docs: autogenerate typescript definitions

Author: wopian

package.json

@@ -19,6 +19,7 @@
     "build": "lerna exec yarn build",
     "docs": "lerna exec --parallel yarn docs:lint",
     "docs:build": "lerna exec --parallel yarn docs:build",
+    "docs:typescript": "lerna exec --parallel yarn docs:typescript",
     "docs:release": "yarn docs && yarn docs:build",
     "fix": "eslint . --fix",
     "lint": "eslint .",
@@ -50,7 +51,8 @@
     "rollup": "~2.10.0",
     "rollup-plugin-local-resolve": "~1.0.7",
     "rollup-plugin-terser": "~5.3.0",
-    "size-limit": "~4.5.0"
+    "size-limit": "~4.5.0",
+    "typescript": "~3.9.3"
   },
   "jest": {
     "testEnvironment": "node",

packages/kitsu-core/index.d.ts

@@ -15,7 +15,7 @@
   "module": "lib/index.mjs",
   "unpkg": "lib/index.browser.js",
   "jsdelivr": "lib/index.browser.js",
-  "types": "index.d.ts",
+  "types": "types/index.d.ts",
   "homepage": "https://github.com/wopian/kitsu/tree/master/packages/kitsu-core#readme",
   "repository": "https://github.com/wopian/kitsu/tree/master/packages/kitsu-core",
   "bugs": {
@@ -34,6 +34,7 @@
   "scripts": {
     "docs:lint": "documentation lint src/index.js",
     "docs:build": "documentation readme src/index.js --section=API -g true --sort-order source",
+    "docs:typescript": "tsc src/index.js --declaration --emitDeclarationOnly --allowJs --outDir types",
     "rollup": "cross-env NODE_ENV=production rollup -c --environment BUILD:production",
     "build": "yarn rollup"
   },

packages/kitsu-core/package.json

@@ -7,7 +7,7 @@ import { error } from '../error'
  * @param {Object} relationship
  * @param {string} relationship.id The relationship ID
  * @param {string} relationship.type The relationship type
- * @returns {Array} The matched includes
+ * @returns {Array<Object>} The matched includes
  *
  * @example
  * const includes = [

packages/kitsu-core/src/filterIncludes/index.js

@@ -106,7 +106,7 @@ function hasID (node) {
  * Handles the Bulk Extension support. See `serialise` for examples.
  *
  * @param {string} type Resource type
- * @param {Array} payload The data
+ * @param {Array<Object>} payload The data
  * @param {string} method Request type (PATCH, POST, DELETE)
  * @param {Object} options Optional configuration for camelCase and pluralisation handling
  * @param {Function} options.camelCaseTypes Convert library-entries and library_entries to libraryEntries (default no conversion). To use parameter, import camel from kitsu-core
@@ -127,7 +127,7 @@ function serialiseRootArray (type, payload, method, options) {
  * Serialises the root data object. See `serialise` for examples.
  *
  * @param {string} type Resource type
- * @param {Array} payload The data
+ * @param {Object} payload The data
  * @param {string} method Request type (PATCH, POST, DELETE)
  * @param {Object} options Optional configuration for camelCase and pluralisation handling
  * @param {Function} options.camelCaseTypes Convert library-entries and library_entries to libraryEntries (default no conversion). To use parameter, import camel from kitsu-core
@@ -164,7 +164,7 @@ function serialiseRootObject (type, payload, method, options) {
  * Serialises an object into a JSON-API structure
  *
  * @param {string} type Resource type
- * @param {Object|Array} data The data
+ * @param {Object|Array<Object>} data The data
  * @param {string} method Request type (PATCH, POST, DELETE)
  * @param {Object} options Optional configuration for camelCase and pluralisation handling
  * @param {Function} options.camelCaseTypes Convert library-entries and library_entries to libraryEntries (default no conversion). To use parameter, import camel from kitsu-core

packages/kitsu-core/src/serialise/index.js

@@ -7,7 +7,7 @@
  * @param {Object} options
  * @param {Function} options.resourceCase Convert libraryEntries to library-entries or library_entries (default no conversion). To use parameter, import kebab or snake from kitsu-core
  * @param {Function} options.pluralModel Pluralise models (default no pluralisation). To use parameter, import pluralize (or another pluralisation npm package)
- * @returns {Array} Array containing the model name and the resource URL with pluralisation applied
+ * @returns {Array<string, string>} Array containing the model name and the resource URL with pluralisation applied
  *
  * @example
  * splitModel('posts/1/comments')

packages/kitsu-core/src/splitModel/index.js

@@ -0,0 +1,2 @@
+declare function _default(s: string): string;
+export default _default;

packages/kitsu-core/types/camel/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hoists attributes to be top-level
+ *
+ * @param {Object|Array} data Resource data
+ * @returns {Object|Array} Deattributed resource data
+ *
+ * @example <caption>Deattribute an array of resources</caption>
+ * // JSON:API 'data' field
+ * const data = [
+ *   {
+ *     id: '1',
+ *     type: 'users',
+ *     attributes: { slug: 'wopian' }
+ *   }
+ * ]
+ *
+ * const output = deattribute(data) // [ { id: '1', type: 'users', slug: 'wopian' } ]
+ *
+ * @example <caption>Deattribute a resource</caption>
+ * // JSON:API 'data' field
+ * const data = {
+ *   id: '1',
+ *   type: 'users',
+ *   attributes: { slug: 'wopian' }
+ * }
+ *
+ * const output = deattribute(data) // { id: '1', type: 'users', slug: 'wopian' }
+ */
+export function deattribute(data: any | Array): any | Array;

packages/kitsu-core/types/deattribute/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Deserialises a JSON-API response
+ *
+ * @param {Object} response The raw JSON:API response object
+ * @returns {Object} The deserialised response
+ *
+ * @example <caption>Deserialise with a basic data object</caption>
+ * deserialise({
+ *   data: {
+ *     id: '1',
+ *     attributes: { liked: true }
+ *   },
+ *   meta: { hello: 'world' }
+ * }) // { data: { id: '1', liked: true }, meta: { hello: 'world' } }
+ *
+ * @example <caption>Deserialise with relationships</caption>
+ * deserialise({
+ *   data: {
+ *     id: '1',
+ *     relationships: {
+ *       user: {
+ *         data: {
+ *           type: 'users',
+ *           id: '2' }
+ *       }
+ *     }
+ *   },
+ *   included: [
+ *     {
+ *       type: 'users',
+ *       id: '2',
+ *       attributes: { slug: 'wopian' }
+ *     }
+ *   ]
+ * }) // { data: { id: '1', user: { type: 'users', id: '2', slug: 'wopian' } } }
+ */
+export function deserialise(response: any): any;

packages/kitsu-core/types/deserialise/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Uniform error handling for Axios, JSON:API and internal package errors. Mutated Error object is rethrown to the caller.
+ *
+ * @param {Object} E The Error
+ * @throws {Object} The mutated Error
+ *
+ * @example
+ * error('Hello')
+ *
+ * @example
+ * error({errors: [ { code: 400 } ]})
+ *
+ * @example
+ * error({
+ *   response: {
+ *     data: {
+ *       errors: [ {
+ *         title: 'Filter is not allowed',
+ *         detail: 'x is not allowed',
+ *         code: '102',
+ *         status: '400'
+ *       } ]
+ *     }
+ *   }
+ * })
+ */
+export function error(E: any): void;