diff --git a/.gitignore b/.gitignore index 44e7bfa..58c974c 100644 --- a/.gitignore +++ b/.gitignore @@ -106,5 +106,3 @@ lib/ # Mac OS artifacts .DS_STORE -# API extractor -ts-japi.api.json diff --git a/Makefile b/Makefile index 4d61e1c..386c05a 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ PATH:=$(PATH):$(PWD)/node_modules/.bin SHELL:=env PATH=$(PATH) /bin/bash -clean: clean-build clean-coverage +clean: clean-lib clean-coverage clean-lib: @echo 'Cleaning build artifacts...' @@ -13,7 +13,5 @@ clean-coverage: .PHONY: all .PHONY: clean -.PHONY: clean-docs -.PHONY: clean-readme .PHONY: clean-lib .PHONY: clean-coverage \ No newline at end of file diff --git a/README.md b/README.md index 02b9a84..ddebbc2 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,6 @@ - [ts:japi](#tsjapi) - [Features](#features) - - [Documentation](#documentation) - [Installation](#installation) - [Getting Started](#getting-started) - [Examples](#examples) @@ -24,6 +23,16 @@ - [Serializing Errors](#serializing-errors) - [Caching](#caching) - [Deserialization](#deserialization) + - [API Reference](#api-reference) + - [Serializer](#serializer) + - [Relator](#relator) + - [Linker](#linker) + - [Metaizer](#metaizer) + - [Paginator](#paginator) + - [ErrorSerializer](#errorserializer) + - [Cache](#cache) + - [PolymorphicSerializer](#polymorphicserializer) + - [JapiError](#japierror) - [Remarks](#remarks) - [FAQ](#faq) - [For Developers](#for-developers) @@ -34,137 +43,83 @@ - This is the **only** typescript-compatible library that fully types the JSON:API specification and performs _proper_ serialization. -- [**Zero dependencies**](#zdg). -- This is the **only** library with [resource recursion](#wirr). +- **Zero dependencies**. +- This is the **only** library with [resource recursion](#faq). - The modular framework laid out here _highly promotes_ the specifications intentions: - Using links is no longer obfuscated. - Meta can truly be placed anywhere with possible dependencies laid out visibly. - This library is designed to adhere to the specifications "never remove, only add" policy, so we will remain backwards-compatible. -## Documentation - -The [documentation](https://mathematic-inc.github.io/ts-japi/) has everything that is covered here -and more. - ## Installation -You can install ts-japi in your project's directory as usual: - ```bash npm install ts-japi ``` ## Getting Started -There are fives classes that are used to serialize data (only one of which is necessarily required). +There are several classes used to serialize data (only `Serializer` is strictly required): -- [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) with - [`SerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html) -- [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) with - [`RelatorOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html) -- [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) with - [`LinkerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html) -- [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) -- [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html) -- [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) with - [`ErrorSerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html) -- [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with - [`CacheOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html) - -You can check the [documentation](https://mathematic-inc.github.io/ts-japi) for a deeper insight -into the usage. +- `Serializer` — primary resource serialization +- `Relator` — relationships and included resources +- `Linker` — document and resource links +- `Metaizer` — metadata at any level +- `Paginator` — pagination links +- `ErrorSerializer` — error serialization +- `Cache` — response caching +- `PolymorphicSerializer` — polymorphic resource serialization ### Examples -You can check the [examples](https://github.com/mathematic-inc/ts-japi/tree/main/examples) and the -[test](https://github.com/mathematic-inc/ts-japi/tree/main/test) folders to see some examples -(such as the ones below). You can check -[this example](https://github.com/mathematic-inc/ts-japi/blob/main/examples/full.example.ts) to -see almost every option of -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) exhausted. +See the [examples](https://github.com/mathematic-inc/ts-japi/tree/main/examples) and +[test](https://github.com/mathematic-inc/ts-japi/tree/main/test) directories for usage. +The [full example](https://github.com/mathematic-inc/ts-japi/blob/main/examples/full.example.ts) +shows nearly every `Serializer` option in use. ## Serialization -The [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) class is the -only class required for basic serialization. - -The following example constructs the most basic -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html): (Note the `await`) +`Serializer` is the only class required for basic serialization. ```typescript -import { Serializer } from '../src'; -import { User } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; +import { Serializer } from 'ts-japi'; const UserSerializer = new Serializer('users'); -(async () => { - const user = new User('sample_user_id'); - - console.log('Output:', getJSON(await UserSerializer.serialize(user))); - - // Output: { - // jsonapi: { version: '1.0' }, - // data: { - // type: 'users', - // id: 'sample_user_id', - // attributes: { - // createdAt: '2020-05-20T15:44:37.650Z', - // articles: [], - // comments: [] - // } - // } - // } -})(); +const user = { id: 'sample_user_id', createdAt: new Date() }; + +console.log(await UserSerializer.serialize(user)); +// { +// jsonapi: { version: '1.0' }, +// data: { +// type: 'users', +// id: 'sample_user_id', +// attributes: { createdAt: '2020-05-20T15:44:37.650Z' } +// } +// } ``` ### Links -The [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) class is used to -generate a normalized [document link](https://jsonapi.org/format/#document-links). Its methods are -not meant to be called. See the [FAQ](#faq) for reasons. - -The following example constructs a -[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) for `User`s and `Article`s: +`Linker` generates normalized [document links](https://jsonapi.org/format/#document-links). Its +methods are not meant to be called directly — pass it to a serializer option. ```typescript -import { Linker } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; +import { Linker } from 'ts-japi'; -// The last argument should almost always be an array or a single object type. -// The reason for this is the potential for linking several articles. const UserArticleLinker = new Linker((user: User, articles: Article | Article[]) => { return Array.isArray(articles) ? `https://www.example.com/users/${user.id}/articles/` : `https://www.example.com/users/${user.id}/articles/${articles.id}`; }); - -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - - console.log('Output:', getJSON(UserArticleLinker.link(user, article))); - - // Output: https://www.example.com/users/sample_user_id/articles/same_article_id -})(); ``` #### Pagination -The [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html) class is used to -generate [pagination links](https://jsonapi.org/format/#fetching-pagination). Its methods are not -meant to be called. - -The following example constructs a -[`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html): +`Paginator` generates [pagination links](https://jsonapi.org/format/#fetching-pagination). ```typescript -import { Paginator } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; +import { Paginator } from 'ts-japi'; const ArticlePaginator = new Paginator((articles: Article | Article[]) => { if (Array.isArray(articles)) { @@ -179,45 +134,17 @@ const ArticlePaginator = new Paginator((articles: Article | Article[]) => { } return; }); - -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - - console.log('Output:', getJSON(ArticlePaginator.paginate([article]))); - - // Output: { - // first: 'https://www.example.com/articles/0', - // last: 'https://www.example.com/articles/10', - // prev: null, - // next: null - // } -})(); ``` +Use it via `SerializerOptions.linkers.paginator`. + ### Relationships -The [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) class is used to -generate top-level [included data](https://jsonapi.org/format/#document-top-level) as well as +`Relator` generates top-level [included data](https://jsonapi.org/format/#document-top-level) and resource-level [relationships](https://jsonapi.org/format/#document-resource-object-relationships). -Its methods are not meant to be called. - -[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html)s may also take optional -[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html)s (using the -[`linker`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#linkers) option) -to define [relationship links](https://jsonapi.org/format/#document-resource-object-relationships) -and -[related resource links](https://jsonapi.org/format/#document-resource-object-related-resource-links). - -The following example constructs a -[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) for `User`s and -`Article`s: ```typescript -import { Serializer, Relator } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; +import { Serializer, Relator } from 'ts-japi'; const ArticleSerializer = new Serializer
('articles'); const UserArticleRelator = new Relator( @@ -225,119 +152,291 @@ const UserArticleRelator = new Relator( ArticleSerializer ); -// ! The rest of this example is just to illustrate some internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - User.save(user); - Article.save(article); - - console.log('Output:', getJSON(await UserArticleRelator.getRelationship(user))); - - // Output: { data: [ { type: 'articles', id: 'same_article_id' } ] } -})(); +const UserSerializer = new Serializer('users', { + relators: UserArticleRelator, +}); ``` -### Metadata +`Relator` also accepts optional `Linker`s via the `linkers` option to define relationship and +related resource links. -The [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) class is used to -construct generate metadata given some dependencies. There are several locations -[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) can be used: - -- [`ErrorSerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#metaizers) -- [`RelatorOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#metaizer) -- [`SerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#metaizers) -- [`LinkerOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html#metaizer) +### Metadata -Like [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html), its methods are not -meant to be called. +`Metaizer` generates metadata. It can be used in: -The following example constructs a -[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html): +- `ErrorSerializerOptions.metaizers` +- `RelatorOptions.metaizer` +- `SerializerOptions.metaizers` +- `LinkerOptions.metaizer` ```typescript -import { User, Article } from '../test/models'; -import { Metaizer } from '../src'; -import { getJSON } from '../test/utils/get-json'; +import { Metaizer } from 'ts-japi'; -// The last argument should almost always be an array or a single object type. -// The reason for this is the potential for metaizing several articles. const UserArticleMetaizer = new Metaizer((user: User, articles: Article | Article[]) => { return Array.isArray(articles) ? { user_created: user.createdAt, article_created: articles.map((a) => a.createdAt) } : { user_created: user.createdAt, article_created: articles.createdAt }; }); +``` + +### Serializing Errors -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); +`ErrorSerializer` serializes any object as an error. Alternatively (recommended), extend `JapiError` +to construct typed server errors. - console.log('Output:', getJSON(UserArticleMetaizer.metaize(user, article))); +```typescript +import { ErrorSerializer } from 'ts-japi'; + +const PrimitiveErrorSerializer = new ErrorSerializer(); - // Output: { - // user_created: '2020-05-20T15:39:43.277Z', - // article_created: '2020-05-20T15:39:43.277Z' - // } -})(); +console.log(PrimitiveErrorSerializer.serialize(new Error('badness'))); +// { +// errors: [ { code: 'Error', detail: 'badness' } ], +// jsonapi: { version: '1.0' } +// } ``` -### Serializing Errors +### Caching -The [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) class -is used to serialize any object considered an error (the -[`attributes`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#attributes) -option allows you to choose what attributes to use during serialization). _Alternatively_ -(**recommended**), you can construct custom errors by extending the -[`JapiError`](https://mathematic-inc.github.io/ts-japi/classes/japierror.html) class and use those -for all server-to-client errors. +Set `cache: true` in `SerializerOptions` for a default `Cache`, or pass a `Cache` instance for +custom equality logic. -The -[error serializer test](https://github.com/mathematic-inc/ts-japi/tree/main/test/error-serializer.test.ts) -includes an example of the alternative solution. +```typescript +import { Serializer, Cache } from 'ts-japi'; -The following example constructs the most basic -[`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html): (Note -the lack of `await`) +const MyCache = new Cache({ resolver: (a, b) => a?.id === b?.id }); +const UserSerializer = new Serializer('users', { cache: MyCache }); +``` + +## Deserialization + +This library does not provide deserialization. Many clients already consume JSON:API endpoints (see +[implementations](https://jsonapi.org/implementations/)), and unmarshalling data is typically +coupled to framework-specific code (e.g. React state). Tighter integration is recommended over an +unnecessary abstraction. + +## API Reference + +### Serializer + +```typescript +new Serializer(collectionName: string, options?: Partial>) +``` + +**Methods:** + +| Method | Description | +|---|---| +| `serialize(data, options?)` | Serializes primary data. Returns a `Promise`. | +| `getRelators()` | Returns the relators associated with this serializer. | +| `setRelators(relators)` | Sets relators (useful for breaking cyclic dependencies). | +| `getIdKeyFieldName()` | Returns the name of the id field. | + +**`SerializerOptions`:** + +| Option | Type | Default | Description | +|---|---|---|---| +| `idKey` | `keyof PrimaryType` | `"id"` | The field name for the resource ID. | +| `version` | `string \| null` | `"1.0"` | JSON:API version. Set to `null` to omit. | +| `relators` | `Relator \| Relator[] \| Record` | — | Relators that generate relationships and included resources. | +| `linkers.document` | `Linker` | — | Linker for the top-level self link. | +| `linkers.resource` | `Linker` | — | Linker for the resource-level self link. | +| `linkers.paginator` | `Paginator` | — | Paginator for pagination links. | +| `metaizers.jsonapi` | `Metaizer` | — | Metadata for the JSON:API object. | +| `metaizers.document` | `Metaizer` | — | Metadata for the top-level document. | +| `metaizers.resource` | `Metaizer` | — | Metadata for each resource object. | +| `include` | `number \| string[]` | `0` | Which relationships to include. A number includes all relationships up to that depth. An array of paths includes only those paths (e.g. `['articles', 'articles.comments']`). Takes precedence over `depth`. | +| `depth` | `number` | `0` | Depth of relators to recurse for included resources. Deprecated — use `include` instead. | +| `projection` | `Partial> \| null \| undefined` | `null` | Attribute projection. All 0s to hide, all 1s to show. `null` shows all. `undefined` omits `attributes`. | +| `cache` | `boolean \| Cache` | `false` | Enables response caching. | +| `onlyIdentifier` | `boolean` | `false` | Serializes only resource identifier objects (no attributes). | +| `onlyRelationship` | `string` | `false` | Serializes only the relationship linkage for the named relator. | +| `nullData` | `boolean` | `false` | Forces `data` to be `null`. | +| `asIncluded` | `boolean` | `false` | Moves primary data to `included` and uses identifier objects for `data`. | + +### Relator ```typescript -import { ErrorSerializer } from '../src'; -import { getJSON } from '../test/utils/get-json'; +new Relator( + fetch: (data: PrimaryType) => Promise, + serializer: Serializer | (() => Serializer), + options?: Partial> +) +``` -const PrimitiveErrorSerializer = new ErrorSerializer(); +Passing a getter function `() => Serializer` instead of a `Serializer` instance breaks circular +references between serializers. When using a getter, `options.relatedName` is required. -(async () => { - const error = new Error('badness'); +**`RelatorOptions`:** - console.log('Output:', getJSON(PrimitiveErrorSerializer.serialize(error))); +| Option | Type | Description | +|---|---|---| +| `linkers.relationship` | `Linker<[PrimaryType, RelatedType \| RelatedType[] \| null \| undefined]>` | Linker for the relationship self link. | +| `linkers.related` | `Linker<[PrimaryType, RelatedType \| RelatedType[] \| null \| undefined]>` | Linker for the related resource link. | +| `metaizer` | `Metaizer<[PrimaryType, RelatedType \| RelatedType[] \| null \| undefined]>` | Metaizer for relationship metadata. | +| `relatedName` | `string` | Override for the relationship name (defaults to the serializer's collection name). Required when passing a serializer getter. | - // Output: { - // errors: [ { code: 'Error', detail: 'badness' } ], - // jsonapi: { version: '1.0' } - // } -})(); +### Linker + +```typescript +new Linker( + link: (...args: Dependencies) => string, + options?: LinkerOptions +) +// where Dependencies extends any[] ``` -### Caching +**`LinkerOptions`:** -The [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) class can be placed in a -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html)'s -[`cache`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#cache) option. -Alternatively, setting that option to `true` will provide a default -[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html). +| Option | Type | Description | +|---|---|---| +| `metaizer` | `Metaizer` | Adds meta to the link object. | -The default [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) uses the basic -[`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) -function to determine if input data are the same. If you want to adjust this, instantiate a new -[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with a -[`resolver`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html#resolver). +### Metaizer -## Deserialization +```typescript +new Metaizer( + metaize: (...args: Dependencies) => Record | Promise> +) +// where Dependencies extends any[] +``` + +### Paginator + +```typescript +new Paginator( + paginate: (data: DataType | DataType[]) => { + first?: string | null; + last?: string | null; + prev?: string | null; + next?: string | null; + } | undefined +) +``` + +The callback returns an object with optional `first`, `last`, `prev`, `next` string URLs (or `null` +to explicitly omit a link). + +### ErrorSerializer + +```typescript +new ErrorSerializer(options?: Partial>) +``` + +**Methods:** + +| Method | Description | +|---|---| +| `serialize(errors, options?)` | Serializes one or more errors synchronously. Returns an `ErrorDocument`. | + +By default, `ErrorSerializer` maps fields from standard `Error` objects: + +| Error field | JSON:API field | +|---|---| +| `name` | `code` | +| `message` | `detail` | +| `id` | `id` | +| `code` | `status` | +| `reason` | `title` | +| `location` | `source.pointer` | + +**`ErrorSerializerOptions`:** + +| Option | Type | Description | +|---|---|---| +| `attributes.id` | `keyof ErrorType` | Field to use for error id. Default: `"id"` | +| `attributes.status` | `keyof ErrorType` | Field to use for HTTP status. Default: `"code"` | +| `attributes.code` | `keyof ErrorType` | Field to use for error code. Default: `"name"` | +| `attributes.title` | `keyof ErrorType` | Field to use for error title. Default: `"reason"` | +| `attributes.detail` | `keyof ErrorType` | Field to use for error detail. Default: `"message"` | +| `attributes.source.pointer` | `keyof ErrorType` | Field for JSON Pointer source. Default: `"location"` | +| `attributes.source.parameter` | `keyof ErrorType` | Field for query parameter source. Default: `undefined` | +| `attributes.source.header` | `keyof ErrorType` | Field for header source. Default: `undefined` | +| `linkers.about` | `Linker<[JapiError]>` | Linker for the error about link. | +| `metaizers.jsonapi` | `Metaizer<[]>` | Metadata for the JSON:API object. | +| `metaizers.document` | `Metaizer<[JapiError[]]>` | Metadata for the top-level document. | +| `metaizers.error` | `Metaizer<[JapiError]>` | Metadata for each error object. | +| `version` | `string \| null` | JSON:API version. Default: `"1.0"` | + +### Cache + +```typescript +new Cache(options?: Partial>) +``` + +**`CacheOptions`:** + +| Option | Type | Default | Description | +|---|---|---|---| +| `limit` | `number` | `10` | Maximum number of documents to store before evicting the oldest. | +| `resolver` | `(stored, incoming) => boolean` | `Object.is` | Equality function to determine cache hits. | + +### PolymorphicSerializer + +Serializes a mixed array of resources that share a common discriminant field. Each type is routed to +its own `Serializer`. + +```typescript +new PolymorphicSerializer( + commonName: string, + key: keyof PrimaryType, + serializers: Record | Record Serializer> +) +``` + +**Example:** + +```typescript +import { PolymorphicSerializer, Serializer } from 'ts-japi'; + +const DogSerializer = new Serializer('dogs'); +const CatSerializer = new Serializer('cats'); + +const AnimalSerializer = new PolymorphicSerializer('animals', 'type', { + dog: DogSerializer, + cat: CatSerializer, +}); + +const animals = [ + { id: '1', type: 'dog', name: 'Rex' }, + { id: '2', type: 'cat', name: 'Whiskers' }, +]; + +console.log(await AnimalSerializer.serialize(animals)); +``` + +### JapiError + +Extend `JapiError` to create typed errors that pass through `ErrorSerializer` unchanged. + +```typescript +import { JapiError, ErrorSerializer } from 'ts-japi'; + +class NotFoundError extends JapiError { + constructor(id: string) { + super({ status: '404', code: 'NOT_FOUND', title: 'Not Found', detail: `Resource ${id} not found` }); + } +} + +const serializer = new ErrorSerializer(); +console.log(serializer.serialize(new NotFoundError('42'))); +// { errors: [{ status: '404', code: 'NOT_FOUND', title: 'Not Found', detail: 'Resource 42 not found' }], jsonapi: { version: '1.0' } } +``` -We stress the following: Given that there are many clients readily built to consume JSON:API -endpoints (see [here](https://jsonapi.org/implementations/)), we do not provide deserialization. In -particular, since unmarshalling data is strongly related to the code it will be used in (e.g. -React), tighter integration is recommended over an unnecessary abstraction. +**`JapiError` fields:** + +| Field | Type | Description | +|---|---|---| +| `id` | `string` | Unique identifier for this error occurrence. | +| `status` | `string` | HTTP status code as a string. | +| `code` | `string` | Application-specific error code. | +| `title` | `string` | Short, human-readable summary (should not change between occurrences). | +| `detail` | `string` | Human-readable explanation of this specific occurrence. | +| `source.pointer` | `string` | JSON Pointer to the source field (e.g. `/data/attributes/name`). | +| `source.parameter` | `string` | Query parameter that caused the error. | +| `source.header` | `string` | Request header that caused the error. | +| `links` | `object` | Links object (e.g. `about` link). | +| `meta` | `object` | Non-standard meta information. | ## Remarks @@ -360,21 +459,19 @@ whenever the specs change. In case the specification is updated to change the meta objects in some functional way. -> What is "resource recursion"? +> What is "resource recursion"? Due to [compound documents](https://jsonapi.org/format/#document-compound-documents), it is possible to recurse through related resources via their [resource linkages](https://jsonapi.org/format/#document-resource-object-linkage) and obtain [included resources](https://jsonapi.org/format/#document-top-level) beyond primary data relations. -This is should be done with caution (see -[`SerializerOptions.depth`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#depth) -and -[this example](https://github.com/mathematic-inc/ts-japi/blob/main/examples/resource-recursion.example.ts)) +Use the `include` or `depth` option on `Serializer` with caution — deep recursion can degrade +performance significantly. ## For Developers -To get started in developing this library, run `yarn install`, `yarn build` and `yarn test` (in this -precise order) to assure everything is in working order. +To get started in developing this library, run `pnpm install`, `pnpm build` and `pnpm test` (in +this precise order) to assure everything is in working order. ## Contributing @@ -383,8 +480,7 @@ find TS:JAPI on GitHub: [https://github.com/mathematic-inc/ts-japi](https://github.com/mathematic-inc/ts-japi) Feel free to submit an issue, but please do not submit pull requests unless it is to fix some issue. -For more information, read the -[contribution guide](https://github.com/mathematic-inc/ts-japi/blob/main/CONTRIBUTING.html). +Feel free to open an issue if you find a bug. ## License diff --git a/api-extractor.json b/api-extractor.json deleted file mode 100644 index 0302579..0000000 --- a/api-extractor.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", - "mainEntryPointFilePath": "/lib/index.d.ts", - "apiReport": { - "enabled": false - }, - "docModel": { - "enabled": true, - "apiJsonFilePath": "/docs/.api.json" - }, - "dtsRollup": { - "enabled": false - } -} diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index ea4e452..0000000 --- a/docs/api/index.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -sidebar_label: API ---- - -# API Reference - -## Classes - -| Class | Description | -| ----------------------------------------------- | ------------------------------------------------------------ | -| [Cache_2](./ts-japi.cache_2.md) | | -| [ErrorSerializer](./ts-japi.errorserializer.md) |

The class is used to serialize errors.

Example:

| - -```typescript -[[include:error-serializer.example.ts]] -``` - -| | [JapiError](./ts-japi.japierror.md) | | | [Linker](./ts-japi.linker.md) |

The class is used -to construct a \[link\](https://jsonapi.org/format/\#document-links).

Example:

- -```typescript -[[include:linker.example.ts]] -``` - -| | [Metaizer](./ts-japi.metaizer.md) |

The class is used to construct \[meta -information\](https://jsonapi.org/format/\#document-meta).

Example:

- -```typescript -[[include:metaizer.example.ts]] -``` - -| | [Paginator](./ts-japi.paginator.md) |

The class is used to construct \[pagination -links\](https://jsonapi.org/format/\#fetching-pagination).

Example:

- -```typescript -[[include:paginator.example.ts]] -``` - -| | [Relator](./ts-japi.relator.md) |

The class is used to generate top-level \[included -data\](https://jsonapi.org/format/\#document-top-level) as well as resource-level -\[relationships\](https://jsonapi.org/format/\#document-resource-object-relationships).

Example:

- -```typescript -[[include:relator.example.ts]] -``` - -| | [Serializer](./ts-japi.serializer.md) |

The class is the main class used to serializer data -(you can use the class to serialize errors).

Example:

- -```typescript -[[include:serializer.example.ts]] -``` - -| - -## Functions - -| Function | Description | -| --------------------------------------------------------- | ------------------------------------------------- | -| [isErrorDocument(document)](./ts-japi.iserrordocument.md) | Detects an ErrorDocument like object | -| [isObject(o)](./ts-japi.isobject.md) | | -| [isPlainObject(o)](./ts-japi.isplainobject.md) | | - -## Interfaces - -| Interface | Description | -| ------------------------------------------------------------- | ----------- | -| [BaseDocument](./ts-japi.basedocument.md) | | -| [CacheOptions](./ts-japi.cacheoptions.md) | | -| [DataDocument](./ts-japi.datadocument.md) | | -| [ErrorAttributeOption](./ts-japi.errorattributeoption.md) | | -| [ErrorDocument](./ts-japi.errordocument.md) | | -| [ErrorOptions](./ts-japi.erroroptions.md) | | -| [ErrorSerializerOptions](./ts-japi.errorserializeroptions.md) | | -| [ErrorSource](./ts-japi.errorsource.md) | | -| [ErrorSourceAttribute](./ts-japi.errorsourceattribute.md) | | -| [JSONAPIObject](./ts-japi.jsonapiobject.md) | | -| [LinkerOptions](./ts-japi.linkeroptions.md) | | -| [MetaDocument](./ts-japi.metadocument.md) | | -| [PaginationOf](./ts-japi.paginationof.md) | | -| [RelatorOptions](./ts-japi.relatoroptions.md) | | -| [SerializerOptions](./ts-japi.serializeroptions.md) | | - -## Type Aliases - -| Type Alias | Description | -| ------------------------------------------------------- | -------------------------------------------------------------------- | -| [Dictionary](./ts-japi.dictionary.md) | | -| [nullish](./ts-japi.nullish.md) | | -| [PrimaryData](./ts-japi.primarydata.md) | | -| [ResourceLinkage](./ts-japi.resourcelinkage.md) | | -| [SingleOrArray](./ts-japi.singleorarray.md) | A utility type for describing a single object or an array of objects | -| [UnionToIntersection](./ts-japi.uniontointersection.md) | | -| [VariadicFunction](./ts-japi.variadicfunction.md) | A function that takes several arguments and outputs something. | diff --git a/docs/api/ts-japi.basedocument.jsonapi.md b/docs/api/ts-japi.basedocument.jsonapi.md deleted file mode 100644 index 2ab29b0..0000000 --- a/docs/api/ts-japi.basedocument.jsonapi.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: BaseDocument.jsonapi ---- - -# BaseDocument.jsonapi property - -**Signature:** - -```typescript -interface BaseDocument { - jsonapi?: JSONAPIObject; -} -``` diff --git a/docs/api/ts-japi.basedocument.md b/docs/api/ts-japi.basedocument.md deleted file mode 100644 index 0cd275e..0000000 --- a/docs/api/ts-japi.basedocument.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: BaseDocument ---- - -# BaseDocument interface - -**Signature:** - -```typescript -export interface BaseDocument -``` - -## Properties - -| Property | Modifiers | Type | Description | -| --------------------------------------------- | --------- | ------------------------------------------- | ----------------- | -| [jsonapi?](./ts-japi.basedocument.jsonapi.md) | | [JSONAPIObject](./ts-japi.jsonapiobject.md) | (Optional) | diff --git a/docs/api/ts-japi.cache_2._constructor_.md b/docs/api/ts-japi.cache_2._constructor_.md deleted file mode 100644 index 1f261db..0000000 --- a/docs/api/ts-japi.cache_2._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: Cache_2.(constructor) ---- - -# Cache_2.(constructor) - -Creates a - -**Signature:** - -```typescript -class Cache_2 { - constructor(options?: Partial>); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | --------------------------------------------------------------------------- | ----------------- | -| options | Partial<[CacheOptions](./ts-japi.cacheoptions.md)<PrimaryType>> | (Optional) | diff --git a/docs/api/ts-japi.cache_2.defaultlimit.md b/docs/api/ts-japi.cache_2.defaultlimit.md deleted file mode 100644 index 6670ea8..0000000 --- a/docs/api/ts-japi.cache_2.defaultlimit.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: Cache_2.defaultLimit ---- - -# Cache_2.defaultLimit property - -The default max for document storage - -**Signature:** - -```typescript -class Cache_2 { - static defaultLimit: number; -} -``` diff --git a/docs/api/ts-japi.cache_2.md b/docs/api/ts-japi.cache_2.md deleted file mode 100644 index 87a2674..0000000 --- a/docs/api/ts-japi.cache_2.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: Cache_2 ---- - -# Cache_2 class - -**Signature:** - -```typescript -export default class Cache -``` - -## Constructors - -| Constructor | Modifiers | Description | -| ------------------------------------------------------------ | --------- | ----------- | -| [(constructor)(options)](./ts-japi.cache_2._constructor_.md) | | Creates a | - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------- | ------------------- | ------ | ------------------------------------ | -| [defaultLimit](./ts-japi.cache_2.defaultlimit.md) | static | number | The default max for document storage | diff --git a/docs/api/ts-japi.cacheoptions.limit.md b/docs/api/ts-japi.cacheoptions.limit.md deleted file mode 100644 index 4c2c8f4..0000000 --- a/docs/api/ts-japi.cacheoptions.limit.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: CacheOptions.limit ---- - -# CacheOptions.limit property - -The maximum amount of documents that can be stored before erasure. - -`10` - -**Signature:** - -```typescript -interface CacheOptions { - limit: number; -} -``` diff --git a/docs/api/ts-japi.cacheoptions.md b/docs/api/ts-japi.cacheoptions.md deleted file mode 100644 index a071cd4..0000000 --- a/docs/api/ts-japi.cacheoptions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: CacheOptions ---- - -# CacheOptions interface - -**Signature:** - -```typescript -export interface CacheOptions -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ---------------------------------------- | --------- | ------ | ------------------------------------------------------------------------------------------------ | -| [limit](./ts-japi.cacheoptions.limit.md) | | number |

The maximum amount of documents that can be stored before erasure.

10

| - -## Methods - -| Method | Description | -| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| [resolver(storedData, newData)](./ts-japi.cacheoptions.resolver.md) |

The method to use in determining data equality

Object.is

| diff --git a/docs/api/ts-japi.cacheoptions.resolver.md b/docs/api/ts-japi.cacheoptions.resolver.md deleted file mode 100644 index 47a614c..0000000 --- a/docs/api/ts-japi.cacheoptions.resolver.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_label: CacheOptions.resolver ---- - -# CacheOptions.resolver() method - -The method to use in determining data equality - -`Object.is` - -**Signature:** - -```typescript -interface CacheOptions { - resolver( - storedData: SingleOrArray | nullish, - newData: SingleOrArray | nullish - ): boolean; -} -``` - -## Parameters - -| Parameter | Type | Description | -| ---------- | ---------------------------------------------------------------------------------------------- | ----------- | -| storedData | [SingleOrArray](./ts-japi.singleorarray.md)<DataType> \| [nullish](./ts-japi.nullish.md) | | -| newData | [SingleOrArray](./ts-japi.singleorarray.md)<DataType> \| [nullish](./ts-japi.nullish.md) | | - -**Returns:** - -boolean diff --git a/docs/api/ts-japi.datadocument.data.md b/docs/api/ts-japi.datadocument.data.md deleted file mode 100644 index bfbc3c8..0000000 --- a/docs/api/ts-japi.datadocument.data.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: DataDocument.data ---- - -# DataDocument.data property - -**Signature:** - -```typescript -interface DataDocument { - data: PrimaryData; -} -``` diff --git a/docs/api/ts-japi.datadocument.included.md b/docs/api/ts-japi.datadocument.included.md deleted file mode 100644 index 0f3367b..0000000 --- a/docs/api/ts-japi.datadocument.included.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: DataDocument.included ---- - -# DataDocument.included property - -**Signature:** - -```typescript -interface DataDocument { - included?: Resource[]; -} -``` diff --git a/docs/api/ts-japi.datadocument.links.md b/docs/api/ts-japi.datadocument.links.md deleted file mode 100644 index 3668649..0000000 --- a/docs/api/ts-japi.datadocument.links.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: DataDocument.links ---- - -# DataDocument.links property - -**Signature:** - -```typescript -interface DataDocument { - links?: Dictionary | PaginationOf; -} -``` diff --git a/docs/api/ts-japi.datadocument.md b/docs/api/ts-japi.datadocument.md deleted file mode 100644 index 6417dfc..0000000 --- a/docs/api/ts-japi.datadocument.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: DataDocument ---- - -# DataDocument interface - -**Signature:** - -```typescript -export interface DataDocument> extends Partial -``` - -**Extends:** Partial<[MetaDocument](./ts-japi.metadocument.md) - -## Properties - -| Property | Modifiers | Type | Description | -| ----------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -| [data](./ts-japi.datadocument.data.md) | | [PrimaryData](./ts-japi.primarydata.md)<PrimaryType> | | -| [included?](./ts-japi.datadocument.included.md) | | Resource\[\] | (Optional) | -| [links?](./ts-japi.datadocument.links.md) | | [Dictionary](./ts-japi.dictionary.md)<Link \| [nullish](./ts-japi.nullish.md)> \| [PaginationOf](./ts-japi.paginationof.md)<Link> | (Optional) | diff --git a/docs/api/ts-japi.dictionary.md b/docs/api/ts-japi.dictionary.md deleted file mode 100644 index 5d5133e..0000000 --- a/docs/api/ts-japi.dictionary.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: Dictionary ---- - -# Dictionary type - -**Signature:** - -```typescript -export declare type Dictionary = Record; -``` diff --git a/docs/api/ts-japi.errorattributeoption.code.md b/docs/api/ts-japi.errorattributeoption.code.md deleted file mode 100644 index e7efdba..0000000 --- a/docs/api/ts-japi.errorattributeoption.code.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.code ---- - -# ErrorAttributeOption.code property - -An application-specific error code. - -`"name"` - -**Signature:** - -```typescript -interface ErrorAttributeOption { - code: keyof T; -} -``` diff --git a/docs/api/ts-japi.errorattributeoption.detail.md b/docs/api/ts-japi.errorattributeoption.detail.md deleted file mode 100644 index d72fd3f..0000000 --- a/docs/api/ts-japi.errorattributeoption.detail.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.detail ---- - -# ErrorAttributeOption.detail property - -A human-readable explanation specific to this occurrence of the problem. Like title, this field’s -value can be localized. - -`"message"` - -**Signature:** - -```typescript -interface ErrorAttributeOption { - detail: keyof T; -} -``` diff --git a/docs/api/ts-japi.errorattributeoption.id.md b/docs/api/ts-japi.errorattributeoption.id.md deleted file mode 100644 index e2b44a7..0000000 --- a/docs/api/ts-japi.errorattributeoption.id.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.id ---- - -# ErrorAttributeOption.id property - -A unique identifier for this particular occurrence of the problem. - -`"id"` - -**Signature:** - -```typescript -interface ErrorAttributeOption { - id: keyof T; -} -``` diff --git a/docs/api/ts-japi.errorattributeoption.md b/docs/api/ts-japi.errorattributeoption.md deleted file mode 100644 index 4661bab..0000000 --- a/docs/api/ts-japi.errorattributeoption.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption ---- - -# ErrorAttributeOption interface - -**Signature:** - -```typescript -export interface ErrorAttributeOption -``` - -## Properties - -| Property | Modifiers | Type | Description | -| -------------------------------------------------- | --------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [code](./ts-japi.errorattributeoption.code.md) | | keyof T |

An application-specific error code.

"name"

| -| [detail](./ts-japi.errorattributeoption.detail.md) | | keyof T |

A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

"message"

| -| [id](./ts-japi.errorattributeoption.id.md) | | keyof T |

A unique identifier for this particular occurrence of the problem.

"id"

| -| [source](./ts-japi.errorattributeoption.source.md) | | Partial<[ErrorSourceAttribute](./ts-japi.errorsourceattribute.md)<T>> | An object containing references to the source of the error, optionally including any of the following members. | -| [status](./ts-japi.errorattributeoption.status.md) | | keyof T |

The HTTP status code applicable to this problem.

"code"

| -| [title](./ts-japi.errorattributeoption.title.md) | | keyof T |

A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

"reason"

| diff --git a/docs/api/ts-japi.errorattributeoption.source.md b/docs/api/ts-japi.errorattributeoption.source.md deleted file mode 100644 index 0e812be..0000000 --- a/docs/api/ts-japi.errorattributeoption.source.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.source ---- - -# ErrorAttributeOption.source property - -An object containing references to the source of the error, optionally including any of the -following members. - -**Signature:** - -```typescript -interface ErrorAttributeOption { - source: Partial>; -} -``` diff --git a/docs/api/ts-japi.errorattributeoption.status.md b/docs/api/ts-japi.errorattributeoption.status.md deleted file mode 100644 index e76480b..0000000 --- a/docs/api/ts-japi.errorattributeoption.status.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.status ---- - -# ErrorAttributeOption.status property - -The HTTP status code applicable to this problem. - -`"code"` - -**Signature:** - -```typescript -interface ErrorAttributeOption { - status: keyof T; -} -``` diff --git a/docs/api/ts-japi.errorattributeoption.title.md b/docs/api/ts-japi.errorattributeoption.title.md deleted file mode 100644 index 94c348b..0000000 --- a/docs/api/ts-japi.errorattributeoption.title.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorAttributeOption.title ---- - -# ErrorAttributeOption.title property - -A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence -of the problem, except for purposes of localization. - -`"reason"` - -**Signature:** - -```typescript -interface ErrorAttributeOption { - title: keyof T; -} -``` diff --git a/docs/api/ts-japi.errordocument.errors.md b/docs/api/ts-japi.errordocument.errors.md deleted file mode 100644 index 36e6ca2..0000000 --- a/docs/api/ts-japi.errordocument.errors.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: ErrorDocument.errors ---- - -# ErrorDocument.errors property - -**Signature:** - -```typescript -interface ErrorDocument { - errors: JapiError[]; -} -``` diff --git a/docs/api/ts-japi.errordocument.md b/docs/api/ts-japi.errordocument.md deleted file mode 100644 index 76d0704..0000000 --- a/docs/api/ts-japi.errordocument.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: ErrorDocument ---- - -# ErrorDocument interface - -**Signature:** - -```typescript -export interface ErrorDocument extends Partial -``` - -**Extends:** Partial<[MetaDocument](./ts-japi.metadocument.md) - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------- | --------- | ------------- | ----------- | -| [errors](./ts-japi.errordocument.errors.md) | | JapiError\[\] | | diff --git a/docs/api/ts-japi.erroroptions.code.md b/docs/api/ts-japi.erroroptions.code.md deleted file mode 100644 index 48f2298..0000000 --- a/docs/api/ts-japi.erroroptions.code.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: ErrorOptions.code ---- - -# ErrorOptions.code property - -An application-specific error code. - -**Signature:** - -```typescript -interface ErrorOptions { - code?: string; -} -``` diff --git a/docs/api/ts-japi.erroroptions.detail.md b/docs/api/ts-japi.erroroptions.detail.md deleted file mode 100644 index 5369bf9..0000000 --- a/docs/api/ts-japi.erroroptions.detail.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: ErrorOptions.detail ---- - -# ErrorOptions.detail property - -A human-readable explanation specific to this occurrence of the problem. Like title, this field’s -value can be localized. - -**Signature:** - -```typescript -interface ErrorOptions { - detail?: string; -} -``` diff --git a/docs/api/ts-japi.erroroptions.id.md b/docs/api/ts-japi.erroroptions.id.md deleted file mode 100644 index a19fea1..0000000 --- a/docs/api/ts-japi.erroroptions.id.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: ErrorOptions.id ---- - -# ErrorOptions.id property - -A unique identifier for this particular occurrence of the problem. - -**Signature:** - -```typescript -interface ErrorOptions { - id?: string; -} -``` diff --git a/docs/api/ts-japi.erroroptions.md b/docs/api/ts-japi.erroroptions.md deleted file mode 100644 index 332bb5c..0000000 --- a/docs/api/ts-japi.erroroptions.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_label: ErrorOptions ---- - -# ErrorOptions interface - -**Signature:** - -```typescript -export interface ErrorOptions -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------- | --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [code?](./ts-japi.erroroptions.code.md) | | string | (Optional) An application-specific error code. | -| [detail?](./ts-japi.erroroptions.detail.md) | | string | (Optional) A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. | -| [id?](./ts-japi.erroroptions.id.md) | | string | (Optional) A unique identifier for this particular occurrence of the problem. | -| [source?](./ts-japi.erroroptions.source.md) | | [ErrorSource](./ts-japi.errorsource.md) | (Optional) An object containing references to the source of the error, optionally including any of the following members. | -| [status?](./ts-japi.erroroptions.status.md) | | number \| string | (Optional) The HTTP status code applicable to this problem. | -| [title?](./ts-japi.erroroptions.title.md) | | string | (Optional) A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. | diff --git a/docs/api/ts-japi.erroroptions.source.md b/docs/api/ts-japi.erroroptions.source.md deleted file mode 100644 index 66408d7..0000000 --- a/docs/api/ts-japi.erroroptions.source.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: ErrorOptions.source ---- - -# ErrorOptions.source property - -An object containing references to the source of the error, optionally including any of the -following members. - -**Signature:** - -```typescript -interface ErrorOptions { - source?: ErrorSource; -} -``` diff --git a/docs/api/ts-japi.erroroptions.status.md b/docs/api/ts-japi.erroroptions.status.md deleted file mode 100644 index 8537252..0000000 --- a/docs/api/ts-japi.erroroptions.status.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: ErrorOptions.status ---- - -# ErrorOptions.status property - -The HTTP status code applicable to this problem. - -**Signature:** - -```typescript -interface ErrorOptions { - status?: number | string; -} -``` diff --git a/docs/api/ts-japi.erroroptions.title.md b/docs/api/ts-japi.erroroptions.title.md deleted file mode 100644 index dd39c96..0000000 --- a/docs/api/ts-japi.erroroptions.title.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: ErrorOptions.title ---- - -# ErrorOptions.title property - -A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence -of the problem, except for purposes of localization. - -**Signature:** - -```typescript -interface ErrorOptions { - title?: string; -} -``` diff --git a/docs/api/ts-japi.errorserializer._constructor_.md b/docs/api/ts-japi.errorserializer._constructor_.md deleted file mode 100644 index c1a52f5..0000000 --- a/docs/api/ts-japi.errorserializer._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: ErrorSerializer.(constructor) ---- - -# ErrorSerializer.(constructor) - -Creates a . - -**Signature:** - -```typescript -class ErrorSerializer { - constructor(options?: Partial>); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | --------------------------------------------------------------------------------------------- | --------------------------------------------- | -| options | Partial<[ErrorSerializerOptions](./ts-japi.errorserializeroptions.md)<ErrorType>> | (Optional) Options for the serializer. | diff --git a/docs/api/ts-japi.errorserializer.defaultoptions.md b/docs/api/ts-japi.errorserializer.defaultoptions.md deleted file mode 100644 index 9a45d95..0000000 --- a/docs/api/ts-japi.errorserializer.defaultoptions.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -sidebar_label: ErrorSerializer.defaultOptions ---- - -# ErrorSerializer.defaultOptions property - -Default options. Can be edited to change default options globally. - -**Signature:** - -```typescript -class ErrorSerializer { - static defaultOptions: { - version: string; - attributes: { - id: string; - status: string; - code: string; - title: string; - detail: string; - source: { - pointer: string; - parameter: undefined; - header: undefined; - }; - }; - metaizers: {}; - linkers: {}; - }; -} -``` diff --git a/docs/api/ts-japi.errorserializer.md b/docs/api/ts-japi.errorserializer.md deleted file mode 100644 index b58dd2b..0000000 --- a/docs/api/ts-japi.errorserializer.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -sidebar_label: ErrorSerializer ---- - -# ErrorSerializer class - -The class is used to serialize errors. - -Example: - -```typescript -[[include:error-serializer.example.ts]] -``` - -**Signature:** - -```typescript -export default class ErrorSerializer -``` - -## Constructors - -| Constructor | Modifiers | Description | -| -------------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(options)](./ts-japi.errorserializer._constructor_.md) | | Creates a . | - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| [defaultOptions](./ts-japi.errorserializer.defaultoptions.md) | static | { version: string; attributes: { id: string; status: string; code: string; title: string; detail: string; source: { pointer: string; parameter: undefined; header: undefined; }; }; metaizers: {}; linkers: {}; } | Default options. Can be edited to change default options globally. | - -## Methods - -| Method | Modifiers | Description | -| -------------------------------------------------------------------- | --------- | ---------------------------------- | -| [serialize(errors, options)](./ts-japi.errorserializer.serialize.md) | | The actual serialization function. | diff --git a/docs/api/ts-japi.errorserializer.serialize.md b/docs/api/ts-japi.errorserializer.serialize.md deleted file mode 100644 index 624bf61..0000000 --- a/docs/api/ts-japi.errorserializer.serialize.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_label: ErrorSerializer.serialize ---- - -# ErrorSerializer.serialize() method - -The actual serialization function. - -**Signature:** - -```typescript -class ErrorSerializer { - serialize( - errors: SingleOrArray, - options?: Partial> - ): ErrorDocument; -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | --------------------------------------------------------------------------------------------- | -------------------------------------------- | -| errors | [SingleOrArray](./ts-japi.singleorarray.md)<ErrorType> | Errors to serialize. | -| options | Partial<[ErrorSerializerOptions](./ts-japi.errorserializeroptions.md)<ErrorType>> | (Optional) Options to use at runtime. | - -**Returns:** - -[ErrorDocument](./ts-japi.errordocument.md) diff --git a/docs/api/ts-japi.errorserializeroptions.attributes.md b/docs/api/ts-japi.errorserializeroptions.attributes.md deleted file mode 100644 index 96e5f4d..0000000 --- a/docs/api/ts-japi.errorserializeroptions.attributes.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: ErrorSerializerOptions.attributes ---- - -# ErrorSerializerOptions.attributes property - -An object of attribute names to use in place of the . - -**Signature:** - -```typescript -interface ErrorSerializerOptions { - attributes: Partial>; -} -``` diff --git a/docs/api/ts-japi.errorserializeroptions.linkers.md b/docs/api/ts-japi.errorserializeroptions.linkers.md deleted file mode 100644 index 3ccd043..0000000 --- a/docs/api/ts-japi.errorserializeroptions.linkers.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorSerializerOptions.linkers ---- - -# ErrorSerializerOptions.linkers property - -A set of options for constructing \[top-level -links\](https://jsonapi.org/format/\#document-top-level). - -**Signature:** - -```typescript -interface ErrorSerializerOptions { - linkers: { - about?: Linker<[JapiError]>; - }; -} -``` diff --git a/docs/api/ts-japi.errorserializeroptions.md b/docs/api/ts-japi.errorserializeroptions.md deleted file mode 100644 index 73a4724..0000000 --- a/docs/api/ts-japi.errorserializeroptions.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: ErrorSerializerOptions ---- - -# ErrorSerializerOptions interface - -**Signature:** - -```typescript -export interface ErrorSerializerOptions> -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -| [attributes](./ts-japi.errorserializeroptions.attributes.md) | | Partial<[ErrorAttributeOption](./ts-japi.errorattributeoption.md)<T>> | An object of attribute names to use in place of the . | -| [linkers](./ts-japi.errorserializeroptions.linkers.md) | | { about?: Linker<\[JapiError\]>; } | A set of options for constructing \[top-level links\](https://jsonapi.org/format/\#document-top-level). | -| [metaizers](./ts-japi.errorserializeroptions.metaizers.md) | | { jsonapi?: Metaizer<\[\]>; document?: Metaizer<\[JapiError\[\]\]>; error?: Metaizer<\[JapiError\]>; } | A dictionary of s to use in different locations of the document. | -| [version](./ts-japi.errorserializeroptions.version.md) | | string \| null |

The highest JSON API version supported.

1.0

| diff --git a/docs/api/ts-japi.errorserializeroptions.metaizers.md b/docs/api/ts-japi.errorserializeroptions.metaizers.md deleted file mode 100644 index 0083c42..0000000 --- a/docs/api/ts-japi.errorserializeroptions.metaizers.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: ErrorSerializerOptions.metaizers ---- - -# ErrorSerializerOptions.metaizers property - -A dictionary of s to use in different locations of the document. - -**Signature:** - -```typescript -interface ErrorSerializerOptions { - metaizers: { - jsonapi?: Metaizer<[]>; - document?: Metaizer<[JapiError[]]>; - error?: Metaizer<[JapiError]>; - }; -} -``` diff --git a/docs/api/ts-japi.errorserializeroptions.version.md b/docs/api/ts-japi.errorserializeroptions.version.md deleted file mode 100644 index f693f18..0000000 --- a/docs/api/ts-japi.errorserializeroptions.version.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: ErrorSerializerOptions.version ---- - -# ErrorSerializerOptions.version property - -The highest JSON API version supported. - -`1.0` - -**Signature:** - -```typescript -interface ErrorSerializerOptions { - version: string | null; -} -``` diff --git a/docs/api/ts-japi.errorsource.md b/docs/api/ts-japi.errorsource.md deleted file mode 100644 index 4d2b3cc..0000000 --- a/docs/api/ts-japi.errorsource.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorSource ---- - -# ErrorSource interface - -**Signature:** - -```typescript -export interface ErrorSource -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------ | --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [parameter?](./ts-japi.errorsource.parameter.md) | | string | (Optional) A string indicating which URI query parameter caused the error. | -| [pointer?](./ts-japi.errorsource.pointer.md) | | string | (Optional) A JSON Pointer \[RFC6901\] to the associated entity in the request document \[e.g. /data for a primary data object, or /data/attributes/title for a specific attribute\]. | diff --git a/docs/api/ts-japi.errorsource.parameter.md b/docs/api/ts-japi.errorsource.parameter.md deleted file mode 100644 index 33c9fa8..0000000 --- a/docs/api/ts-japi.errorsource.parameter.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: ErrorSource.parameter ---- - -# ErrorSource.parameter property - -A string indicating which URI query parameter caused the error. - -**Signature:** - -```typescript -interface ErrorSource { - parameter?: string; -} -``` diff --git a/docs/api/ts-japi.errorsource.pointer.md b/docs/api/ts-japi.errorsource.pointer.md deleted file mode 100644 index 2e06d10..0000000 --- a/docs/api/ts-japi.errorsource.pointer.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: ErrorSource.pointer ---- - -# ErrorSource.pointer property - -A JSON Pointer \[RFC6901\] to the associated entity in the request document \[e.g. `/data` for a -primary data object, or `/data/attributes/title` for a specific attribute\]. - -**Signature:** - -```typescript -interface ErrorSource { - pointer?: string; -} -``` diff --git a/docs/api/ts-japi.errorsourceattribute.md b/docs/api/ts-japi.errorsourceattribute.md deleted file mode 100644 index 02247bb..0000000 --- a/docs/api/ts-japi.errorsourceattribute.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorSourceAttribute ---- - -# ErrorSourceAttribute interface - -**Signature:** - -```typescript -export interface ErrorSourceAttribute -``` - -## Properties - -| Property | Modifiers | Type | Description | -| -------------------------------------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [parameter](./ts-japi.errorsourceattribute.parameter.md) | | keyof T |

A string indicating which URI query parameter caused the error.

undefined

| -| [pointer](./ts-japi.errorsourceattribute.pointer.md) | | keyof T |

A JSON Pointer \[RFC6901\] to the associated entity in the request document \[e.g. /data for a primary data object, or /data/attributes/title for a specific attribute\].

"location"

| diff --git a/docs/api/ts-japi.errorsourceattribute.parameter.md b/docs/api/ts-japi.errorsourceattribute.parameter.md deleted file mode 100644 index 17de338..0000000 --- a/docs/api/ts-japi.errorsourceattribute.parameter.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: ErrorSourceAttribute.parameter ---- - -# ErrorSourceAttribute.parameter property - -A string indicating which URI query parameter caused the error. - -`undefined` - -**Signature:** - -```typescript -interface ErrorSourceAttribute { - parameter: keyof T; -} -``` diff --git a/docs/api/ts-japi.errorsourceattribute.pointer.md b/docs/api/ts-japi.errorsourceattribute.pointer.md deleted file mode 100644 index e13dd14..0000000 --- a/docs/api/ts-japi.errorsourceattribute.pointer.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: ErrorSourceAttribute.pointer ---- - -# ErrorSourceAttribute.pointer property - -A JSON Pointer \[RFC6901\] to the associated entity in the request document \[e.g. `/data` for a -primary data object, or `/data/attributes/title` for a specific attribute\]. - -`"location"` - -**Signature:** - -```typescript -interface ErrorSourceAttribute { - pointer: keyof T; -} -``` diff --git a/docs/api/ts-japi.iserrordocument.md b/docs/api/ts-japi.iserrordocument.md deleted file mode 100644 index 9827fea..0000000 --- a/docs/api/ts-japi.iserrordocument.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: isErrorDocument ---- - -# isErrorDocument() function - -Detects an `ErrorDocument` like object - -**Signature:** - -```typescript -export declare function isErrorDocument(document: unknown): document is ErrorDocument; -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------- | ----------------- | -| document | unknown | An unknown object | - -**Returns:** - -document is [ErrorDocument](./ts-japi.errordocument.md) diff --git a/docs/api/ts-japi.isobject.md b/docs/api/ts-japi.isobject.md deleted file mode 100644 index 9b82f51..0000000 --- a/docs/api/ts-japi.isobject.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: isObject ---- - -# isObject() function - -**Signature:** - -```typescript -export declare function isObject(o: unknown): o is Record; -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------- | ----------- | -| o | unknown | | - -**Returns:** - -o is Record<string, unknown> diff --git a/docs/api/ts-japi.isplainobject.md b/docs/api/ts-japi.isplainobject.md deleted file mode 100644 index 811cefb..0000000 --- a/docs/api/ts-japi.isplainobject.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: isPlainObject ---- - -# isPlainObject() function - -**Signature:** - -```typescript -export declare function isPlainObject(o: unknown): o is Record; -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------- | ----------- | -| o | unknown | | - -**Returns:** - -o is Record<string, unknown> diff --git a/docs/api/ts-japi.japierror._constructor_.md b/docs/api/ts-japi.japierror._constructor_.md deleted file mode 100644 index 332d811..0000000 --- a/docs/api/ts-japi.japierror._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: JapiError.(constructor) ---- - -# JapiError.(constructor) - -Constructs a new instance of the `JapiError` class - -**Signature:** - -```typescript -class JapiError { - constructor(options?: ErrorOptions); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------- | ----------------- | -| options | [ErrorOptions](./ts-japi.erroroptions.md) | (Optional) | diff --git a/docs/api/ts-japi.japierror.code.md b/docs/api/ts-japi.japierror.code.md deleted file mode 100644 index 9272254..0000000 --- a/docs/api/ts-japi.japierror.code.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: JapiError.code ---- - -# JapiError.code property - -An application-specific error code, expressed as a string value. - -**Signature:** - -```typescript -class JapiError { - code?: string; -} -``` diff --git a/docs/api/ts-japi.japierror.detail.md b/docs/api/ts-japi.japierror.detail.md deleted file mode 100644 index 0f17224..0000000 --- a/docs/api/ts-japi.japierror.detail.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: JapiError.detail ---- - -# JapiError.detail property - -A human-readable explanation specific to this occurrence of the problem. Like title, this field’s -value can be localized. - -**Signature:** - -```typescript -class JapiError { - detail?: string; -} -``` diff --git a/docs/api/ts-japi.japierror.id.md b/docs/api/ts-japi.japierror.id.md deleted file mode 100644 index 9c20ba8..0000000 --- a/docs/api/ts-japi.japierror.id.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: JapiError.id ---- - -# JapiError.id property - -A unique identifier for this particular occurrence of the problem. - -**Signature:** - -```typescript -class JapiError { - id?: string; -} -``` diff --git a/docs/api/ts-japi.japierror.islikejapierror.md b/docs/api/ts-japi.japierror.islikejapierror.md deleted file mode 100644 index d74bb2e..0000000 --- a/docs/api/ts-japi.japierror.islikejapierror.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_label: JapiError.isLikeJapiError ---- - -# JapiError.isLikeJapiError() method - -Tests whether `error` has similar attributes to a JapiError - -**Signature:** - -```typescript -class JapiError { - static isLikeJapiError(error: unknown): error is Partial; -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------- | ----------------- | -| error | unknown | An unknown object | - -**Returns:** - -error is Partial<JapiError> diff --git a/docs/api/ts-japi.japierror.links.md b/docs/api/ts-japi.japierror.links.md deleted file mode 100644 index 399fd28..0000000 --- a/docs/api/ts-japi.japierror.links.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: JapiError.links ---- - -# JapiError.links property - -A links object - -**Signature:** - -```typescript -class JapiError { - links?: Dictionary; -} -``` diff --git a/docs/api/ts-japi.japierror.md b/docs/api/ts-japi.japierror.md deleted file mode 100644 index 2306fc9..0000000 --- a/docs/api/ts-japi.japierror.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_label: JapiError ---- - -# JapiError class - -**Signature:** - -```typescript -export default class JapiError -``` - -## Constructors - -| Constructor | Modifiers | Description | -| -------------------------------------------------------------- | --------- | ------------------------------------------------------------- | -| [(constructor)(options)](./ts-japi.japierror._constructor_.md) | | Constructs a new instance of the JapiError class | - -## Properties - -| Property | Modifiers | Type | Description | -| ---------------------------------------- | --------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [code?](./ts-japi.japierror.code.md) | | string | (Optional) An application-specific error code, expressed as a string value. | -| [detail?](./ts-japi.japierror.detail.md) | | string | (Optional) A human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized. | -| [id?](./ts-japi.japierror.id.md) | | string | (Optional) A unique identifier for this particular occurrence of the problem. | -| [links?](./ts-japi.japierror.links.md) | | [Dictionary](./ts-japi.dictionary.md)<Link \| [nullish](./ts-japi.nullish.md)> | (Optional) A links object | -| [meta?](./ts-japi.japierror.meta.md) | | Meta | (Optional) A meta object containing non-standard meta information about the error. | -| [source?](./ts-japi.japierror.source.md) | | { pointer?: string; parameter?: string; header?: string; } | (Optional) An object containing references to the source of the error, optionally including any of the following members. | -| [status?](./ts-japi.japierror.status.md) | | string | (Optional) The HTTP status code applicable to this problem, expressed as a string value. | -| [title?](./ts-japi.japierror.title.md) | | string | (Optional) A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. | - -## Methods - -| Method | Modifiers | Description | -| ---------------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------- | -| [isLikeJapiError(error)](./ts-japi.japierror.islikejapierror.md) | static | Tests whether error has similar attributes to a JapiError | diff --git a/docs/api/ts-japi.japierror.meta.md b/docs/api/ts-japi.japierror.meta.md deleted file mode 100644 index 2e88bc0..0000000 --- a/docs/api/ts-japi.japierror.meta.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: JapiError.meta ---- - -# JapiError.meta property - -A meta object containing non-standard meta information about the error. - -**Signature:** - -```typescript -class JapiError { - meta?: Meta; -} -``` diff --git a/docs/api/ts-japi.japierror.source.md b/docs/api/ts-japi.japierror.source.md deleted file mode 100644 index 54f143e..0000000 --- a/docs/api/ts-japi.japierror.source.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: JapiError.source ---- - -# JapiError.source property - -An object containing references to the source of the error, optionally including any of the -following members. - -**Signature:** - -```typescript -class JapiError { - source?: { - pointer?: string; - parameter?: string; - header?: string; - }; -} -``` diff --git a/docs/api/ts-japi.japierror.status.md b/docs/api/ts-japi.japierror.status.md deleted file mode 100644 index 71f5850..0000000 --- a/docs/api/ts-japi.japierror.status.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: JapiError.status ---- - -# JapiError.status property - -The HTTP status code applicable to this problem, expressed as a string value. - -**Signature:** - -```typescript -class JapiError { - status?: string; -} -``` diff --git a/docs/api/ts-japi.japierror.title.md b/docs/api/ts-japi.japierror.title.md deleted file mode 100644 index d61397f..0000000 --- a/docs/api/ts-japi.japierror.title.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: JapiError.title ---- - -# JapiError.title property - -A short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence -of the problem, except for purposes of localization. - -**Signature:** - -```typescript -class JapiError { - title?: string; -} -``` diff --git a/docs/api/ts-japi.jsonapiobject.md b/docs/api/ts-japi.jsonapiobject.md deleted file mode 100644 index 5cea201..0000000 --- a/docs/api/ts-japi.jsonapiobject.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: JSONAPIObject ---- - -# JSONAPIObject interface - -**Signature:** - -```typescript -export interface JSONAPIObject -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ---------------------------------------------- | --------- | ------ | ----------------- | -| [meta?](./ts-japi.jsonapiobject.meta.md) | | Meta | (Optional) | -| [version?](./ts-japi.jsonapiobject.version.md) | | string | (Optional) | diff --git a/docs/api/ts-japi.jsonapiobject.meta.md b/docs/api/ts-japi.jsonapiobject.meta.md deleted file mode 100644 index 6b97e6f..0000000 --- a/docs/api/ts-japi.jsonapiobject.meta.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: JSONAPIObject.meta ---- - -# JSONAPIObject.meta property - -**Signature:** - -```typescript -interface JSONAPIObject { - meta?: Meta; -} -``` diff --git a/docs/api/ts-japi.jsonapiobject.version.md b/docs/api/ts-japi.jsonapiobject.version.md deleted file mode 100644 index 59277b3..0000000 --- a/docs/api/ts-japi.jsonapiobject.version.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: JSONAPIObject.version ---- - -# JSONAPIObject.version property - -**Signature:** - -```typescript -interface JSONAPIObject { - version?: string; -} -``` diff --git a/docs/api/ts-japi.linker._constructor_.md b/docs/api/ts-japi.linker._constructor_.md deleted file mode 100644 index 271f03d..0000000 --- a/docs/api/ts-japi.linker._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_label: Linker.(constructor) ---- - -# Linker.(constructor) - -Creates a . - -**Signature:** - -```typescript -class Linker { - constructor(link: VariadicFunction, options?: LinkerOptions); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------------------------- | --------------------------------------------------- | -| link | [VariadicFunction](./ts-japi.variadicfunction.md)<Dependencies, string> | A used to generate a string URI from its arguments. | -| options | [LinkerOptions](./ts-japi.linkeroptions.md)<Dependencies> | (Optional) Options for the linker. | diff --git a/docs/api/ts-japi.linker.md b/docs/api/ts-japi.linker.md deleted file mode 100644 index 951e089..0000000 --- a/docs/api/ts-japi.linker.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_label: Linker ---- - -# Linker class - -The class is used to construct a \[link\](https://jsonapi.org/format/\#document-links). - -Example: - -```typescript -[[include:linker.example.ts]] -``` - -**Signature:** - -```typescript -export default class Linker -``` - -## Constructors - -| Constructor | Modifiers | Description | -| ----------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(link, options)](./ts-japi.linker._constructor_.md) | | Creates a . | diff --git a/docs/api/ts-japi.linkeroptions.md b/docs/api/ts-japi.linkeroptions.md deleted file mode 100644 index 15cf8d6..0000000 --- a/docs/api/ts-japi.linkeroptions.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: LinkerOptions ---- - -# LinkerOptions interface - -**Signature:** - -```typescript -export interface LinkerOptions -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------ | --------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| [metaizer?](./ts-japi.linkeroptions.metaizer.md) | | Metaizer<Dependencies> | (Optional) A that gets the \[meta\](https://jsonapi.org/format/\#document-resource-object-relationships) about the link. | diff --git a/docs/api/ts-japi.linkeroptions.metaizer.md b/docs/api/ts-japi.linkeroptions.metaizer.md deleted file mode 100644 index e240c9f..0000000 --- a/docs/api/ts-japi.linkeroptions.metaizer.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: LinkerOptions.metaizer ---- - -# LinkerOptions.metaizer property - -A that gets the \[meta\](https://jsonapi.org/format/\#document-resource-object-relationships) about -the link. - -**Signature:** - -```typescript -interface LinkerOptions { - metaizer?: Metaizer; -} -``` diff --git a/docs/api/ts-japi.metadocument.md b/docs/api/ts-japi.metadocument.md deleted file mode 100644 index 9a51c4d..0000000 --- a/docs/api/ts-japi.metadocument.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: MetaDocument ---- - -# MetaDocument interface - -**Signature:** - -```typescript -export interface MetaDocument extends BaseDocument -``` - -**Extends:** [BaseDocument](./ts-japi.basedocument.md) - -## Properties - -| Property | Modifiers | Type | Description | -| -------------------------------------- | --------- | ---- | ----------- | -| [meta](./ts-japi.metadocument.meta.md) | | Meta | | diff --git a/docs/api/ts-japi.metadocument.meta.md b/docs/api/ts-japi.metadocument.meta.md deleted file mode 100644 index 19591c1..0000000 --- a/docs/api/ts-japi.metadocument.meta.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: MetaDocument.meta ---- - -# MetaDocument.meta property - -**Signature:** - -```typescript -interface MetaDocument { - meta: Meta; -} -``` diff --git a/docs/api/ts-japi.metaizer._constructor_.md b/docs/api/ts-japi.metaizer._constructor_.md deleted file mode 100644 index 7404fe0..0000000 --- a/docs/api/ts-japi.metaizer._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: Metaizer.(constructor) ---- - -# Metaizer.(constructor) - -Creates a . - -**Signature:** - -```typescript -class Metaizer { - constructor(metaize: VariadicFunction>); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| metaize | [VariadicFunction](./ts-japi.variadicfunction.md)<Dependencies, [Dictionary](./ts-japi.dictionary.md)<any>> | A function to generate \[meta information\](https://jsonapi.org/format/\#document-meta) from its arguments. | diff --git a/docs/api/ts-japi.metaizer.md b/docs/api/ts-japi.metaizer.md deleted file mode 100644 index 4ac700d..0000000 --- a/docs/api/ts-japi.metaizer.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_label: Metaizer ---- - -# Metaizer class - -The class is used to construct \[meta information\](https://jsonapi.org/format/\#document-meta). - -Example: - -```typescript -[[include:metaizer.example.ts]] -``` - -**Signature:** - -```typescript -export default class Metaizer -``` - -## Constructors - -| Constructor | Modifiers | Description | -| ------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(metaize)](./ts-japi.metaizer._constructor_.md) | | Creates a . | diff --git a/docs/api/ts-japi.nullish.md b/docs/api/ts-japi.nullish.md deleted file mode 100644 index eea0f42..0000000 --- a/docs/api/ts-japi.nullish.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_label: nullish ---- - -# nullish type - -**Signature:** - -```typescript -export declare type nullish = null | undefined; -``` diff --git a/docs/api/ts-japi.paginationof.first.md b/docs/api/ts-japi.paginationof.first.md deleted file mode 100644 index 58b501f..0000000 --- a/docs/api/ts-japi.paginationof.first.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: PaginationOf.first ---- - -# PaginationOf.first property - -**Signature:** - -```typescript -interface PaginationOf { - first: T | nullish; -} -``` diff --git a/docs/api/ts-japi.paginationof.last.md b/docs/api/ts-japi.paginationof.last.md deleted file mode 100644 index 11081d2..0000000 --- a/docs/api/ts-japi.paginationof.last.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: PaginationOf.last ---- - -# PaginationOf.last property - -**Signature:** - -```typescript -interface PaginationOf { - last: T | nullish; -} -``` diff --git a/docs/api/ts-japi.paginationof.md b/docs/api/ts-japi.paginationof.md deleted file mode 100644 index 0b5346c..0000000 --- a/docs/api/ts-japi.paginationof.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: PaginationOf ---- - -# PaginationOf interface - -**Signature:** - -```typescript -export interface PaginationOf -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ---------------------------------------- | --------- | ------------------------------------ | ----------- | -| [first](./ts-japi.paginationof.first.md) | | T \| [nullish](./ts-japi.nullish.md) | | -| [last](./ts-japi.paginationof.last.md) | | T \| [nullish](./ts-japi.nullish.md) | | -| [next](./ts-japi.paginationof.next.md) | | T \| [nullish](./ts-japi.nullish.md) | | -| [prev](./ts-japi.paginationof.prev.md) | | T \| [nullish](./ts-japi.nullish.md) | | diff --git a/docs/api/ts-japi.paginationof.next.md b/docs/api/ts-japi.paginationof.next.md deleted file mode 100644 index dc57a22..0000000 --- a/docs/api/ts-japi.paginationof.next.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: PaginationOf.next ---- - -# PaginationOf.next property - -**Signature:** - -```typescript -interface PaginationOf { - next: T | nullish; -} -``` diff --git a/docs/api/ts-japi.paginationof.prev.md b/docs/api/ts-japi.paginationof.prev.md deleted file mode 100644 index a7d993e..0000000 --- a/docs/api/ts-japi.paginationof.prev.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: PaginationOf.prev ---- - -# PaginationOf.prev property - -**Signature:** - -```typescript -interface PaginationOf { - prev: T | nullish; -} -``` diff --git a/docs/api/ts-japi.paginator._constructor_.md b/docs/api/ts-japi.paginator._constructor_.md deleted file mode 100644 index 1487341..0000000 --- a/docs/api/ts-japi.paginator._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: Paginator.(constructor) ---- - -# Paginator.(constructor) - -Creates a . - -**Signature:** - -```typescript -class Paginator { - constructor(paginate: (data: SingleOrArray) => PaginationOf | void); -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| paginate | (data: [SingleOrArray](./ts-japi.singleorarray.md)<DataType>) => [PaginationOf](./ts-japi.paginationof.md)<string> \| void | A function to generate pagination links from data. | diff --git a/docs/api/ts-japi.paginator.md b/docs/api/ts-japi.paginator.md deleted file mode 100644 index bbc07eb..0000000 --- a/docs/api/ts-japi.paginator.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -sidebar_label: Paginator ---- - -# Paginator class - -The class is used to construct \[pagination -links\](https://jsonapi.org/format/\#fetching-pagination). - -Example: - -```typescript -[[include:paginator.example.ts]] -``` - -**Signature:** - -```typescript -export default class Paginator -``` - -## Constructors - -| Constructor | Modifiers | Description | -| --------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(paginate)](./ts-japi.paginator._constructor_.md) | | Creates a . | diff --git a/docs/api/ts-japi.primarydata.md b/docs/api/ts-japi.primarydata.md deleted file mode 100644 index 3c44494..0000000 --- a/docs/api/ts-japi.primarydata.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: PrimaryData ---- - -# PrimaryData type - -**Signature:** - -```typescript -export declare type PrimaryData = - | SingleOrArray - | SingleOrArray> - | null; -``` - -**References:** [SingleOrArray](./ts-japi.singleorarray.md) diff --git a/docs/api/ts-japi.relator._constructor_.md b/docs/api/ts-japi.relator._constructor_.md deleted file mode 100644 index 98a37ed..0000000 --- a/docs/api/ts-japi.relator._constructor_.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -sidebar_label: Relator.(constructor) ---- - -# Relator.(constructor) - -Creates a . - -**Signature:** - -```typescript -class Relator { - constructor( - fetch: (data: PrimaryType) => Promise, - serializer: Serializer, - options?: Partial> - ); -} -``` - -## Parameters - -| Parameter | Type | Description | -| ---------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| fetch | (data: PrimaryType) => Promise<RelatedType \| RelatedType\[\] \| [nullish](./ts-japi.nullish.md)> | Fetches related data from primary data. | -| serializer | Serializer<RelatedType> | The Serializer to use for related data. | -| options | Partial<[RelatorOptions](./ts-japi.relatoroptions.md)<PrimaryType, RelatedType>> | (Optional) Options for the relator. | diff --git a/docs/api/ts-japi.relator.defaultoptions.md b/docs/api/ts-japi.relator.defaultoptions.md deleted file mode 100644 index 70e0636..0000000 --- a/docs/api/ts-japi.relator.defaultoptions.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: Relator.defaultOptions ---- - -# Relator.defaultOptions property - -Default options. Can be edited to change default options globally. - -**Signature:** - -```typescript -class Relator { - static defaultOptions: { - linkers: {}; - }; -} -``` diff --git a/docs/api/ts-japi.relator.md b/docs/api/ts-japi.relator.md deleted file mode 100644 index f8d67ca..0000000 --- a/docs/api/ts-japi.relator.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: Relator ---- - -# Relator class - -The class is used to generate top-level \[included -data\](https://jsonapi.org/format/\#document-top-level) as well as resource-level -\[relationships\](https://jsonapi.org/format/\#document-resource-object-relationships). - -Example: - -```typescript -[[include:relator.example.ts]] -``` - -**Signature:** - -```typescript -export default class Relator = any> -``` - -## Constructors - -| Constructor | Modifiers | Description | -| ------------------------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(fetch, serializer, options)](./ts-japi.relator._constructor_.md) | | Creates a . | - -## Properties - -| Property | Modifiers | Type | Description | -| ----------------------------------------------------- | ------------------- | ---------------- | ------------------------------------------------------------------ | -| [defaultOptions](./ts-japi.relator.defaultoptions.md) | static | { linkers: {}; } | Default options. Can be edited to change default options globally. | -| [relatedName](./ts-japi.relator.relatedname.md) | | string | | diff --git a/docs/api/ts-japi.relator.relatedname.md b/docs/api/ts-japi.relator.relatedname.md deleted file mode 100644 index 5bf23b9..0000000 --- a/docs/api/ts-japi.relator.relatedname.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: Relator.relatedName ---- - -# Relator.relatedName property - -**Signature:** - -```typescript -class Relator { - relatedName: string; -} -``` diff --git a/docs/api/ts-japi.relatoroptions.linkers.md b/docs/api/ts-japi.relatoroptions.linkers.md deleted file mode 100644 index 58e08ed..0000000 --- a/docs/api/ts-japi.relatoroptions.linkers.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: RelatorOptions.linkers ---- - -# RelatorOptions.linkers property - -A dictionary of s to use for constructing links. - -**Signature:** - -```typescript -interface RelatorOptions { - linkers: { - relationship?: Linker<[PrimaryType, SingleOrArray | nullish]>; - related?: Linker<[PrimaryType, SingleOrArray | nullish]>; - }; -} -``` diff --git a/docs/api/ts-japi.relatoroptions.md b/docs/api/ts-japi.relatoroptions.md deleted file mode 100644 index 15ddf86..0000000 --- a/docs/api/ts-japi.relatoroptions.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_label: RelatorOptions ---- - -# RelatorOptions interface - -**Signature:** - -```typescript -export interface RelatorOptions = any> -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | -| [linkers](./ts-japi.relatoroptions.linkers.md) | | { relationship?: Linker<\[PrimaryType, [SingleOrArray](./ts-japi.singleorarray.md)<RelatedType> \| [nullish](./ts-japi.nullish.md)\]>; related?: Linker<\[PrimaryType, [SingleOrArray](./ts-japi.singleorarray.md)<RelatedType> \| [nullish](./ts-japi.nullish.md)\]>; } | A dictionary of s to use for constructing links. | -| [metaizer?](./ts-japi.relatoroptions.metaizer.md) | | Metaizer<\[PrimaryType, [SingleOrArray](./ts-japi.singleorarray.md)<RelatedType> \| [nullish](./ts-japi.nullish.md)\]> | (Optional) A that gets the \[meta\](https://jsonapi.org/format/\#document-resource-object-relationships) about the relationship. | diff --git a/docs/api/ts-japi.relatoroptions.metaizer.md b/docs/api/ts-japi.relatoroptions.metaizer.md deleted file mode 100644 index a78f93b..0000000 --- a/docs/api/ts-japi.relatoroptions.metaizer.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -sidebar_label: RelatorOptions.metaizer ---- - -# RelatorOptions.metaizer property - -A that gets the \[meta\](https://jsonapi.org/format/\#document-resource-object-relationships) about -the relationship. - -**Signature:** - -```typescript -interface RelatorOptions { - metaizer?: Metaizer<[PrimaryType, SingleOrArray | nullish]>; -} -``` diff --git a/docs/api/ts-japi.resourcelinkage.md b/docs/api/ts-japi.resourcelinkage.md deleted file mode 100644 index f5add77..0000000 --- a/docs/api/ts-japi.resourcelinkage.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: ResourceLinkage ---- - -# ResourceLinkage type - -**Signature:** - -```typescript -export declare type ResourceLinkage = SingleOrArray | null; -``` - -**References:** [SingleOrArray](./ts-japi.singleorarray.md) diff --git a/docs/api/ts-japi.serializer._constructor_.md b/docs/api/ts-japi.serializer._constructor_.md deleted file mode 100644 index 9798a1c..0000000 --- a/docs/api/ts-japi.serializer._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_label: Serializer.(constructor) ---- - -# Serializer.(constructor) - -Creates a . - -**Signature:** - -```typescript -class Serializer { - constructor(collectionName: string, options?: Partial>); -} -``` - -## Parameters - -| Parameter | Type | Description | -| -------------- | ------------------------------------------------------------------------------------- | --------------------------------------------- | -| collectionName | string | The name of the collection of objects. | -| options | Partial<[SerializerOptions](./ts-japi.serializeroptions.md)<PrimaryType>> | (Optional) Options for the serializer. | diff --git a/docs/api/ts-japi.serializer.cache.md b/docs/api/ts-japi.serializer.cache.md deleted file mode 100644 index 47fa780..0000000 --- a/docs/api/ts-japi.serializer.cache.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: Serializer.cache ---- - -# Serializer.cache property - -Caching - -**Signature:** - -```typescript -class Serializer { - cache: Cache; -} -``` diff --git a/docs/api/ts-japi.serializer.collectionname.md b/docs/api/ts-japi.serializer.collectionname.md deleted file mode 100644 index 8e06e2d..0000000 --- a/docs/api/ts-japi.serializer.collectionname.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: Serializer.collectionName ---- - -# Serializer.collectionName property - -The name to use for the type. - -**Signature:** - -```typescript -class Serializer { - collectionName: string; -} -``` diff --git a/docs/api/ts-japi.serializer.defaultoptions.md b/docs/api/ts-japi.serializer.defaultoptions.md deleted file mode 100644 index 19a1609..0000000 --- a/docs/api/ts-japi.serializer.defaultoptions.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -sidebar_label: Serializer.defaultOptions ---- - -# Serializer.defaultOptions property - -Default options. Can be edited to change default options globally. - -**Signature:** - -```typescript -class Serializer { - static defaultOptions: { - idKey: string; - version: string; - onlyIdentifier: boolean; - nullData: boolean; - asIncluded: boolean; - onlyRelationship: boolean; - cache: boolean; - depth: number; - projection: null; - linkers: {}; - metaizers: {}; - }; -} -``` diff --git a/docs/api/ts-japi.serializer.getrelators.md b/docs/api/ts-japi.serializer.getrelators.md deleted file mode 100644 index 3d4bd83..0000000 --- a/docs/api/ts-japi.serializer.getrelators.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: Serializer.getRelators ---- - -# Serializer.getRelators() method - -Gets the s associated with this serializer - -**Signature:** - -```typescript -class Serializer { - getRelators(): Record> | undefined; -} -``` - -**Returns:** - -Record<string, Relator<PrimaryType, any>> \| undefined diff --git a/docs/api/ts-japi.serializer.helpers.md b/docs/api/ts-japi.serializer.helpers.md deleted file mode 100644 index 23288e1..0000000 --- a/docs/api/ts-japi.serializer.helpers.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: Serializer.helpers ---- - -# Serializer.helpers property - -The set of helper functions for the serializer - -**Signature:** - -```typescript -class Serializer { - helpers: Helpers; -} -``` diff --git a/docs/api/ts-japi.serializer.md b/docs/api/ts-japi.serializer.md deleted file mode 100644 index 8d68152..0000000 --- a/docs/api/ts-japi.serializer.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -sidebar_label: Serializer ---- - -# Serializer class - -The class is the main class used to serializer data (you can use the class to serialize errors). - -Example: - -```typescript -[[include:serializer.example.ts]] -``` - -**Signature:** - -```typescript -export default class Serializer = any> -``` - -## Constructors - -| Constructor | Modifiers | Description | -| ------------------------------------------------------------------------------- | --------- | ----------- | -| [(constructor)(collectionName, options)](./ts-japi.serializer._constructor_.md) | | Creates a . | - -## Properties - -| Property | Modifiers | Type | Description | -| -------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | -| [cache](./ts-japi.serializer.cache.md) | | Cache<PrimaryType> | Caching | -| [collectionName](./ts-japi.serializer.collectionname.md) | | string | The name to use for the type. | -| [defaultOptions](./ts-japi.serializer.defaultoptions.md) | static | { idKey: string; version: string; onlyIdentifier: boolean; nullData: boolean; asIncluded: boolean; onlyRelationship: boolean; cache: boolean; depth: number; projection: null; linkers: {}; metaizers: {}; } | Default options. Can be edited to change default options globally. | -| [helpers](./ts-japi.serializer.helpers.md) | | Helpers<PrimaryType> | The set of helper functions for the serializer | - -## Methods - -| Method | Modifiers | Description | -| ------------------------------------------------------------- | --------- | ------------------------------------------ | -| [getRelators()](./ts-japi.serializer.getrelators.md) | | Gets the s associated with this serializer | -| [serialize(data, options)](./ts-japi.serializer.serialize.md) | | The actual serialization function. | -| [setRelators(relators)](./ts-japi.serializer.setrelators.md) | | Sets the s associated with this serializer | diff --git a/docs/api/ts-japi.serializer.serialize.md b/docs/api/ts-japi.serializer.serialize.md deleted file mode 100644 index 41ccec3..0000000 --- a/docs/api/ts-japi.serializer.serialize.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_label: Serializer.serialize ---- - -# Serializer.serialize() method - -The actual serialization function. - -**Signature:** - -```typescript -class Serializer { - serialize( - data: SingleOrArray | nullish, - options?: Partial> - ): Promise>>; -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| data | [SingleOrArray](./ts-japi.singleorarray.md)<PrimaryType> \| [nullish](./ts-japi.nullish.md) | Data to serialize. | -| options | Partial<[SerializerOptions](./ts-japi.serializeroptions.md)<PrimaryType>> | (Optional) Options to use at runtime. | - -**Returns:** - -Promise<Partial<[DataDocument](./ts-japi.datadocument.md)<PrimaryType>>> diff --git a/docs/api/ts-japi.serializer.setrelators.md b/docs/api/ts-japi.serializer.setrelators.md deleted file mode 100644 index e0961b3..0000000 --- a/docs/api/ts-japi.serializer.setrelators.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -sidebar_label: Serializer.setRelators ---- - -# Serializer.setRelators() method - -Sets the s associated with this serializer - -**Signature:** - -```typescript -class Serializer { - setRelators(relators: SerializerOptions['relators']): void; -} -``` - -## Parameters - -| Parameter | Type | Description | -| --------- | ------------------------------------------------------------------------------------ | ----------- | -| relators | [SerializerOptions](./ts-japi.serializeroptions.md)<PrimaryType>\['relators'\] | | - -**Returns:** - -void diff --git a/docs/api/ts-japi.serializeroptions.asincluded.md b/docs/api/ts-japi.serializeroptions.asincluded.md deleted file mode 100644 index a01cc9d..0000000 --- a/docs/api/ts-japi.serializeroptions.asincluded.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: SerializerOptions.asIncluded ---- - -# SerializerOptions.asIncluded property - -Whether to make primary data as an \[included -resource\](https://jsonapi.org/format/\#document-compound-documents) and use \[resource identifier -objects\](https://jsonapi.org/format/\#document-resource-identifier-objects) for \[top-level -data\](https://jsonapi.org/format/\#document-top-level). - -`false` - -**Signature:** - -```typescript -interface SerializerOptions { - asIncluded: boolean; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.cache.md b/docs/api/ts-japi.serializeroptions.cache.md deleted file mode 100644 index 5279b38..0000000 --- a/docs/api/ts-japi.serializeroptions.cache.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: SerializerOptions.cache ---- - -# SerializerOptions.cache property - -Enables caching of documents. If a is given, then the given will be used. - -`false` - -**Signature:** - -```typescript -interface SerializerOptions { - cache: boolean | Cache; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.depth.md b/docs/api/ts-japi.serializeroptions.depth.md deleted file mode 100644 index 7cdf9d6..0000000 --- a/docs/api/ts-japi.serializeroptions.depth.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -sidebar_label: SerializerOptions.depth ---- - -# SerializerOptions.depth property - -Determines the depth of `relator`s to use for \[included -resources\](https://jsonapi.org/format/\#document-compound-documents). - -\*\*PLEASE TAKE CAUTION\*\*: If this property is `Infinity`, performance can degrade -\*\*significantly\*\*. It is \*RECOMMENDED\* to use more requests rather than a single one if such -depth is required since included resources can be \*\*inhomogenous\*\* thus difficult to traverse. - -Must be a number in `[0, Infinity]`. - -`0` - -**Signature:** - -```typescript -interface SerializerOptions { - depth: number; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.idkey.md b/docs/api/ts-japi.serializeroptions.idkey.md deleted file mode 100644 index ac053b8..0000000 --- a/docs/api/ts-japi.serializeroptions.idkey.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: SerializerOptions.idKey ---- - -# SerializerOptions.idKey property - -The key name for the identifier in the resource. - -`"id"` - -**Signature:** - -```typescript -interface SerializerOptions { - idKey: keyof PrimaryType; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.linkers.md b/docs/api/ts-japi.serializeroptions.linkers.md deleted file mode 100644 index 9473350..0000000 --- a/docs/api/ts-japi.serializeroptions.linkers.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: SerializerOptions.linkers ---- - -# SerializerOptions.linkers property - -A set of options for constructing \[top-level -links\](https://jsonapi.org/format/\#document-top-level). - -**Signature:** - -```typescript -interface SerializerOptions { - linkers: { - document?: Linker<[SingleOrArray | nullish]>; - resource?: Linker<[PrimaryType]>; - paginator?: Paginator; - }; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.md b/docs/api/ts-japi.serializeroptions.md deleted file mode 100644 index a46fe59..0000000 --- a/docs/api/ts-japi.serializeroptions.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -sidebar_label: SerializerOptions ---- - -# SerializerOptions interface - -**Signature:** - -```typescript -export interface SerializerOptions = any> -``` - -## Properties - -| Property | Modifiers | Type | Description | -| ------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [asIncluded](./ts-japi.serializeroptions.asincluded.md) | | boolean |

Whether to make primary data as an \[included resource\](https://jsonapi.org/format/\#document-compound-documents) and use \[resource identifier objects\](https://jsonapi.org/format/\#document-resource-identifier-objects) for \[top-level data\](https://jsonapi.org/format/\#document-top-level).

false

| -| [cache](./ts-japi.serializeroptions.cache.md) | | boolean \| Cache<PrimaryType> |

Enables caching of documents. If a is given, then the given will be used.

false

| -| [depth](./ts-japi.serializeroptions.depth.md) | | number |

Determines the depth of relators to use for \[included resources\](https://jsonapi.org/format/\#document-compound-documents).

\*\*PLEASE TAKE CAUTION\*\*: If this property is Infinity, performance can degrade \*\*significantly\*\*. It is \*RECOMMENDED\* to use more requests rather than a single one if such depth is required since included resources can be \*\*inhomogenous\*\* thus difficult to traverse.

Must be a number in [0, Infinity].

0

| -| [idKey](./ts-japi.serializeroptions.idkey.md) | | keyof PrimaryType |

The key name for the identifier in the resource.

"id"

| -| [linkers](./ts-japi.serializeroptions.linkers.md) | | { document?: Linker<\[[SingleOrArray](./ts-japi.singleorarray.md)<PrimaryType> \| [nullish](./ts-japi.nullish.md)\]>; resource?: Linker<\[PrimaryType\]>; paginator?: Paginator<PrimaryType>; } | A set of options for constructing \[top-level links\](https://jsonapi.org/format/\#document-top-level). | -| [metaizers](./ts-japi.serializeroptions.metaizers.md) | | { jsonapi?: Metaizer<\[\]>; document?: Metaizer<\[[SingleOrArray](./ts-japi.singleorarray.md)<PrimaryType> \| [nullish](./ts-japi.nullish.md)\]>; resource?: Metaizer<\[PrimaryType\]>; } | A dictionary of s to use in different locations of the document. | -| [nullData](./ts-japi.serializeroptions.nulldata.md) | | boolean |

Whether to use null value the data field.

This option will ignore options , , and (and all options they ignores).

false

| -| [onlyIdentifier](./ts-japi.serializeroptions.onlyidentifier.md) | | boolean |

Whether to only serialize the identifier.

This option will ignore the options

false

| -| [onlyRelationship](./ts-japi.serializeroptions.onlyrelationship.md) | | string |

This is used to serialize the \[resource linkages\](https://jsonapi.org/format/\#document-resource-object-linkage) only. The value must be the name of a collection for a relator in the option.

Only a single primary datum (as opposed to an array) \*\*MUST\*\* be serialized.

This option will ignore the options , , and .

| -| [projection](./ts-japi.serializeroptions.projection.md) | | Partial<Record<keyof PrimaryType, 0 \| 1>> \| null \| undefined |

An object of 0 \*OR\* 1 (\*\*NOT BOTH\*\*) to denote hide or show attributes respectively.

If set (directly) to undefined, then the attributes field will be left undefined. If set to null, then every attribute will show. If set to {}, then every attribute will hide.

null

| -| [relators?](./ts-japi.serializeroptions.relators.md) | | Relator<PrimaryType> \| Array<Relator<PrimaryType>> \| Record<string, Relator<PrimaryType>> |

(Optional) A that generates relationships for a given primary resource.

\*Note\*: You can add more relators by using . This is useful in case you have a cycle of relators among serializers.

See \[relationships objects\](https://jsonapi.org/format/\#document-resource-object-relationships) for more information.

| -| [version](./ts-japi.serializeroptions.version.md) | | string \| null |

The highest JSON API version supported. Set to null to omit version.

1.0

| diff --git a/docs/api/ts-japi.serializeroptions.metaizers.md b/docs/api/ts-japi.serializeroptions.metaizers.md deleted file mode 100644 index 12302e6..0000000 --- a/docs/api/ts-japi.serializeroptions.metaizers.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: SerializerOptions.metaizers ---- - -# SerializerOptions.metaizers property - -A dictionary of s to use in different locations of the document. - -**Signature:** - -```typescript -interface SerializerOptions { - metaizers: { - jsonapi?: Metaizer<[]>; - document?: Metaizer<[SingleOrArray | nullish]>; - resource?: Metaizer<[PrimaryType]>; - }; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.nulldata.md b/docs/api/ts-japi.serializeroptions.nulldata.md deleted file mode 100644 index 08d2494..0000000 --- a/docs/api/ts-japi.serializeroptions.nulldata.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: SerializerOptions.nullData ---- - -# SerializerOptions.nullData property - -Whether to use `null` value the `data` field. - -This option will ignore options , , and (and all options they ignores). - -`false` - -**Signature:** - -```typescript -interface SerializerOptions { - nullData: boolean; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.onlyidentifier.md b/docs/api/ts-japi.serializeroptions.onlyidentifier.md deleted file mode 100644 index 48b47d6..0000000 --- a/docs/api/ts-japi.serializeroptions.onlyidentifier.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_label: SerializerOptions.onlyIdentifier ---- - -# SerializerOptions.onlyIdentifier property - -Whether to only serialize the identifier. - -This option will ignore the options - -`false` - -**Signature:** - -```typescript -interface SerializerOptions { - onlyIdentifier: boolean; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.onlyrelationship.md b/docs/api/ts-japi.serializeroptions.onlyrelationship.md deleted file mode 100644 index b81c130..0000000 --- a/docs/api/ts-japi.serializeroptions.onlyrelationship.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -sidebar_label: SerializerOptions.onlyRelationship ---- - -# SerializerOptions.onlyRelationship property - -This is used to serialize the \[resource -linkages\](https://jsonapi.org/format/\#document-resource-object-linkage) only. The value must be -the name of a collection for a relator in the option. - -Only a single primary datum (as opposed to an array) \*\*MUST\*\* be serialized. - -This option will ignore the options , , and . - -**Signature:** - -```typescript -interface SerializerOptions { - onlyRelationship: string; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.projection.md b/docs/api/ts-japi.serializeroptions.projection.md deleted file mode 100644 index 1173a0e..0000000 --- a/docs/api/ts-japi.serializeroptions.projection.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -sidebar_label: SerializerOptions.projection ---- - -# SerializerOptions.projection property - -An object of 0 \*OR\* 1 (\*\*NOT BOTH\*\*) to denote hide or show attributes respectively. - -If set (directly) to `undefined`, then the `attributes` field will be left `undefined`. If set to -`null`, then every attribute will show. If set to `{}`, then every attribute will hide. - -`null` - -**Signature:** - -```typescript -interface SerializerOptions { - projection: Partial> | null | undefined; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.relators.md b/docs/api/ts-japi.serializeroptions.relators.md deleted file mode 100644 index 5ab42f0..0000000 --- a/docs/api/ts-japi.serializeroptions.relators.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -sidebar_label: SerializerOptions.relators ---- - -# SerializerOptions.relators property - -A that generates `relationships` for a given primary resource. - -\*Note\*: You can add more relators by using . This is useful in case you have a cycle of relators -among serializers. - -See \[relationships objects\](https://jsonapi.org/format/\#document-resource-object-relationships) -for more information. - -**Signature:** - -```typescript -interface SerializerOptions { - relators?: - | Relator - | Array> - | Record>; -} -``` diff --git a/docs/api/ts-japi.serializeroptions.version.md b/docs/api/ts-japi.serializeroptions.version.md deleted file mode 100644 index 5bb8884..0000000 --- a/docs/api/ts-japi.serializeroptions.version.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -sidebar_label: SerializerOptions.version ---- - -# SerializerOptions.version property - -The highest JSON API version supported. Set to `null` to omit version. - -`1.0` - -**Signature:** - -```typescript -interface SerializerOptions { - version: string | null; -} -``` diff --git a/docs/api/ts-japi.singleorarray.md b/docs/api/ts-japi.singleorarray.md deleted file mode 100644 index 9654b07..0000000 --- a/docs/api/ts-japi.singleorarray.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_label: SingleOrArray ---- - -# SingleOrArray type - -A utility type for describing a single object or an array of objects - -**Signature:** - -```typescript -export declare type SingleOrArray = T | T[]; -``` diff --git a/docs/api/ts-japi.uniontointersection.md b/docs/api/ts-japi.uniontointersection.md deleted file mode 100644 index a3f865b..0000000 --- a/docs/api/ts-japi.uniontointersection.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: UnionToIntersection ---- - -# UnionToIntersection type - -**Signature:** - -```typescript -export declare type UnionToIntersection = (U extends any ? (k: U) => void : never) extends ( - k: infer I -) => void - ? I - : never; -``` diff --git a/docs/api/ts-japi.variadicfunction.md b/docs/api/ts-japi.variadicfunction.md deleted file mode 100644 index eb10826..0000000 --- a/docs/api/ts-japi.variadicfunction.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -sidebar_label: VariadicFunction ---- - -# VariadicFunction type - -A function that takes several arguments and outputs something. - -**Signature:** - -```typescript -export declare type VariadicFunction = ( - ...dependencies: Dependencies -) => ReturnType; -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index b445f6c..0000000 --- a/docs/index.md +++ /dev/null @@ -1,393 +0,0 @@ -# ts:japi - -
-{ts:japi} -
- -![node-current](https://img.shields.io/node/v/ts-japi) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) - -> A highly-modular (typescript-friendly)-framework agnostic library for serializing data to the -> JSON:API specification - -- [ts:japi](#tsjapi) - - [Features](#features) - - [Documentation](#documentation) - - [Installation](#installation) - - [Getting Started](#getting-started) - - [Examples](#examples) - - [Serialization](#serialization) - - [Links](#links) - - [Pagination](#pagination) - - [Relationships](#relationships) - - [Metadata](#metadata) - - [Serializing Errors](#serializing-errors) - - [Caching](#caching) - - [Deserialization](#deserialization) - - [Remarks](#remarks) - - [FAQ](#faq) - - [For Developers](#for-developers) - - [Contributing](#contributing) - - [License](#license) - -## Features - -- This is the **only** typescript-compatible library that fully types the JSON:API specification and - performs _proper_ serialization. -- [**Zero dependencies**](#zdg). -- This is the **only** library with [resource recursion](#wirr). -- The modular framework laid out here _highly promotes_ the specifications intentions: - - Using links is no longer obfuscated. - - Meta can truly be placed anywhere with possible dependencies laid out visibly. -- This library is designed to adhere to the specifications "never remove, only add" policy, so we - will remain backwards-compatible. - -## Documentation - -The [documentation](https://mathematic-inc.github.io/ts-japi/) has everything that is covered here -and more. - -## Installation - -You can install ts-japi in your project's directory as usual: - -```bash -npm install ts-japi -``` - -## Getting Started - -There are fives classes that are used to serialize data (only one of which is necessarily required). - -- [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) with - [`SerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html) -- [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) with - [`RelatorOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html) -- [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) with - [`LinkerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html) -- [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) -- [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html) -- [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) with - [`ErrorSerializerOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html) -- [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with - [`CacheOptions`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html) - -You can check the [documentation](https://mathematic-inc.github.io/ts-japi) for a deeper insight -into the usage. - -### Examples - -You can check the [examples](https://github.com/mathematic-inc/ts-japi/tree/master/examples) and the -[test](https://github.com/mathematic-inc/ts-japi/tree/master/test) folders to see some examples -(such as the ones below). You can check -[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/full.example.ts) to -see almost every option of -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) exhausted. - -## Serialization - -The [`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html) class is the -only class required for basic serialization. - -The following example constructs the most basic -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html): (Note the `await`) - -```typescript -import { Serializer } from '../src'; -import { User } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; - -const UserSerializer = new Serializer('users'); - -(async () => { - const user = new User('sample_user_id'); - - console.log('Output:', getJSON(await UserSerializer.serialize(user))); - - // Output: { - // jsonapi: { version: '1.0' }, - // data: { - // type: 'users', - // id: 'sample_user_id', - // attributes: { - // createdAt: '2020-05-20T15:44:37.650Z', - // articles: [], - // comments: [] - // } - // } - // } -})(); -``` - -### Links - -The [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) class is used to -generate a normalized [document link](https://jsonapi.org/format/#document-links). Its methods are -not meant to be called. See the [FAQ](#faq) for reasons. - -The following example constructs a -[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html) for `User`s and `Article`s: - -```typescript -import { Linker } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; - -// The last argument should almost always be an array or a single object type. -// The reason for this is the potential for linking several articles. -const UserArticleLinker = new Linker((user: User, articles: Article | Article[]) => { - return Array.isArray(articles) - ? `https://www.example.com/users/${user.id}/articles/` - : `https://www.example.com/users/${user.id}/articles/${articles.id}`; -}); - -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - - console.log('Output:', getJSON(UserArticleLinker.link(user, article))); - - // Output: https://www.example.com/users/sample_user_id/articles/same_article_id -})(); -``` - -#### Pagination - -The [`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html) class is used to -generate [pagination links](https://jsonapi.org/format/#fetching-pagination). Its methods are not -meant to be called. - -The following example constructs a -[`Paginator`](https://mathematic-inc.github.io/ts-japi/classes/paginator.html): - -```typescript -import { Paginator } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; - -const ArticlePaginator = new Paginator((articles: Article | Article[]) => { - if (Array.isArray(articles)) { - const nextPage = Number(articles[0].id) + 1; - const prevPage = Number(articles[articles.length - 1].id) - 1; - return { - first: `https://www.example.com/articles/0`, - last: `https://www.example.com/articles/10`, - next: nextPage <= 10 ? `https://www.example.com/articles/${nextPage}` : null, - prev: prevPage >= 0 ? `https://www.example.com/articles/${prevPage}` : null, - }; - } - return; -}); - -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - - console.log('Output:', getJSON(ArticlePaginator.paginate([article]))); - - // Output: { - // first: 'https://www.example.com/articles/0', - // last: 'https://www.example.com/articles/10', - // prev: null, - // next: null - // } -})(); -``` - -### Relationships - -The [`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) class is used to -generate top-level [included data](https://jsonapi.org/format/#document-top-level) as well as -resource-level [relationships](https://jsonapi.org/format/#document-resource-object-relationships). -Its methods are not meant to be called. - -[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html)s may also take optional -[`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html)s (using the -[`linker`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#linkers) option) -to define [relationship links](https://jsonapi.org/format/#document-resource-object-relationships) -and -[related resource links](https://jsonapi.org/format/#document-resource-object-related-resource-links). - -The following example constructs a -[`Relator`](https://mathematic-inc.github.io/ts-japi/classes/relator.html) for `User`s and -`Article`s: - -```typescript -import { Serializer, Relator } from '../src'; -import { User, Article } from '../test/models'; -import { getJSON } from '../test/utils/get-json'; - -const ArticleSerializer = new Serializer
('articles'); -const UserArticleRelator = new Relator( - async (user) => user.getArticles(), - ArticleSerializer -); - -// ! The rest of this example is just to illustrate some internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - User.save(user); - Article.save(article); - - console.log('Output:', getJSON(await UserArticleRelator.getRelationship(user))); - - // Output: { data: [ { type: 'articles', id: 'same_article_id' } ] } -})(); -``` - -### Metadata - -The [`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) class is used to -construct generate metadata given some dependencies. There are several locations -[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html) can be used: - -- [`ErrorSerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#metaizers) -- [`RelatorOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/relatoroptions.html#metaizer) -- [`SerializerOptions.metaizers`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#metaizers) -- [`LinkerOptions.metaizer`](https://mathematic-inc.github.io/ts-japi/interfaces/linkeroptions.html#metaizer) - -Like [`Linker`](https://mathematic-inc.github.io/ts-japi/classes/linker.html), its methods are not -meant to be called. - -The following example constructs a -[`Metaizer`](https://mathematic-inc.github.io/ts-japi/classes/metaizer.html): - -```typescript -import { User, Article } from '../test/models'; -import { Metaizer } from '../src'; -import { getJSON } from '../test/utils/get-json'; - -// The last argument should almost always be an array or a single object type. -// The reason for this is the potential for metaizing several articles. -const UserArticleMetaizer = new Metaizer((user: User, articles: Article | Article[]) => { - return Array.isArray(articles) - ? { user_created: user.createdAt, article_created: articles.map((a) => a.createdAt) } - : { user_created: user.createdAt, article_created: articles.createdAt }; -}); - -// ! The rest of this example is just to illustrate internal behavior. -(async () => { - const user = new User('sample_user_id'); - const article = new Article('same_article_id', user); - - console.log('Output:', getJSON(UserArticleMetaizer.metaize(user, article))); - - // Output: { - // user_created: '2020-05-20T15:39:43.277Z', - // article_created: '2020-05-20T15:39:43.277Z' - // } -})(); -``` - -### Serializing Errors - -The [`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html) class -is used to serialize any object considered an error (the -[`attributes`](https://mathematic-inc.github.io/ts-japi/interfaces/errorserializeroptions.html#attributes) -option allows you to choose what attributes to use during serialization). _Alternatively_ -(**recommended**), you can construct custom errors by extending the -[`JapiError`](https://mathematic-inc.github.io/ts-japi/classes/japierror.html) class and use those -for all server-to-client errors. - -The -[error serializer test](https://github.com/mathematic-inc/ts-japi/tree/master/test/error-serializer.test.ts) -includes an example of the alternative solution. - -The following example constructs the most basic -[`ErrorSerializer`](https://mathematic-inc.github.io/ts-japi/classes/errorserializer.html): (Note -the lack of `await`) - -```typescript -import { ErrorSerializer } from '../src'; -import { getJSON } from '../test/utils/get-json'; - -const PrimitiveErrorSerializer = new ErrorSerializer(); - -(async () => { - const error = new Error('badness'); - - console.log('Output:', getJSON(PrimitiveErrorSerializer.serialize(error))); - - // Output: { - // errors: [ { code: 'Error', detail: 'badness' } ], - // jsonapi: { version: '1.0' } - // } -})(); -``` - -### Caching - -The [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) class can be placed in a -[`Serializer`](https://mathematic-inc.github.io/ts-japi/classes/serializer.html)'s -[`cache`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#cache) option. -Alternatively, setting that option to `true` will provide a default -[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html). - -The default [`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) uses the basic -[`Object.is`](https://mathematic-inc.github.io/ts-japi/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) -function to determine if input data are the same. If you want to adjust this, instantiate a new -[`Cache`](https://mathematic-inc.github.io/ts-japi/classes/cache.html) with a -[`resolver`](https://mathematic-inc.github.io/ts-japi/interfaces/cacheoptions.html#resolver). - -## Deserialization - -We stress the following: Given that there are many clients readily built to consume JSON:API -endpoints (see [here](https://jsonapi.org/implementations/)), we do not provide deserialization. In -particular, since unmarshalling data is strongly related to the code it will be used in (e.g. -React), tighter integration is recommended over an unnecessary abstraction. - -## Remarks - -There are several model classes used inside TS:JAPI such as `Resource` and `Relationships`. These -models are used for normalization as well as traversing a JSON:API document. If you plan to fork -this repo, you can extend these models and reimplement them to create your own custom (non-standard, -extended) serializer. - -## FAQ - -> Why not just allow optional functions that return the internal `Link` Class (or just a URI -> `string`)? - -The `Link` class is defined to be as general as possible in case of changes in the specification. In -particular, the implementation of metadata and the types in our library rely on the generality of -the `Link` class. Relying on user arguments will generate a lot of overhead for both us and users -whenever the specs change. - -> Why does the `Meta` class exist if it is essentially just a plain object? - -In case the specification is updated to change the meta objects in some functional way. - -> What is "resource recursion"? - -Due to [compound documents](https://jsonapi.org/format/#document-compound-documents), it is possible -to recurse through related resources via their -[resource linkages](https://jsonapi.org/format/#document-resource-object-linkage) and obtain -[included resources](https://jsonapi.org/format/#document-top-level) beyond primary data relations. -This is should be done with caution (see -[`SerializerOptions.depth`](https://mathematic-inc.github.io/ts-japi/interfaces/serializeroptions.html#depth) -and -[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/resource-recursion.example.ts)) - -## For Developers - -To get started in developing this library, run `yarn install`, `yarn build` and `yarn test` (in this -precise order) to assure everything is in working order. - -## Contributing - -This project is maintained by the author, however contributions are welcome and appreciated. You can -find TS:JAPI on GitHub: -[https://github.com/mathematic-inc/ts-japi](https://github.com/mathematic-inc/ts-japi) - -Feel free to submit an issue, but please do not submit pull requests unless it is to fix some issue. -For more information, read the -[contribution guide](https://github.com/mathematic-inc/ts-japi/blob/master/CONTRIBUTING.html). - -## License - -Copyright © 2020 [mathematic-inc](https://github.com/mathematic-inc). - -Licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/package.json b/package.json index dab80e9..536ccd8 100644 --- a/package.json +++ b/package.json @@ -5,12 +5,10 @@ "main": "lib/index.js", "packageManager": "pnpm@10.31.0+sha512.e3927388bfaa8078ceb79b748ffc1e8274e84d75163e67bc22e06c0d3aed43dd153151cbf11d7f8301ff4acb98c68bdc5cadf6989532801ffafe3b3e4a63c268", "scripts": { - "api-extractor": "api-extractor run", "benchmark": "ts-node ./benchmarks/serializer.benchmark", "build": "tsc", "clean": "make clean", "commitlint": "commitlint --from=HEAD~1", - "docs": "npm run api-extractor && ts-node tools/generate_docs.ts", "format": "ultracite fix", "examples": "ts-node ./examples/", "lint": "ultracite check", @@ -51,8 +49,6 @@ "@changesets/cli": "^2.30.0", "@commitlint/cli": "^20.4.3", "@commitlint/config-conventional": "^20.4.3", - "@microsoft/api-documenter": "^7.29.7", - "@microsoft/api-extractor": "^7.57.7", "@types/benchmark": "^2.1.5", "@types/jest": "^30.0.0", "@types/lodash": "^4.17.24", @@ -67,8 +63,6 @@ "npm-run-all": "^4.1.5", "regenerator-runtime": "^0.14.1", "ts-node": "^10.9.2", - "typedoc": "^0.28.17", - "typedoc-plugin-markdown": "^4.10.0", "typescript": "^5.9.3", "ultracite": "^7.2.5", "uuid": "^13.0.0" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 499179c..10c527d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -41,12 +41,6 @@ importers: '@commitlint/config-conventional': specifier: ^20.4.3 version: 20.4.3 - '@microsoft/api-documenter': - specifier: ^7.29.7 - version: 7.29.7(@types/node@25.4.0) - '@microsoft/api-extractor': - specifier: ^7.57.7 - version: 7.57.7(@types/node@25.4.0) '@types/benchmark': specifier: ^2.1.5 version: 2.1.5 @@ -89,12 +83,6 @@ importers: ts-node: specifier: ^10.9.2 version: 10.9.2(@types/node@25.4.0)(typescript@5.9.3) - typedoc: - specifier: ^0.28.17 - version: 0.28.17(typescript@5.9.3) - typedoc-plugin-markdown: - specifier: ^4.10.0 - version: 4.10.0(typedoc@0.28.17(typescript@5.9.3)) typescript: specifier: ^5.9.3 version: 5.9.3 @@ -935,9 +923,6 @@ packages: '@emnapi/wasi-threads@1.1.0': resolution: {integrity: sha512-WI0DdZ8xFSbgMjR1sFsKABJ/C5OnRrjT06JXbZKexJGrDuPTzZdDYfFlsgcCXCyf+suG5QU2e/y1Wo2V/OapLQ==} - '@gerrit0/mini-shiki@3.23.0': - resolution: {integrity: sha512-bEMORlG0cqdjVyCEuU0cDQbORWX+kYCeo0kV1lbxF5bt4r7SID2l9bqsxJEM0zndaxpOUT7riCyIVEuqq/Ynxg==} - '@inquirer/external-editor@1.0.3': resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==} engines: {node: '>=18'} @@ -1066,23 +1051,6 @@ packages: '@manypkg/get-packages@1.1.3': resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==} - '@microsoft/api-documenter@7.29.7': - resolution: {integrity: sha512-hBI9sBwyhSNfLxSoP2IOZcFOwqYeRG6uRc5scEeBD2oaz+jrJ3mwe/amSiY4Dz/Q8RWCLCWHf1WYqabEmhMlug==} - hasBin: true - - '@microsoft/api-extractor-model@7.33.4': - resolution: {integrity: sha512-u1LTaNTikZAQ9uK6KG1Ms7nvNedsnODnspq/gH2dcyETWvH4hVNGNDvRAEutH66kAmxA4/necElqGNs1FggC8w==} - - '@microsoft/api-extractor@7.57.7': - resolution: {integrity: sha512-kmnmVs32MFWbV5X6BInC1/TfCs7y1ugwxv1xHsAIj/DyUfoe7vtO0alRUgbQa57+yRGHBBjlNcEk33SCAt5/dA==} - hasBin: true - - '@microsoft/tsdoc-config@0.18.1': - resolution: {integrity: sha512-9brPoVdfN9k9g0dcWkFeA7IH9bbcttzDJlXvkf8b2OBzd5MueR1V2wkKBL0abn0otvmkHJC6aapBOTJDDeMCZg==} - - '@microsoft/tsdoc@0.16.0': - resolution: {integrity: sha512-xgAyonlVVS+q7Vc7qLW0UrJU7rSFcETRWsqdXZtjzRU8dF+6CkozTK4V4y1LwOX7j8r/vHphjDeMeGI4tNGeGA==} - '@napi-rs/wasm-runtime@0.2.12': resolution: {integrity: sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==} @@ -1109,51 +1077,6 @@ packages: resolution: {integrity: sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==} engines: {node: ^12.20.0 || ^14.18.0 || >=16.0.0} - '@rushstack/node-core-library@5.20.3': - resolution: {integrity: sha512-95JgEPq2k7tHxhF9/OJnnyHDXfC9cLhhta0An/6MlkDsX2A6dTzDrTUG18vx4vjc280V0fi0xDH9iQczpSuWsw==} - peerDependencies: - '@types/node': '*' - peerDependenciesMeta: - '@types/node': - optional: true - - '@rushstack/problem-matcher@0.2.1': - resolution: {integrity: sha512-gulfhBs6n+I5b7DvjKRfhMGyUejtSgOHTclF/eONr8hcgF1APEDjhxIsfdUYYMzC3rvLwGluqLjbwCFZ8nxrog==} - peerDependencies: - '@types/node': '*' - peerDependenciesMeta: - '@types/node': - optional: true - - '@rushstack/rig-package@0.7.2': - resolution: {integrity: sha512-9XbFWuqMYcHUso4mnETfhGVUSaADBRj6HUAAEYk50nMPn8WRICmBuCphycQGNB3duIR6EEZX3Xj3SYc2XiP+9A==} - - '@rushstack/terminal@0.22.3': - resolution: {integrity: sha512-gHC9pIMrUPzAbBiI4VZMU7Q+rsCzb8hJl36lFIulIzoceKotyKL3Rd76AZ2CryCTKEg+0bnTj406HE5YY5OQvw==} - peerDependencies: - '@types/node': '*' - peerDependenciesMeta: - '@types/node': - optional: true - - '@rushstack/ts-command-line@5.3.3': - resolution: {integrity: sha512-c+ltdcvC7ym+10lhwR/vWiOhsrm/bP3By2VsFcs5qTKv+6tTmxgbVrtJ5NdNjANiV5TcmOZgUN+5KYQ4llsvEw==} - - '@shikijs/engine-oniguruma@3.23.0': - resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==} - - '@shikijs/langs@3.23.0': - resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==} - - '@shikijs/themes@3.23.0': - resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==} - - '@shikijs/types@3.23.0': - resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==} - - '@shikijs/vscode-textmate@10.0.2': - resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==} - '@simple-libs/stream-utils@1.2.0': resolution: {integrity: sha512-KxXvfapcixpz6rVEB6HPjOUZT22yN6v0vI0urQSk1L8MlEWPDFCZkhw2xmkyoTGYeFw7tWTZd7e3lVzRZRN/EA==} engines: {node: '>=18'} @@ -1182,9 +1105,6 @@ packages: '@tybys/wasm-util@0.10.1': resolution: {integrity: sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==} - '@types/argparse@1.0.38': - resolution: {integrity: sha512-ebDJ9b0e702Yr7pWgB0jzm+CX4Srzz8RcXtLJDJB+BSccqMa36uyH/zUsSYao5+BD1ytv3k3rPYCq4mAE1hsXA==} - '@types/babel__core@7.20.5': resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==} @@ -1200,9 +1120,6 @@ packages: '@types/benchmark@2.1.5': resolution: {integrity: sha512-cKio2eFB3v7qmKcvIHLUMw/dIx/8bhWPuzpzRT4unCPRTD8VdA9Zb0afxpcxOqR4PixRS7yT42FqGS8BYL8g1w==} - '@types/hast@3.0.4': - resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} - '@types/istanbul-lib-coverage@2.0.6': resolution: {integrity: sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w==} @@ -1227,9 +1144,6 @@ packages: '@types/stack-utils@2.0.3': resolution: {integrity: sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw==} - '@types/unist@3.0.3': - resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} - '@types/uuid@11.0.0': resolution: {integrity: sha512-HVyk8nj2m+jcFRNazzqyVKiZezyhDKrGUA3jlEcg/nZ6Ms+qHwocba1Y/AaVaznJTAM9xpdFSh+ptbNrhOGvZA==} deprecated: This is a stub types definition. uuid provides its own type definitions, so you do not need this installed. @@ -1355,22 +1269,6 @@ packages: engines: {node: '>=0.4.0'} hasBin: true - ajv-draft-04@1.0.0: - resolution: {integrity: sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==} - peerDependencies: - ajv: ^8.5.0 - peerDependenciesMeta: - ajv: - optional: true - - ajv-formats@3.0.1: - resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==} - peerDependencies: - ajv: ^8.0.0 - peerDependenciesMeta: - ajv: - optional: true - ajv@8.18.0: resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==} @@ -1731,10 +1629,6 @@ packages: resolution: {integrity: sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==} engines: {node: '>=0.3.1'} - diff@8.0.3: - resolution: {integrity: sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==} - engines: {node: '>=0.3.1'} - dir-glob@3.0.1: resolution: {integrity: sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==} engines: {node: '>=8'} @@ -1767,10 +1661,6 @@ packages: resolution: {integrity: sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==} engines: {node: '>=8.6'} - entities@4.5.0: - resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} - engines: {node: '>=0.12'} - env-paths@2.2.1: resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==} engines: {node: '>=6'} @@ -1873,10 +1763,6 @@ packages: resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==} engines: {node: '>=14'} - fs-extra@11.3.4: - resolution: {integrity: sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==} - engines: {node: '>=14.14'} - fs-extra@7.0.1: resolution: {integrity: sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==} engines: {node: '>=6 <7 || >=8'} @@ -2037,10 +1923,6 @@ packages: resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==} engines: {node: '>=6'} - import-lazy@4.0.0: - resolution: {integrity: sha512-rKtvo6a868b5Hu3heneU+L4yEQ4jYKLtjpnPeUdK7h0yzXGmyBTypknlkCvHFBqfX9YlorEiMM6Dnq/5atfHkw==} - engines: {node: '>=8'} - import-local@3.2.0: resolution: {integrity: sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA==} engines: {node: '>=8'} @@ -2364,9 +2246,6 @@ packages: resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==} hasBin: true - jju@1.4.0: - resolution: {integrity: sha512-8wb9Yw966OSxApiCt0K3yNJL8pnNeIv+OEq2YMidz4FKP6nonSRoOXc80iXY4JaN2FC11B9qsNmDsm+ZOfMROA==} - js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} @@ -2403,9 +2282,6 @@ packages: jsonfile@4.0.0: resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==} - jsonfile@6.2.0: - resolution: {integrity: sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==} - lefthook-darwin-arm64@2.1.3: resolution: {integrity: sha512-VMSQK5ZUh66mKrEpHt5U81BxOg5xAXLoLZIK6e++4uc28tj8zGBqV9+tZqSRElXXzlnHbfdDVCMaKlTuqUy0Rg==} cpu: [arm64] @@ -2467,9 +2343,6 @@ packages: lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} - linkify-it@5.0.0: - resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==} - load-json-file@4.0.0: resolution: {integrity: sha512-Kx8hMakjX03tiGTLAIdJ+lL0htKnXjEZN6hk/tozf/WOuYGdZBJrZ+rCJRbVCugsjB3jMLn9746NsQIf5VjBMw==} engines: {node: '>=4'} @@ -2512,13 +2385,6 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} - lru-cache@6.0.0: - resolution: {integrity: sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==} - engines: {node: '>=10'} - - lunr@2.3.9: - resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} - make-dir@2.1.0: resolution: {integrity: sha512-LS9X+dc8KLxXCb8dni79fLIIUA5VyZoyjSMCwTluaXA0o27cCK0bhXkpgw+sTXVpPy/lSO57ilRixqk0vDmtRA==} engines: {node: '>=6'} @@ -2533,17 +2399,10 @@ packages: makeerror@1.0.12: resolution: {integrity: sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==} - markdown-it@14.1.1: - resolution: {integrity: sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==} - hasBin: true - math-intrinsics@1.1.0: resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} engines: {node: '>= 0.4'} - mdurl@2.0.0: - resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==} - memorystream@0.3.1: resolution: {integrity: sha512-S3UwM3yj5mtUSEfP41UZmt/0SCoVYUcU1rkXv+BQ5Ig8ndL4sPoJNBUJERafdPb5jjHJGuMgytgKvKIf58XNBw==} engines: {node: '>= 0.10.0'} @@ -2571,10 +2430,6 @@ packages: resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==} engines: {node: '>=6'} - minimatch@10.2.3: - resolution: {integrity: sha512-Rwi3pnapEqirPSbWbrZaa6N3nmqq4Xer/2XooiOKyV3q12ML06f7MOuc5DVH8ONZIFhwIYQ3yzPH4nt7iWHaTg==} - engines: {node: 18 || 20 || >=22} - minimatch@10.2.4: resolution: {integrity: sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==} engines: {node: 18 || 20 || >=22} @@ -2792,10 +2647,6 @@ packages: resolution: {integrity: sha512-oG4T3wCbfeuvljnyAzhBvpN45E8iOTXCU/TD3zXW80HA3dQ4ahdqMkWGiPWZvjpQwlbyHrPTWUAqUzGzv4l1JQ==} engines: {node: ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0} - punycode.js@2.3.1: - resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} - engines: {node: '>=6'} - pure-rand@7.0.1: resolution: {integrity: sha512-oTUZM/NAZS8p7ANR3SHh30kXB+zK2r2BPcEn/awJIbOvq82WoMN4p62AWWp3Hhw50G0xMsw1mhIBLqHw64EcNQ==} @@ -2904,11 +2755,6 @@ packages: resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==} hasBin: true - semver@7.5.4: - resolution: {integrity: sha512-1bCSESV6Pv+i21Hvpxp3Dx+pSD8lIPt8uVjRrxAUt/nbswYc+tK6Y2btiULjd4+fnq15PX+nqQDC7Oft7WkwcA==} - engines: {node: '>=10'} - hasBin: true - semver@7.7.4: resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==} engines: {node: '>=10'} @@ -3017,10 +2863,6 @@ packages: resolution: {integrity: sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ==} engines: {node: '>= 0.4'} - string-argv@0.3.2: - resolution: {integrity: sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==} - engines: {node: '>=0.6.19'} - string-length@4.0.2: resolution: {integrity: sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ==} engines: {node: '>=10'} @@ -3153,32 +2995,11 @@ packages: resolution: {integrity: sha512-3KS2b+kL7fsuk/eJZ7EQdnEmQoaho/r6KUef7hxvltNA5DR8NAUM+8wJMbJyZ4G9/7i3v5zPBIMN5aybAh2/Jg==} engines: {node: '>= 0.4'} - typedoc-plugin-markdown@4.10.0: - resolution: {integrity: sha512-psrg8Rtnv4HPWCsoxId+MzEN8TVK5jeKCnTbnGAbTBqcDapR9hM41bJT/9eAyKn9C2MDG9Qjh3MkltAYuLDoXg==} - engines: {node: '>= 18'} - peerDependencies: - typedoc: 0.28.x - - typedoc@0.28.17: - resolution: {integrity: sha512-ZkJ2G7mZrbxrKxinTQMjFqsCoYY6a5Luwv2GKbTnBCEgV2ihYm5CflA9JnJAwH0pZWavqfYxmDkFHPt4yx2oDQ==} - engines: {node: '>= 18', pnpm: '>= 10'} - hasBin: true - peerDependencies: - typescript: 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x - - typescript@5.8.2: - resolution: {integrity: sha512-aJn6wq13/afZp/jT9QZmwEjDqqvSGp1VT5GVg+f/t6/oVyrgXM6BY1h9BRh/O5p3PlUPAe+WuiEZOmb/49RqoQ==} - engines: {node: '>=14.17'} - hasBin: true - typescript@5.9.3: resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} engines: {node: '>=14.17'} hasBin: true - uc.micro@2.1.0: - resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} - ultracite@7.2.5: resolution: {integrity: sha512-Fw+V7P/gzTcVz6wmyYxaw8AGIOYDOilzwEiQq7pDGjrHwqdSzNrzevh1wxk0FTYfSHhk5a+wX02/Ayu8IK/x0A==} hasBin: true @@ -3215,10 +3036,6 @@ packages: resolution: {integrity: sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==} engines: {node: '>= 4.0.0'} - universalify@2.0.1: - resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==} - engines: {node: '>= 10.0.0'} - unrs-resolver@1.11.1: resolution: {integrity: sha512-bSjt9pjaEBnNiGgc9rUiHGKv5l4/TGzDmYw3RhnkJGtLhbnnA/5qJj7x3dNDCRx/PJxu774LlH8lCOlB4hEfKg==} @@ -3292,14 +3109,6 @@ packages: yallist@3.1.1: resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==} - yallist@4.0.0: - resolution: {integrity: sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==} - - yaml@2.8.2: - resolution: {integrity: sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==} - engines: {node: '>= 14.6'} - hasBin: true - yargs-parser@21.1.1: resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} engines: {node: '>=12'} @@ -4434,14 +4243,6 @@ snapshots: tslib: 2.8.1 optional: true - '@gerrit0/mini-shiki@3.23.0': - dependencies: - '@shikijs/engine-oniguruma': 3.23.0 - '@shikijs/langs': 3.23.0 - '@shikijs/themes': 3.23.0 - '@shikijs/types': 3.23.0 - '@shikijs/vscode-textmate': 10.0.2 - '@inquirer/external-editor@1.0.3(@types/node@25.4.0)': dependencies: chardet: 2.1.1 @@ -4685,54 +4486,6 @@ snapshots: globby: 11.1.0 read-yaml-file: 1.1.0 - '@microsoft/api-documenter@7.29.7(@types/node@25.4.0)': - dependencies: - '@microsoft/api-extractor-model': 7.33.4(@types/node@25.4.0) - '@microsoft/tsdoc': 0.16.0 - '@rushstack/node-core-library': 5.20.3(@types/node@25.4.0) - '@rushstack/terminal': 0.22.3(@types/node@25.4.0) - '@rushstack/ts-command-line': 5.3.3(@types/node@25.4.0) - js-yaml: 4.1.1 - resolve: 1.22.11 - transitivePeerDependencies: - - '@types/node' - - '@microsoft/api-extractor-model@7.33.4(@types/node@25.4.0)': - dependencies: - '@microsoft/tsdoc': 0.16.0 - '@microsoft/tsdoc-config': 0.18.1 - '@rushstack/node-core-library': 5.20.3(@types/node@25.4.0) - transitivePeerDependencies: - - '@types/node' - - '@microsoft/api-extractor@7.57.7(@types/node@25.4.0)': - dependencies: - '@microsoft/api-extractor-model': 7.33.4(@types/node@25.4.0) - '@microsoft/tsdoc': 0.16.0 - '@microsoft/tsdoc-config': 0.18.1 - '@rushstack/node-core-library': 5.20.3(@types/node@25.4.0) - '@rushstack/rig-package': 0.7.2 - '@rushstack/terminal': 0.22.3(@types/node@25.4.0) - '@rushstack/ts-command-line': 5.3.3(@types/node@25.4.0) - diff: 8.0.3 - lodash: 4.17.23 - minimatch: 10.2.3 - resolve: 1.22.11 - semver: 7.5.4 - source-map: 0.6.1 - typescript: 5.8.2 - transitivePeerDependencies: - - '@types/node' - - '@microsoft/tsdoc-config@0.18.1': - dependencies: - '@microsoft/tsdoc': 0.16.0 - ajv: 8.18.0 - jju: 1.4.0 - resolve: 1.22.11 - - '@microsoft/tsdoc@0.16.0': {} - '@napi-rs/wasm-runtime@0.2.12': dependencies: '@emnapi/core': 1.8.1 @@ -4760,65 +4513,6 @@ snapshots: '@pkgr/core@0.2.9': {} - '@rushstack/node-core-library@5.20.3(@types/node@25.4.0)': - dependencies: - ajv: 8.18.0 - ajv-draft-04: 1.0.0(ajv@8.18.0) - ajv-formats: 3.0.1(ajv@8.18.0) - fs-extra: 11.3.4 - import-lazy: 4.0.0 - jju: 1.4.0 - resolve: 1.22.11 - semver: 7.5.4 - optionalDependencies: - '@types/node': 25.4.0 - - '@rushstack/problem-matcher@0.2.1(@types/node@25.4.0)': - optionalDependencies: - '@types/node': 25.4.0 - - '@rushstack/rig-package@0.7.2': - dependencies: - resolve: 1.22.11 - strip-json-comments: 3.1.1 - - '@rushstack/terminal@0.22.3(@types/node@25.4.0)': - dependencies: - '@rushstack/node-core-library': 5.20.3(@types/node@25.4.0) - '@rushstack/problem-matcher': 0.2.1(@types/node@25.4.0) - supports-color: 8.1.1 - optionalDependencies: - '@types/node': 25.4.0 - - '@rushstack/ts-command-line@5.3.3(@types/node@25.4.0)': - dependencies: - '@rushstack/terminal': 0.22.3(@types/node@25.4.0) - '@types/argparse': 1.0.38 - argparse: 1.0.10 - string-argv: 0.3.2 - transitivePeerDependencies: - - '@types/node' - - '@shikijs/engine-oniguruma@3.23.0': - dependencies: - '@shikijs/types': 3.23.0 - '@shikijs/vscode-textmate': 10.0.2 - - '@shikijs/langs@3.23.0': - dependencies: - '@shikijs/types': 3.23.0 - - '@shikijs/themes@3.23.0': - dependencies: - '@shikijs/types': 3.23.0 - - '@shikijs/types@3.23.0': - dependencies: - '@shikijs/vscode-textmate': 10.0.2 - '@types/hast': 3.0.4 - - '@shikijs/vscode-textmate@10.0.2': {} - '@simple-libs/stream-utils@1.2.0': {} '@sinclair/typebox@0.34.48': {} @@ -4844,8 +4538,6 @@ snapshots: tslib: 2.8.1 optional: true - '@types/argparse@1.0.38': {} - '@types/babel__core@7.20.5': dependencies: '@babel/parser': 7.29.0 @@ -4869,10 +4561,6 @@ snapshots: '@types/benchmark@2.1.5': {} - '@types/hast@3.0.4': - dependencies: - '@types/unist': 3.0.3 - '@types/istanbul-lib-coverage@2.0.6': {} '@types/istanbul-lib-report@3.0.3': @@ -4898,8 +4586,6 @@ snapshots: '@types/stack-utils@2.0.3': {} - '@types/unist@3.0.3': {} - '@types/uuid@11.0.0': dependencies: uuid: 13.0.0 @@ -4977,14 +4663,6 @@ snapshots: acorn@8.16.0: {} - ajv-draft-04@1.0.0(ajv@8.18.0): - optionalDependencies: - ajv: 8.18.0 - - ajv-formats@3.0.1(ajv@8.18.0): - optionalDependencies: - ajv: 8.18.0 - ajv@8.18.0: dependencies: fast-deep-equal: 3.1.3 @@ -5368,8 +5046,6 @@ snapshots: diff@4.0.4: {} - diff@8.0.3: {} - dir-glob@3.0.1: dependencies: path-type: 4.0.0 @@ -5399,8 +5075,6 @@ snapshots: ansi-colors: 4.1.3 strip-ansi: 6.0.1 - entities@4.5.0: {} - env-paths@2.2.1: {} error-ex@1.3.4: @@ -5560,12 +5234,6 @@ snapshots: cross-spawn: 7.0.6 signal-exit: 4.1.0 - fs-extra@11.3.4: - dependencies: - graceful-fs: 4.2.11 - jsonfile: 6.2.0 - universalify: 2.0.1 - fs-extra@7.0.1: dependencies: graceful-fs: 4.2.11 @@ -5731,8 +5399,6 @@ snapshots: parent-module: 1.0.1 resolve-from: 4.0.0 - import-lazy@4.0.0: {} - import-local@3.2.0: dependencies: pkg-dir: 4.2.0 @@ -6242,8 +5908,6 @@ snapshots: jiti@2.6.1: {} - jju@1.4.0: {} - js-tokens@4.0.0: {} js-yaml@3.14.2: @@ -6271,12 +5935,6 @@ snapshots: optionalDependencies: graceful-fs: 4.2.11 - jsonfile@6.2.0: - dependencies: - universalify: 2.0.1 - optionalDependencies: - graceful-fs: 4.2.11 - lefthook-darwin-arm64@2.1.3: optional: true @@ -6324,10 +5982,6 @@ snapshots: lines-and-columns@1.2.4: {} - linkify-it@5.0.0: - dependencies: - uc.micro: 2.1.0 - load-json-file@4.0.0: dependencies: graceful-fs: 4.2.11 @@ -6363,12 +6017,6 @@ snapshots: dependencies: yallist: 3.1.1 - lru-cache@6.0.0: - dependencies: - yallist: 4.0.0 - - lunr@2.3.9: {} - make-dir@2.1.0: dependencies: pify: 4.0.1 @@ -6384,19 +6032,8 @@ snapshots: dependencies: tmpl: 1.0.5 - markdown-it@14.1.1: - dependencies: - argparse: 2.0.1 - entities: 4.5.0 - linkify-it: 5.0.0 - mdurl: 2.0.0 - punycode.js: 2.3.1 - uc.micro: 2.1.0 - math-intrinsics@1.1.0: {} - mdurl@2.0.0: {} - memorystream@0.3.1: {} meow@12.1.1: {} @@ -6414,10 +6051,6 @@ snapshots: mimic-fn@2.1.0: {} - minimatch@10.2.3: - dependencies: - brace-expansion: 5.0.4 - minimatch@10.2.4: dependencies: brace-expansion: 5.0.4 @@ -6608,8 +6241,6 @@ snapshots: ansi-styles: 5.2.0 react-is: 18.3.1 - punycode.js@2.3.1: {} - pure-rand@7.0.1: {} quansync@0.2.11: {} @@ -6728,10 +6359,6 @@ snapshots: semver@6.3.1: {} - semver@7.5.4: - dependencies: - lru-cache: 6.0.0 - semver@7.7.4: {} set-function-length@1.2.2: @@ -6847,8 +6474,6 @@ snapshots: es-errors: 1.3.0 internal-slot: 1.1.0 - string-argv@0.3.2: {} - string-length@4.0.2: dependencies: char-regex: 1.0.2 @@ -7004,25 +6629,8 @@ snapshots: possible-typed-array-names: 1.1.0 reflect.getprototypeof: 1.0.10 - typedoc-plugin-markdown@4.10.0(typedoc@0.28.17(typescript@5.9.3)): - dependencies: - typedoc: 0.28.17(typescript@5.9.3) - - typedoc@0.28.17(typescript@5.9.3): - dependencies: - '@gerrit0/mini-shiki': 3.23.0 - lunr: 2.3.9 - markdown-it: 14.1.1 - minimatch: 9.0.9 - typescript: 5.9.3 - yaml: 2.8.2 - - typescript@5.8.2: {} - typescript@5.9.3: {} - uc.micro@2.1.0: {} - ultracite@7.2.5: dependencies: '@clack/prompts': 1.1.0 @@ -7054,8 +6662,6 @@ snapshots: universalify@0.1.2: {} - universalify@2.0.1: {} - unrs-resolver@1.11.1: dependencies: napi-postinstall: 0.3.4 @@ -7177,10 +6783,6 @@ snapshots: yallist@3.1.1: {} - yallist@4.0.0: {} - - yaml@2.8.2: {} - yargs-parser@21.1.1: {} yargs@17.7.2: diff --git a/src/docs/README.md b/src/docs/README.md deleted file mode 100644 index c6ec923..0000000 --- a/src/docs/README.md +++ /dev/null @@ -1,231 +0,0 @@ -
-{ts:japi} -

- -![node-current](https://img.shields.io/node/v/ts-japi) -[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) - -> A highly-modular (typescript-friendly)-framework agnostic library for serializing data to the -> JSON:API specification - -- [Features](#features) -- [Documentation](#documentation) -- [Installation](#installation) -- [Getting Started](#getting-started) - - [Examples](#examples) -- [Serialization](#serialization) - - [Links](#links) - - [Pagination](#pagination) - - [Relationships](#relationships) - - [Metadata](#metadata) - - [Serializing Errors](#serializing-errors) - - [Caching](#caching) -- [Deserialization](#deserialization) -- [Remarks](#remarks) -- [FAQ](#faq) -- [For Developers](#for-developers) -- [Contributing](#contributing) -- [License](#license) - -## Features - -- This is the **only** typescript-compatible library that fully types the JSON:API specification and - performs _proper_ serialization. -- [**Zero dependencies**](#zdg). -- This is the **only** library with [resource recursion](#wirr). -- The modular framework laid out here _highly promotes_ the specifications intentions: - - Using links is no longer obfuscated. - - Meta can truly be placed anywhere with possible dependencies laid out visibly. -- This library is designed to adhere to the specifications "never remove, only add" policy, so we - will remain backwards-compatible. - -## Documentation - -The [documentation](https://mathematic-inc.github.io/ts-japi) has everything that is covered here -and more. - -## Installation - -You can install ts-japi in your project's directory as usual: - -```bash -npm install ts-japi -``` - -## Getting Started - -There are fives classes that are used to serialize data (only one of which is necessarily required). - -- {@link Serializer} with {@link SerializerOptions} -- {@link Relator} with {@link RelatorOptions} -- {@link Linker} with {@link LinkerOptions} -- {@link Metaizer} -- {@link Paginator} -- {@link ErrorSerializer} with {@link ErrorSerializerOptions} -- **NEW** {@link Cache} with {@link CacheOptions} - -You can check the [documentation](https://mathematic-inc.github.io/ts-japi) for a deeper insight -into the usage. - -### Examples - -You can check the [examples](https://github.com/mathematic-inc/ts-japi/tree/master/examples) and the -[test](https://github.com/mathematic-inc/ts-japi/tree/master/test) folders to see some examples -(such as the ones below). You can check -[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/full.example.ts) to -see almost every option of {@link Serializer} exhausted. - -## Serialization - -The {@link Serializer} class is the only class required for basic serialization. - -The following example constructs the most basic {@link Serializer}: (Note the `await`) - -```typescript -[[include:serializer.example.ts]] -``` - -### Links - -The {@link Linker} class is used to generate a normalized -[document link](https://jsonapi.org/format/#document-links). Its methods are not meant to be called. -See the [FAQ](#faq) for reasons. - -The following example constructs a {@link Linker} for `User`s and `Article`s: - -```typescript -[[include:linker.example.ts]] -``` - -#### Pagination - -The {@link Paginator} class is used to generate -[pagination links](https://jsonapi.org/format/#fetching-pagination). Its methods are not meant to be -called. - -The following example constructs a {@link Paginator}: - -```typescript -[[include:paginator.example.ts]] -``` - -### Relationships - -The {@link Relator} class is used to generate top-level -[included data](https://jsonapi.org/format/#document-top-level) as well as resource-level -[relationships](https://jsonapi.org/format/#document-resource-object-relationships). Its methods are -not meant to be called. - -{@link Relator}s may also take optional {@link Linker}s (using the {@link RelatorOptions.linkers | -linker} option) to define -[relationship links](https://jsonapi.org/format/#document-resource-object-relationships) and -[related resource links](https://jsonapi.org/format/#document-resource-object-related-resource-links). - -The following example constructs a {@link Relator} for `User`s and `Article`s: - -```typescript -[[include:relator.example.ts]] -``` - -### Metadata - -The {@link Metaizer} class is used to construct generate metadata given some dependencies. There are -several locations {@link Metaizer} can be used: - -- {@link ErrorSerializerOptions.metaizers} -- {@link RelatorOptions.metaizer} -- {@link SerializerOptions.metaizers} -- {@link LinkerOptions.metaizer} - -Like {@link Linker}, its methods are not meant to be called. - -The following example constructs a {@link Metaizer}: - -```typescript -[[include:metaizer.example.ts]] -``` - -### Serializing Errors - -The {@link ErrorSerializer} class is used to serialize any object considered an error (the {@link -ErrorSerializerOptions.attributes | attributes} option allows you to choose what attributes to use -during serialization). _Alternatively_ (**recommended**), you can construct custom errors by -extending the {@link JapiError} class and use those for all server-to-client errors. - -The -[error serializer test](https://github.com/mathematic-inc/ts-japi/tree/master/test/error-serializer.test.ts) -includes an example of the alternative solution. - -The following example constructs the most basic {@link ErrorSerializer}: (Note the lack of `await`) - -```typescript -[[include:error-serializer.example.ts]] -``` - -### Caching - -The {@link Cache} class can be placed in a {@link Serializer}'s {@link SerializerOptions.cache | -cache} option. Alternatively, setting that option to `true` will provide a default {@link Cache}. - -The default {@link Cache} uses the basic -[`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) -function to determine if input data are the same. If you want to adjust this, instantiate a new -{@link Cache} with a {@link CacheOptions.resolver | resolver}. - -## Deserialization - -We stress the following: Given that there are many clients readily built to consume JSON:API -endpoints (see [here](https://jsonapi.org/implementations/)), we do not provide deserialization. In -particular, since unmarshalling data is strongly related to the code it will be used in (e.g. -React), tighter integration is recommended over an unnecessary abstraction. - -## Remarks - -There are several model classes used inside TS:JAPI such as `Resource` and `Relationships`. These -models are used for normalization as well as traversing a JSON:API document. If you plan to fork -this repo, you can extend these models and reimplement them to create your own custom (non-standard, -extended) serializer. - -## FAQ - -> Why not just allow optional functions that return the internal `Link` Class (or just a URI -> `string`)? - -The `Link` class is defined to be as general as possible in case of changes in the specification. In -particular, the implementation of metadata and the types in our library rely on the generality of -the `Link` class. Relying on user arguments will generate a lot of overhead for both us and users -whenever the specs change. - -> Why does the `Meta` class exist if it is essentially just a plain object? - -In case the specification is updated to change the meta objects in some functional way. - -> What is "resource recursion"? - -Due to [compound documents](https://jsonapi.org/format/#document-compound-documents), it is possible -to recurse through related resources via their -[resource linkages](https://jsonapi.org/format/#document-resource-object-linkage) and obtain -[included resources](https://jsonapi.org/format/#document-top-level) beyond primary data relations. -This is should be done with caution (see {@link SerializerOptions.depth} and -[this example](https://github.com/mathematic-inc/ts-japi/blob/master/examples/resource-recursion.example.ts)) - -## For Developers - -To get started in developing this library, run `yarn install`, `yarn build` and `yarn test` (in this -precise order) to assure everything is in working order. - -## Contributing - -This project is maintained by the author, however contributions are welcome and appreciated. You can -find TS:JAPI on GitHub: -[https://github.com/mathematic-inc/ts-japi](https://github.com/mathematic-inc/ts-japi) - -Feel free to submit an issue, but please do not submit pull requests unless it is to fix some issue. -For more information, read the -[contribution guide](https://github.com/mathematic-inc/ts-japi/blob/master/CONTRIBUTING.md). - -## License - -Copyright © 2020 [mathematic-inc](https://github.com/mathematic-inc). - -Licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/tools/generate_docs.ts b/tools/generate_docs.ts deleted file mode 100644 index f69d743..0000000 --- a/tools/generate_docs.ts +++ /dev/null @@ -1,31 +0,0 @@ -/** - * Copyright 2022 Google Inc. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { copyFileSync } from "node:fs"; -import { join } from "node:path"; -import { chdir } from "node:process"; - -// eslint-disable-next-line import/extensions -import { generateDocs } from "./internal/custom_markdown_action"; - -// Change to root directory -chdir(join(import.meta.dirname, "..")); - -// README -copyFileSync("README.md", "docs/index.md"); - -// Generate documentation -generateDocs("docs/ts-japi.api.json", "docs/api"); diff --git a/tools/internal/custom_markdown_action.ts b/tools/internal/custom_markdown_action.ts deleted file mode 100644 index f384e85..0000000 --- a/tools/internal/custom_markdown_action.ts +++ /dev/null @@ -1,32 +0,0 @@ -/** - * Copyright 2022 Google Inc. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -import { ApiModel } from "@microsoft/api-extractor-model"; - -// eslint-disable-next-line import/extensions -import { MarkdownDocumenter } from "./custom_markdown_documenter"; - -export const generateDocs = (jsonPath: string, outputDir: string): void => { - const apiModel = new ApiModel(); - apiModel.loadPackage(jsonPath); - - const markdownDocumenter: MarkdownDocumenter = new MarkdownDocumenter({ - apiModel, - documenterConfig: undefined, - outputFolder: outputDir, - }); - markdownDocumenter.generateFiles(); -}; diff --git a/tools/internal/custom_markdown_documenter.ts b/tools/internal/custom_markdown_documenter.ts deleted file mode 100644 index 6c85b0a..0000000 --- a/tools/internal/custom_markdown_documenter.ts +++ /dev/null @@ -1,1441 +0,0 @@ -/** - * Copyright 2022 Google Inc. All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * https://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the -// MIT license. See LICENSE in the project root for license information. - -// Taken from -// https://github.com/microsoft/rushstack/blob/main/apps/api-documenter/src/documenters/MarkdownDocumenter.ts -// This file has been edited to morph into Docusaurus's expected inputs. - -import * as path from "node:path"; -import type { DocumenterConfig } from "@microsoft/api-documenter/lib/documenters/DocumenterConfig"; -import { CustomMarkdownEmitter } from "@microsoft/api-documenter/lib/markdown/CustomMarkdownEmitter"; -import { CustomDocNodes } from "@microsoft/api-documenter/lib/nodes/CustomDocNodeKind"; -import { DocEmphasisSpan } from "@microsoft/api-documenter/lib/nodes/DocEmphasisSpan"; -import { DocHeading } from "@microsoft/api-documenter/lib/nodes/DocHeading"; -import { DocNoteBox } from "@microsoft/api-documenter/lib/nodes/DocNoteBox"; -import { DocTable } from "@microsoft/api-documenter/lib/nodes/DocTable"; -import { DocTableCell } from "@microsoft/api-documenter/lib/nodes/DocTableCell"; -import { DocTableRow } from "@microsoft/api-documenter/lib/nodes/DocTableRow"; -import { MarkdownDocumenterAccessor } from "@microsoft/api-documenter/lib/plugin/MarkdownDocumenterAccessor"; -import { - type IMarkdownDocumenterFeatureOnBeforeWritePageArgs, - MarkdownDocumenterFeatureContext, -} from "@microsoft/api-documenter/lib/plugin/MarkdownDocumenterFeature"; -import { PluginLoader } from "@microsoft/api-documenter/lib/plugin/PluginLoader"; -import { Utilities } from "@microsoft/api-documenter/lib/utils/Utilities"; -import { - ApiClass, - ApiDeclaredItem, - ApiDocumentedItem, - type ApiEnum, - ApiInitializerMixin, - ApiInterface, - type ApiItem, - ApiItemKind, - type ApiModel, - type ApiNamespace, - ApiOptionalMixin, - type ApiPackage, - ApiParameterListMixin, - ApiPropertyItem, - ApiProtectedMixin, - ApiReadonlyMixin, - ApiReleaseTagMixin, - ApiReturnTypeMixin, - ApiStaticMixin, - ApiTypeAlias, - type Excerpt, - type ExcerptToken, - ExcerptTokenKind, - type IResolveDeclarationReferenceResult, - ReleaseTag, -} from "@microsoft/api-extractor-model"; -import { - type DocBlock, - DocCodeSpan, - type DocComment, - DocFencedCode, - DocLinkTag, - type DocNodeContainer, - DocNodeKind, - DocParagraph, - DocPlainText, - DocSection, - StandardTags, - StringBuilder, - type TSDocConfiguration, -} from "@microsoft/tsdoc"; -import { - FileSystem, - NewlineKind, - PackageName, -} from "@rushstack/node-core-library"; - -export interface IMarkdownDocumenterOptions { - apiModel: ApiModel; - documenterConfig: DocumenterConfig | undefined; - outputFolder: string; -} - -/** - * Renders API documentation in the Markdown file format. - * For more info: https://en.wikipedia.org/wiki/Markdown - */ -export class MarkdownDocumenter { - private readonly _apiModel: ApiModel; - private readonly _documenterConfig: DocumenterConfig | undefined; - private readonly _tsdocConfiguration: TSDocConfiguration; - private readonly _markdownEmitter: CustomMarkdownEmitter; - private readonly _outputFolder: string; - private readonly _pluginLoader: PluginLoader; - - public constructor(options: IMarkdownDocumenterOptions) { - this._apiModel = options.apiModel; - this._documenterConfig = options.documenterConfig; - this._outputFolder = options.outputFolder; - this._tsdocConfiguration = CustomDocNodes.configuration; - this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel); - - this._pluginLoader = new PluginLoader(); - } - - public generateFiles(): void { - if (this._documenterConfig) { - this._pluginLoader.load(this._documenterConfig, () => { - return new MarkdownDocumenterFeatureContext({ - apiModel: this._apiModel, - outputFolder: this._outputFolder, - documenter: new MarkdownDocumenterAccessor({ - getLinkForApiItem: (apiItem: ApiItem) => { - return this._getLinkFilenameForApiItem(apiItem); - }, - }), - }); - }); - } - - console.log(); - this._deleteOldOutputFiles(); - - this._writeApiItemPage(this._apiModel.members[0]!); - - if (this._pluginLoader.markdownDocumenterFeature) { - this._pluginLoader.markdownDocumenterFeature.onFinished({}); - } - } - - private _writeApiItemPage(apiItem: ApiItem): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - const output: DocSection = new DocSection({ - configuration: this._tsdocConfiguration, - }); - - const scopedName: string = apiItem.getScopedNameWithinPackage(); - - switch (apiItem.kind) { - case ApiItemKind.Class: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} class` }) - ); - break; - case ApiItemKind.Enum: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} enum` }) - ); - break; - case ApiItemKind.Interface: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} interface` }) - ); - break; - case ApiItemKind.Constructor: - case ApiItemKind.ConstructSignature: - output.appendNode(new DocHeading({ configuration, title: scopedName })); - break; - case ApiItemKind.Method: - case ApiItemKind.MethodSignature: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} method` }) - ); - break; - case ApiItemKind.Function: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} function` }) - ); - break; - case ApiItemKind.Model: - output.appendNode( - new DocHeading({ configuration, title: "API Reference" }) - ); - break; - case ApiItemKind.Namespace: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} namespace` }) - ); - break; - case ApiItemKind.Package: - console.log(`Writing ${apiItem.displayName} package`); - output.appendNode( - new DocHeading({ - configuration, - title: "API Reference", - }) - ); - break; - case ApiItemKind.Property: - case ApiItemKind.PropertySignature: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} property` }) - ); - break; - case ApiItemKind.TypeAlias: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} type` }) - ); - break; - case ApiItemKind.Variable: - output.appendNode( - new DocHeading({ configuration, title: `${scopedName} variable` }) - ); - break; - default: - throw new Error(`Unsupported API item kind: ${apiItem.kind}`); - } - - if ( - ApiReleaseTagMixin.isBaseClassOf(apiItem) && - apiItem.releaseTag === ReleaseTag.Beta - ) { - this._writeBetaWarning(output); - } - - const decoratorBlocks: DocBlock[] = []; - - if (apiItem instanceof ApiDocumentedItem) { - const tsdocComment: DocComment | undefined = apiItem.tsdocComment; - - if (tsdocComment) { - decoratorBlocks.push( - ...tsdocComment.customBlocks.filter((block) => { - return ( - block.blockTag.tagNameWithUpperCase === - StandardTags.decorator.tagNameWithUpperCase - ); - }) - ); - - if (tsdocComment.deprecatedBlock) { - output.appendNode( - new DocNoteBox({ configuration: this._tsdocConfiguration }, [ - new DocParagraph({ configuration: this._tsdocConfiguration }, [ - new DocPlainText({ - configuration: this._tsdocConfiguration, - text: "Warning: This API is now obsolete. ", - }), - ]), - ...tsdocComment.deprecatedBlock.content.nodes, - ]) - ); - } - - this._appendSection(output, tsdocComment.summarySection); - } - } - - if (apiItem instanceof ApiDeclaredItem) { - if (apiItem.excerpt.text.length > 0) { - output.appendNode( - new DocParagraph({ configuration }, [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Signature:" }), - ]), - ]) - ); - - let code: string; - switch (apiItem.parent?.kind) { - case ApiItemKind.Class: - code = `class ${apiItem.parent.displayName} {${apiItem.getExcerptWithModifiers()}}`; - break; - case ApiItemKind.Interface: - code = `interface ${apiItem.parent.displayName} {${apiItem.getExcerptWithModifiers()}}`; - break; - default: - code = apiItem.getExcerptWithModifiers(); - } - output.appendNode( - new DocFencedCode({ - configuration, - code, - language: "typescript", - }) - ); - } - - this._writeHeritageTypes(output, apiItem); - } - - if (decoratorBlocks.length > 0) { - output.appendNode( - new DocParagraph({ configuration }, [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Decorators:" }), - ]), - ]) - ); - for (const decoratorBlock of decoratorBlocks) { - output.appendNodes(decoratorBlock.content.nodes); - } - } - - let appendRemarks = true; - switch (apiItem.kind) { - case ApiItemKind.Class: - case ApiItemKind.Interface: - case ApiItemKind.Namespace: - case ApiItemKind.Package: - this._writeRemarksSection(output, apiItem); - appendRemarks = false; - break; - } - - switch (apiItem.kind) { - case ApiItemKind.Class: - this._writeClassTables(output, apiItem as ApiClass); - break; - case ApiItemKind.Enum: - this._writeEnumTables(output, apiItem as ApiEnum); - break; - case ApiItemKind.Interface: - this._writeInterfaceTables(output, apiItem as ApiInterface); - break; - case ApiItemKind.Constructor: - case ApiItemKind.ConstructSignature: - case ApiItemKind.Method: - case ApiItemKind.MethodSignature: - case ApiItemKind.Function: - this._writeParameterTables(output, apiItem as ApiParameterListMixin); - this._writeThrowsSection(output, apiItem); - break; - case ApiItemKind.Namespace: - this._writePackageOrNamespaceTables(output, apiItem as ApiNamespace); - break; - case ApiItemKind.Model: - this._writeModelTable(output, apiItem as ApiModel); - break; - case ApiItemKind.Package: - this._writePackageOrNamespaceTables(output, apiItem as ApiPackage); - break; - case ApiItemKind.Property: - case ApiItemKind.PropertySignature: - break; - case ApiItemKind.TypeAlias: - break; - case ApiItemKind.Variable: - break; - default: - throw new Error(`Unsupported API item kind: ${apiItem.kind}`); - } - - if (appendRemarks) { - this._writeRemarksSection(output, apiItem); - } - - const filename: string = path.join( - this._outputFolder, - this._getFilenameForApiItem(apiItem) - ); - const stringBuilder: StringBuilder = new StringBuilder(); - - this._markdownEmitter.emit(stringBuilder, output, { - contextApiItem: apiItem, - onGetFilenameForApiItem: (apiItemForFilename: ApiItem) => { - return this._getLinkFilenameForApiItem(apiItemForFilename); - }, - }); - - let pageContent: string = stringBuilder.toString(); - - if (this._pluginLoader.markdownDocumenterFeature) { - // Allow the plugin to customize the pageContent - const eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs = { - apiItem, - outputFilename: filename, - pageContent, - }; - this._pluginLoader.markdownDocumenterFeature.onBeforeWritePage(eventArgs); - pageContent = eventArgs.pageContent; - } - - pageContent = - `---\nsidebar_label: ${this._getSidebarLabelForApiItem(apiItem)}\n---` + - pageContent; - pageContent = pageContent.replace("##", "#"); - pageContent = pageContent.replace(//g, ""); - pageContent = pageContent.replace(/|<\/b>/g, "**"); - FileSystem.writeFile(filename, pageContent, { - convertLineEndings: this._documenterConfig - ? this._documenterConfig.newlineKind - : NewlineKind.CrLf, - }); - } - - private _writeHeritageTypes( - output: DocSection, - apiItem: ApiDeclaredItem - ): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - if (apiItem instanceof ApiClass) { - if (apiItem.extendsType) { - const extendsParagraph: DocParagraph = new DocParagraph( - { configuration }, - [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Extends: " }), - ]), - ] - ); - this._appendExcerptWithHyperlinks( - extendsParagraph, - apiItem.extendsType.excerpt - ); - output.appendNode(extendsParagraph); - } - if (apiItem.implementsTypes.length > 0) { - const extendsParagraph: DocParagraph = new DocParagraph( - { configuration }, - [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Implements: " }), - ]), - ] - ); - let needsComma = false; - for (const implementsType of apiItem.implementsTypes) { - if (needsComma) { - extendsParagraph.appendNode( - new DocPlainText({ configuration, text: ", " }) - ); - } - this._appendExcerptWithHyperlinks( - extendsParagraph, - implementsType.excerpt - ); - needsComma = true; - } - output.appendNode(extendsParagraph); - } - } - - if (apiItem instanceof ApiInterface && apiItem.extendsTypes.length > 0) { - const extendsParagraph: DocParagraph = new DocParagraph( - { configuration }, - [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Extends: " }), - ]), - ] - ); - let needsComma = false; - for (const extendsType of apiItem.extendsTypes) { - if (needsComma) { - extendsParagraph.appendNode( - new DocPlainText({ configuration, text: ", " }) - ); - } - this._appendExcerptWithHyperlinks( - extendsParagraph, - extendsType.excerpt - ); - needsComma = true; - } - output.appendNode(extendsParagraph); - } - - if (apiItem instanceof ApiTypeAlias) { - const refs: ExcerptToken[] = apiItem.excerptTokens.filter((token) => { - return ( - token.kind === ExcerptTokenKind.Reference && - token.canonicalReference && - this._apiModel.resolveDeclarationReference( - token.canonicalReference, - undefined - ).resolvedApiItem - ); - }); - if (refs.length > 0) { - const referencesParagraph: DocParagraph = new DocParagraph( - { configuration }, - [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "References: " }), - ]), - ] - ); - let needsComma = false; - const visited: Set = new Set(); - for (const ref of refs) { - if (visited.has(ref.text)) { - continue; - } - visited.add(ref.text); - - if (needsComma) { - referencesParagraph.appendNode( - new DocPlainText({ configuration, text: ", " }) - ); - } - - this._appendExcerptTokenWithHyperlinks(referencesParagraph, ref); - needsComma = true; - } - output.appendNode(referencesParagraph); - } - } - } - - private _writeRemarksSection(output: DocSection, apiItem: ApiItem): void { - if (apiItem instanceof ApiDocumentedItem) { - const tsdocComment: DocComment | undefined = apiItem.tsdocComment; - - if (tsdocComment) { - // Write the @remarks block - if (tsdocComment.remarksBlock) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Remarks", - }) - ); - this._appendSection(output, tsdocComment.remarksBlock.content); - } - - // Write the @example blocks - const exampleBlocks: DocBlock[] = tsdocComment.customBlocks.filter( - (x) => { - return ( - x.blockTag.tagNameWithUpperCase === - StandardTags.example.tagNameWithUpperCase - ); - } - ); - - let exampleNumber = 1; - for (const exampleBlock of exampleBlocks) { - const heading: string = - exampleBlocks.length > 1 ? `Example ${exampleNumber}` : "Example"; - - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: heading, - }) - ); - - this._appendSection(output, exampleBlock.content); - - ++exampleNumber; - } - } - } - } - - private _writeThrowsSection(output: DocSection, apiItem: ApiItem): void { - if (apiItem instanceof ApiDocumentedItem) { - const tsdocComment: DocComment | undefined = apiItem.tsdocComment; - - if (tsdocComment) { - // Write the @throws blocks - const throwsBlocks: DocBlock[] = tsdocComment.customBlocks.filter( - (x) => { - return ( - x.blockTag.tagNameWithUpperCase === - StandardTags.throws.tagNameWithUpperCase - ); - } - ); - - if (throwsBlocks.length > 0) { - const heading = "Exceptions"; - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: heading, - }) - ); - - for (const throwsBlock of throwsBlocks) { - this._appendSection(output, throwsBlock.content); - } - } - } - } - } - - /** - * GENERATE PAGE: MODEL - */ - private _writeModelTable(output: DocSection, apiModel: ApiModel): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const packagesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Package", "Description"], - }); - - for (const apiMember of apiModel.members) { - const row: DocTableRow = new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createDescriptionCell(apiMember), - ]); - - switch (apiMember.kind) { - case ApiItemKind.Package: - packagesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - } - } - - if (packagesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Packages", - }) - ); - output.appendNode(packagesTable); - } - } - - /** - * GENERATE PAGE: PACKAGE or NAMESPACE - */ - private _writePackageOrNamespaceTables( - output: DocSection, - apiContainer: ApiPackage | ApiNamespace - ): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const classesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Class", "Description"], - }); - - const enumerationsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Enumeration", "Description"], - }); - - const functionsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Function", "Description"], - }); - - const interfacesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Interface", "Description"], - }); - - const namespacesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Namespace", "Description"], - }); - - const variablesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Variable", "Description"], - }); - - const typeAliasesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Type Alias", "Description"], - }); - - const apiMembers: readonly ApiItem[] = - apiContainer.kind === ApiItemKind.Package - ? (apiContainer as ApiPackage).entryPoints[0]?.members - : (apiContainer as ApiNamespace).members; - - for (const apiMember of apiMembers) { - const row: DocTableRow = new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createDescriptionCell(apiMember), - ]); - - switch (apiMember.kind) { - case ApiItemKind.Class: - classesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.Enum: - enumerationsTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.Interface: - interfacesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.Namespace: - namespacesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.Function: - functionsTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.TypeAlias: - typeAliasesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - - case ApiItemKind.Variable: - variablesTable.addRow(row); - this._writeApiItemPage(apiMember); - break; - } - } - - if (classesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Classes", - }) - ); - output.appendNode(classesTable); - } - - if (enumerationsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Enumerations", - }) - ); - output.appendNode(enumerationsTable); - } - if (functionsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Functions", - }) - ); - output.appendNode(functionsTable); - } - - if (interfacesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Interfaces", - }) - ); - output.appendNode(interfacesTable); - } - - if (namespacesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Namespaces", - }) - ); - output.appendNode(namespacesTable); - } - - if (variablesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Variables", - }) - ); - output.appendNode(variablesTable); - } - - if (typeAliasesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Type Aliases", - }) - ); - output.appendNode(typeAliasesTable); - } - } - - /** - * GENERATE PAGE: CLASS - */ - private _writeClassTables(output: DocSection, apiClass: ApiClass): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const eventsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Property", "Modifiers", "Type", "Description"], - }); - - const constructorsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Constructor", "Modifiers", "Description"], - }); - - const propertiesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Property", "Modifiers", "Type", "Description"], - }); - - const methodsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Method", "Modifiers", "Description"], - }); - - for (const apiMember of apiClass.members) { - switch (apiMember.kind) { - case ApiItemKind.Constructor: { - constructorsTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - - this._writeApiItemPage(apiMember); - break; - } - case ApiItemKind.Method: { - methodsTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - - this._writeApiItemPage(apiMember); - break; - } - case ApiItemKind.Property: { - if ((apiMember as ApiPropertyItem).isEventProperty) { - eventsTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createPropertyTypeCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - } else { - propertiesTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createPropertyTypeCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - } - - this._writeApiItemPage(apiMember); - break; - } - } - } - - if (eventsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Events", - }) - ); - output.appendNode(eventsTable); - } - - if (constructorsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Constructors", - }) - ); - output.appendNode(constructorsTable); - } - - if (propertiesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Properties", - }) - ); - output.appendNode(propertiesTable); - } - - if (methodsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Methods", - }) - ); - output.appendNode(methodsTable); - } - } - - /** - * GENERATE PAGE: ENUM - */ - private _writeEnumTables(output: DocSection, apiEnum: ApiEnum): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const enumMembersTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Member", "Value", "Description"], - }); - - for (const apiEnumMember of apiEnum.members) { - enumMembersTable.addRow( - new DocTableRow({ configuration }, [ - new DocTableCell({ configuration }, [ - new DocParagraph({ configuration }, [ - new DocPlainText({ - configuration, - text: Utilities.getConciseSignature(apiEnumMember), - }), - ]), - ]), - this._createInitializerCell(apiEnumMember), - this._createDescriptionCell(apiEnumMember), - ]) - ); - } - - if (enumMembersTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Enumeration Members", - }) - ); - output.appendNode(enumMembersTable); - } - } - - /** - * GENERATE PAGE: INTERFACE - */ - private _writeInterfaceTables( - output: DocSection, - apiClass: ApiInterface - ): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const eventsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Property", "Modifiers", "Type", "Description"], - }); - - const propertiesTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Property", "Modifiers", "Type", "Description"], - }); - - const methodsTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Method", "Description"], - }); - - for (const apiMember of apiClass.members) { - switch (apiMember.kind) { - case ApiItemKind.ConstructSignature: - case ApiItemKind.MethodSignature: { - methodsTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - - this._writeApiItemPage(apiMember); - break; - } - case ApiItemKind.PropertySignature: { - if ((apiMember as ApiPropertyItem).isEventProperty) { - eventsTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createPropertyTypeCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - } else { - propertiesTable.addRow( - new DocTableRow({ configuration }, [ - this._createTitleCell(apiMember), - this._createModifiersCell(apiMember), - this._createPropertyTypeCell(apiMember), - this._createDescriptionCell(apiMember), - ]) - ); - } - - this._writeApiItemPage(apiMember); - break; - } - } - } - - if (eventsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Events", - }) - ); - output.appendNode(eventsTable); - } - - if (propertiesTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Properties", - }) - ); - output.appendNode(propertiesTable); - } - - if (methodsTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Methods", - }) - ); - output.appendNode(methodsTable); - } - } - - /** - * GENERATE PAGE: FUNCTION-LIKE - */ - private _writeParameterTables( - output: DocSection, - apiParameterListMixin: ApiParameterListMixin - ): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const parametersTable: DocTable = new DocTable({ - configuration, - headerTitles: ["Parameter", "Type", "Description"], - }); - for (const apiParameter of apiParameterListMixin.parameters) { - const parameterDescription: DocSection = new DocSection({ - configuration, - }); - - if (apiParameter.isOptional) { - parameterDescription.appendNodesInParagraph([ - new DocEmphasisSpan({ configuration, italic: true }, [ - new DocPlainText({ configuration, text: "(Optional)" }), - ]), - new DocPlainText({ configuration, text: " " }), - ]); - } - - if (apiParameter.tsdocParamBlock) { - this._appendAndMergeSection( - parameterDescription, - apiParameter.tsdocParamBlock.content - ); - } - - parametersTable.addRow( - new DocTableRow({ configuration }, [ - new DocTableCell({ configuration }, [ - new DocParagraph({ configuration }, [ - new DocPlainText({ configuration, text: apiParameter.name }), - ]), - ]), - new DocTableCell({ configuration }, [ - this._createParagraphForTypeExcerpt( - apiParameter.parameterTypeExcerpt - ), - ]), - new DocTableCell({ configuration }, parameterDescription.nodes), - ]) - ); - } - - if (parametersTable.rows.length > 0) { - output.appendNode( - new DocHeading({ - configuration: this._tsdocConfiguration, - title: "Parameters", - }) - ); - output.appendNode(parametersTable); - } - - if (ApiReturnTypeMixin.isBaseClassOf(apiParameterListMixin)) { - const returnTypeExcerpt: Excerpt = - apiParameterListMixin.returnTypeExcerpt; - output.appendNode( - new DocParagraph({ configuration }, [ - new DocEmphasisSpan({ configuration, bold: true }, [ - new DocPlainText({ configuration, text: "Returns:" }), - ]), - ]) - ); - - output.appendNode(this._createParagraphForTypeExcerpt(returnTypeExcerpt)); - - if ( - apiParameterListMixin instanceof ApiDocumentedItem && - apiParameterListMixin.tsdocComment && - apiParameterListMixin.tsdocComment.returnsBlock - ) { - this._appendSection( - output, - apiParameterListMixin.tsdocComment.returnsBlock.content - ); - } - } - } - - private _createParagraphForTypeExcerpt(excerpt: Excerpt): DocParagraph { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const paragraph: DocParagraph = new DocParagraph({ configuration }); - if (excerpt.text.trim()) { - this._appendExcerptWithHyperlinks(paragraph, excerpt); - } else { - paragraph.appendNode( - new DocPlainText({ configuration, text: "(not declared)" }) - ); - } - - return paragraph; - } - - private _appendExcerptWithHyperlinks( - docNodeContainer: DocNodeContainer, - excerpt: Excerpt - ): void { - for (const token of excerpt.spannedTokens) { - this._appendExcerptTokenWithHyperlinks(docNodeContainer, token); - } - } - - private _appendExcerptTokenWithHyperlinks( - docNodeContainer: DocNodeContainer, - token: ExcerptToken - ): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - // Markdown doesn't provide a standardized syntax for hyperlinks inside code - // spans, so we will render the type expression as DocPlainText. Instead of - // creating multiple DocParagraphs, we can simply discard any newlines and - // let the renderer do normal word-wrapping. - const unwrappedTokenText: string = token.text.replace(/[\r\n]+/g, " "); - - // If it's hyperlinkable, then append a DocLinkTag - if (token.kind === ExcerptTokenKind.Reference && token.canonicalReference) { - const apiItemResult: IResolveDeclarationReferenceResult = - this._apiModel.resolveDeclarationReference( - token.canonicalReference, - undefined - ); - - if (apiItemResult.resolvedApiItem) { - docNodeContainer.appendNode( - new DocLinkTag({ - configuration, - tagName: "@link", - linkText: unwrappedTokenText, - urlDestination: this._getLinkFilenameForApiItem( - apiItemResult.resolvedApiItem - ), - }) - ); - return; - } - } - - // Otherwise append non-hyperlinked text - docNodeContainer.appendNode( - new DocPlainText({ configuration, text: unwrappedTokenText }) - ); - } - - private _createTitleCell(apiItem: ApiItem): DocTableCell { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - let linkText: string = Utilities.getConciseSignature(apiItem); - if (ApiOptionalMixin.isBaseClassOf(apiItem) && apiItem.isOptional) { - linkText += "?"; - } - - return new DocTableCell({ configuration }, [ - new DocParagraph({ configuration }, [ - new DocLinkTag({ - configuration, - tagName: "@link", - linkText, - urlDestination: this._getLinkFilenameForApiItem(apiItem), - }), - ]), - ]); - } - - /** - * This generates a DocTableCell for an ApiItem including the summary section - * and "(BETA)" annotation. - * - * @remarks - * We mostly assume that the input is an ApiDocumentedItem, but it's easier to - * perform this as a runtime check than to have each caller perform a type - * cast. - */ - private _createDescriptionCell(apiItem: ApiItem): DocTableCell { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const section: DocSection = new DocSection({ configuration }); - - if ( - ApiReleaseTagMixin.isBaseClassOf(apiItem) && - apiItem.releaseTag === ReleaseTag.Beta - ) { - section.appendNodesInParagraph([ - new DocEmphasisSpan({ configuration, bold: true, italic: true }, [ - new DocPlainText({ configuration, text: "(BETA)" }), - ]), - new DocPlainText({ configuration, text: " " }), - ]); - } - - if (ApiOptionalMixin.isBaseClassOf(apiItem) && apiItem.isOptional) { - section.appendNodesInParagraph([ - new DocEmphasisSpan({ configuration, italic: true }, [ - new DocPlainText({ configuration, text: "(Optional)" }), - ]), - new DocPlainText({ configuration, text: " " }), - ]); - } - - if ( - apiItem instanceof ApiDocumentedItem && - apiItem.tsdocComment !== undefined - ) { - this._appendAndMergeSection(section, apiItem.tsdocComment.summarySection); - } - - return new DocTableCell({ configuration }, section.nodes); - } - - private _createModifiersCell(apiItem: ApiItem): DocTableCell { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const section: DocSection = new DocSection({ configuration }); - - if (ApiProtectedMixin.isBaseClassOf(apiItem) && apiItem.isProtected) { - section.appendNode( - new DocParagraph({ configuration }, [ - new DocCodeSpan({ configuration, code: "protected" }), - ]) - ); - } - - if (ApiReadonlyMixin.isBaseClassOf(apiItem) && apiItem.isReadonly) { - section.appendNode( - new DocParagraph({ configuration }, [ - new DocCodeSpan({ configuration, code: "readonly" }), - ]) - ); - } - - if (ApiStaticMixin.isBaseClassOf(apiItem) && apiItem.isStatic) { - section.appendNode( - new DocParagraph({ configuration }, [ - new DocCodeSpan({ configuration, code: "static" }), - ]) - ); - } - - return new DocTableCell({ configuration }, section.nodes); - } - - private _createPropertyTypeCell(apiItem: ApiItem): DocTableCell { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const section: DocSection = new DocSection({ configuration }); - - if (apiItem instanceof ApiPropertyItem) { - section.appendNode( - this._createParagraphForTypeExcerpt(apiItem.propertyTypeExcerpt) - ); - } - - return new DocTableCell({ configuration }, section.nodes); - } - - private _createInitializerCell(apiItem: ApiItem): DocTableCell { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - - const section: DocSection = new DocSection({ configuration }); - - if ( - ApiInitializerMixin.isBaseClassOf(apiItem) && - apiItem.initializerExcerpt - ) { - section.appendNodeInParagraph( - new DocCodeSpan({ - configuration, - code: apiItem.initializerExcerpt.text, - }) - ); - } - - return new DocTableCell({ configuration }, section.nodes); - } - - private _writeBetaWarning(output: DocSection): void { - const configuration: TSDocConfiguration = this._tsdocConfiguration; - const betaWarning: string = - "This API is provided as a preview for developers and may change" + - " based on feedback that we receive. Do not use this API in a production environment."; - output.appendNode( - new DocNoteBox({ configuration }, [ - new DocParagraph({ configuration }, [ - new DocPlainText({ configuration, text: betaWarning }), - ]), - ]) - ); - } - - private _appendSection(output: DocSection, docSection: DocSection): void { - for (const node of docSection.nodes) { - output.appendNode(node); - } - } - - private _appendAndMergeSection( - output: DocSection, - docSection: DocSection - ): void { - let firstNode = true; - for (const node of docSection.nodes) { - if (firstNode && node.kind === DocNodeKind.Paragraph) { - output.appendNodesInParagraph(node.getChildNodes()); - firstNode = false; - continue; - } - firstNode = false; - - output.appendNode(node); - } - } - - private _getSidebarLabelForApiItem(apiItem: ApiItem): string { - if (apiItem.kind === ApiItemKind.Package) { - return "API"; - } - - let baseName = ""; - for (const hierarchyItem of apiItem.getHierarchy()) { - // For overloaded methods, add a suffix such as "MyClass.myMethod_2". - let qualifiedName: string = hierarchyItem.displayName; - if ( - ApiParameterListMixin.isBaseClassOf(hierarchyItem) && - hierarchyItem.overloadIndex > 1 - ) { - // Subtract one for compatibility with earlier releases of API Documenter. - // (This will get revamped when we fix GitHub issue #1308) - qualifiedName += `_${hierarchyItem.overloadIndex - 1}`; - } - - switch (hierarchyItem.kind) { - case ApiItemKind.Model: - case ApiItemKind.EntryPoint: - case ApiItemKind.EnumMember: - case ApiItemKind.Package: - break; - default: - baseName += `${qualifiedName}.`; - } - } - return baseName.slice(0, baseName.length - 1); - } - - private _getFilenameForApiItem(apiItem: ApiItem): string { - if (apiItem.kind === ApiItemKind.Package) { - return "index.md"; - } - - let baseName = ""; - for (const hierarchyItem of apiItem.getHierarchy()) { - // For overloaded methods, add a suffix such as "MyClass.myMethod_2". - let qualifiedName: string = Utilities.getSafeFilenameForName( - hierarchyItem.displayName - ); - if ( - ApiParameterListMixin.isBaseClassOf(hierarchyItem) && - hierarchyItem.overloadIndex > 1 - ) { - // Subtract one for compatibility with earlier releases of API Documenter. - // (This will get revamped when we fix GitHub issue #1308) - qualifiedName += `_${hierarchyItem.overloadIndex - 1}`; - } - - switch (hierarchyItem.kind) { - case ApiItemKind.Model: - case ApiItemKind.EntryPoint: - case ApiItemKind.EnumMember: - break; - case ApiItemKind.Package: - baseName = Utilities.getSafeFilenameForName( - PackageName.getUnscopedName(hierarchyItem.displayName) - ); - break; - default: - baseName += `.${qualifiedName}`; - } - } - return `${baseName}.md`; - } - - private _getLinkFilenameForApiItem(apiItem: ApiItem): string { - return `./${this._getFilenameForApiItem(apiItem)}`; - } - - private _deleteOldOutputFiles(): void { - console.log(`Deleting old output from ${this._outputFolder}`); - FileSystem.ensureEmptyFolder(this._outputFolder); - } -}