@chubbyts/chubbyts-decode-encode 2.5.2 → 2.6.0

package/README.md

@@ -19,7 +19,9 @@
 
 ## Description
 
-A simple decode/encode solution for json / jsonx / url-encoded / xml / yaml.
+Decode and encode request/response bodies by content type: json, jsonx, url-encoded and yaml.
+
+Strings are decoded into plain data (objects, arrays, strings, numbers, booleans and null) and encoded back. Each format can be registered under additional content types, for example `application/problem+json` or `application/yaml`.
 
 ## Requirements
 
@@ -36,43 +38,65 @@ A simple decode/encode solution for json / jsonx / url-encoded / xml / yaml.
 
 Through [NPM](https://www.npmjs.com) as [@chubbyts/chubbyts-decode-encode][1].
 
-```ts
-npm i @chubbyts/chubbyts-decode-encode@^2.5.2
+```sh
+npm i @chubbyts/chubbyts-decode-encode@^2.6.0
 ```
 
 ## Usage
 
+### Data
+
+Every type decoder returns and every type encoder accepts `Data`, the json data model:
+
+```ts
+type Data = { [key: string]: Data } | Array<Data> | string | number | boolean | null;
+```
+
+The matching type guards `isNull`, `isBoolean`, `isNumber`, `isString`, `isArray` and `isObject` (plain objects only) can be imported from `@chubbyts/chubbyts-decode-encode/data`.
+
+```ts
+import { isObject } from '@chubbyts/chubbyts-decode-encode/data';
+
+isObject({ key: 'value' }); // true
+isObject(new Date()); // false
+```
+
 ### Decoder
 
 #### createDecoder
 
 ```ts
-import { createDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/decoder';
-import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/json-type-decoder';
+import { createDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/json-type-decoder';
 
 const decoder = createDecoder([createJsonTypeDecoder()]);
-const data = decoder.decode('{"key":"value"}', 'application/json'); // or with 3th argument, for example { user: 'username1' }
-// data: {key: "value"}
+const data = decoder.decode('{"key":"value"}', 'application/json');
+// data: { key: 'value' }
 const contentTypes = decoder.contentTypes;
 // contentTypes: ['application/json']
 ```
 
+The `Decoder` type accepts an optional third argument `context` (`Record<string, unknown>`). The shipped decoder ignores it, it exists for custom `Decoder` implementations, for example one that decodes depending on the current user.
+
 #### createJsonTypeDecoder
 
 ```ts
-import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/json-type-decoder';
+import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/json-type-decoder';
 
 const jsonTypeDecoder = createJsonTypeDecoder();
 const data = jsonTypeDecoder.decode('{"key":"value"}');
-// data: {key: "value"}
+// data: { key: 'value' }
 const contentType = jsonTypeDecoder.contentType;
 // contentType: 'application/json'
+
+// any other json based content type, like `application/problem+json` (RFC 9457)
+const problemJsonTypeDecoder = createJsonTypeDecoder('application/problem+json');
 ```
 
 #### createJsonxTypeDecoder
 
 ```ts
-import { createJsonxTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/jsonx-type-decoder';
+import { createJsonxTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/jsonx-type-decoder';
 
 const jsonxTypeDecoder = createJsonxTypeDecoder();
 const data = jsonxTypeDecoder.decode(`
@@ -81,7 +105,7 @@ const data = jsonxTypeDecoder.decode(`
   <json:string name="key">value</json:string>
 </json:object>
 `);
-// data: {key: "value"}
+// data: { key: 'value' }
 const contentType = jsonxTypeDecoder.contentType;
 // contentType: 'application/jsonx+xml'
 ```
@@ -89,25 +113,35 @@ const contentType = jsonxTypeDecoder.contentType;
 #### createUrlEncodedTypeDecoder
 
 ```ts
-import { createUrlEncodedTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/url-encoded-type-decoder';
+import { createUrlEncodedTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/url-encoded-type-decoder';
 
 const urlEncodedTypeDecoder = createUrlEncodedTypeDecoder();
 const data = urlEncodedTypeDecoder.decode('key=value');
-// data: {key: "value"}
+// data: { key: 'value' }
 const contentType = urlEncodedTypeDecoder.contentType;
 // contentType: 'application/x-www-form-urlencoded'
 ```
 
+Values are converted to their json type: `true` and `false` become booleans, `null` becomes `null` and a value becomes a number only if the number converts back to the exact same string, so `01` or `1.0` stay strings.
+
+```ts
+const data = urlEncodedTypeDecoder.decode('a=1&b=true&c=null&d=01&e[]=x');
+// data: { a: 1, b: true, c: null, d: '01', e: ['x'] }
+```
+
 #### createYamlTypeDecoder
 
 ```ts
-import { createYamlTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/yaml-type-decoder';
+import { createYamlTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/yaml-type-decoder';
 
 const yamlTypeDecoder = createYamlTypeDecoder();
 const data = yamlTypeDecoder.decode('key: value');
-// data: {key: "value"}
+// data: { key: 'value' }
 const contentType = yamlTypeDecoder.contentType;
 // contentType: 'application/x-yaml'
+
+// the registered media type `application/yaml` (RFC 9512)
+const officialYamlTypeDecoder = createYamlTypeDecoder('application/yaml');
 ```
 
 ### Encoder
@@ -115,82 +149,147 @@ const contentType = yamlTypeDecoder.contentType;
 #### createEncoder
 
 ```ts
-import { createEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/encoder';
-import { createJsonTypeEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/json-type-encoder';
+import { createEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/encoder';
+import { createJsonTypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/json-type-encoder';
 
 const encoder = createEncoder([createJsonTypeEncoder()]);
-const encodedData = encoder.encode({key: "value"}, 'application/json'); // or with 3th argument, for example { user: 'username1' }
-// encodedData: {"key":"value"}
+const encodedData = encoder.encode({ key: 'value' }, 'application/json');
+// encodedData: '{"key":"value"}'
 const contentTypes = encoder.contentTypes;
 // contentTypes: ['application/json']
 ```
 
+The `Encoder` type accepts an optional third argument `context` (`Record<string, unknown>`). The shipped encoder ignores it, it exists for custom `Encoder` implementations, for example one that encodes depending on the current user.
+
 #### createJsonTypeEncoder
 
 ```ts
-import { createJsonTypeEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/json-type-encoder';
+import { createJsonTypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/json-type-encoder';
 
 const jsonTypeEncoder = createJsonTypeEncoder();
-const encodedData = jsonTypeEncoder.encode({key: "value"});
-// encodedData: {"key":"value"}
+const encodedData = jsonTypeEncoder.encode({ key: 'value' });
+// encodedData: '{"key":"value"}'
 const contentType = jsonTypeEncoder.contentType;
-// contentTypes: 'application/json'
+// contentType: 'application/json'
+
+// pretty printed
+const prettyJsonTypeEncoder = createJsonTypeEncoder(true);
+
+// any other json based content type, like `application/problem+json` (RFC 9457)
+const problemJsonTypeEncoder = createJsonTypeEncoder(false, 'application/problem+json');
 ```
 
 #### createJsonxTypeEncoder
 
 ```ts
-import { createJsonxTypeEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/jsonx-type-encoder';
+import { createJsonxTypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/jsonx-type-encoder';
 
-const jsonxTypeEncoder = createJsonxTypeEncoder();
-const encodedData = jsonxTypeEncoder.encode({key: "value"});
-// encodedData: <?xml version="1.0" encoding="UTF-8"?>
-// <json:object>
+const jsonxTypeEncoder = createJsonxTypeEncoder(true); // pretty printed, defaults to false
+const encodedData = jsonxTypeEncoder.encode({ key: 'value' });
+// encodedData:
+// <?xml version="1.0" encoding="UTF-8"?>
+// <json:object xsi:schemaLocation="http://www.datapower.com/schemas/json jsonx.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:json="http://www.ibm.com/xmlns/prod/2009/jsonx">
 //   <json:string name="key">value</json:string>
 // </json:object>
 const contentType = jsonxTypeEncoder.contentType;
-// contentTypes: 'application/jsonx+xml'
+// contentType: 'application/jsonx+xml'
 ```
 
 #### createUrlEncodedTypeEncoder
 
 ```ts
-import { createUrlEncodedTypeEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/url-encoded-type-encoder';
+import { createUrlEncodedTypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/url-encoded-type-encoder';
 
 const urlEncodedTypeEncoder = createUrlEncodedTypeEncoder();
-const encodedData = urlEncodedTypeEncoder.encode({key: "value"});
-// encodedData: key=value
+const encodedData = urlEncodedTypeEncoder.encode({ a: 1, b: true, c: null, d: [1, 2] });
+// encodedData: 'a=1&b=true&c=null&d[0]=1&d[1]=2'
 const contentType = urlEncodedTypeEncoder.contentType;
-// contentTypes: 'application/x-www-form-urlencoded'
+// contentType: 'application/x-www-form-urlencoded'
 ```
 
 #### createYamlTypeEncoder
 
 ```ts
-import { createYamlTypeEncoder } from '@chubbyts/chubbyts-encode-encode/dist/encoder/yaml-type-encoder';
+import { createYamlTypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/yaml-type-encoder';
 
 const yamlTypeEncoder = createYamlTypeEncoder();
-const encodedData = yamlTypeEncoder.encode({key: "value"});
-// encodedData: key: value
+const encodedData = yamlTypeEncoder.encode({ key: 'value' });
+// encodedData: 'key: value\n'
 const contentType = yamlTypeEncoder.contentType;
-// contentTypes: 'application/x-yaml'
+// contentType: 'application/x-yaml'
+
+// the registered media type `application/yaml` (RFC 9512)
+const officialYamlTypeEncoder = createYamlTypeEncoder('application/yaml');
+```
+
+### Custom type decoders / encoders
+
+A type decoder / encoder is a plain object with a `contentType` and a `decode` / `encode` function. This adds [NDJSON](https://github.com/ndjson/ndjson-spec), one json document per line:
+
+```ts
+import type { Data } from '@chubbyts/chubbyts-decode-encode/data';
+import { isArray } from '@chubbyts/chubbyts-decode-encode/data';
+import type { TypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+import { DecodeError, createDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+import type { TypeEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/encoder';
+import { createEncoder } from '@chubbyts/chubbyts-decode-encode/encoder/encoder';
+
+const createNdjsonTypeDecoder = (): TypeDecoder => ({
+  decode: (encodedData: string): Data => {
+    try {
+      return encodedData
+        .split('\n')
+        .filter((line) => line.trim() !== '')
+        .map((line) => JSON.parse(line));
+    } catch (e) {
+      throw new DecodeError(e instanceof Error ? e.message : String(e));
+    }
+  },
+  contentType: 'application/x-ndjson',
+});
+
+const createNdjsonTypeEncoder = (): TypeEncoder => ({
+  encode: (data: Data): string => (isArray(data) ? data : [data]).map((item) => JSON.stringify(item)).join('\n'),
+  contentType: 'application/x-ndjson',
+});
+
+const decoder = createDecoder([createNdjsonTypeDecoder()]);
+const encoder = createEncoder([createNdjsonTypeEncoder()]);
+```
+
+### Errors
+
+* `decode` throws a `DecodeError` (`@chubbyts/chubbyts-decode-encode/decoder/decoder`) if the encoded data is invalid, for example a json syntax error. In a http context this usually maps to `400 Bad Request`.
+* `encode` of the jsonx type encoder throws an `EncodeError` (`@chubbyts/chubbyts-decode-encode/encoder/encoder`) if a value cannot be represented.
+* `decode` / `encode` of the decoder / encoder throw an `Error` if the content type is not supported, the message lists the supported content types. In a http context this usually maps to `415 Unsupported Media Type` (decoder) or `406 Not Acceptable` (encoder).
+
+```ts
+import { DecodeError } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+
+try {
+  decoder.decode('{', 'application/json');
+} catch (e) {
+  if (e instanceof DecodeError) {
+    // invalid request body
+  }
+}
 ```
 
 ### Service factories (chubbyts-dic-config)
 
-The package ships service factories (abstract factories built on [chubbyts-dic-config-factory][9]) for a [chubbyts-dic-config][8] (or any [chubbyts-dic-types][7] compatible) container within `@chubbyts/chubbyts-decode-encode/dist/service-factory`:
+The package ships service factories (abstract factories built on [chubbyts-dic-config-factory][9]) for a [chubbyts-dic-config][8] (or any [chubbyts-dic-types][7] compatible) container within `@chubbyts/chubbyts-decode-encode/service-factory`:
 
- * `typeDecodersServiceFactory`: all shipped type decoders (json, jsonx, urlencoded, yaml)
- * `typeEncodersServiceFactory`: all shipped type encoders (json, jsonx, urlencoded, yaml), `config.debug` enables pretty printing for json / jsonx
+ * `typeDecodersServiceFactory`: all shipped type decoders (json, jsonx, urlencoded, yaml as `application/x-yaml` and `application/yaml`)
+ * `typeEncodersServiceFactory`: all shipped type encoders (json, jsonx, urlencoded, yaml as `application/x-yaml` and `application/yaml`), `config.debug` enables pretty printing for json / jsonx
  * `decoderServiceFactory`: the decoder, built from the `typeDecoders` service if registered, the shipped type decoders otherwise
  * `encoderServiceFactory`: the encoder, built from the `typeEncoders` service if registered, the shipped type encoders otherwise
 
 ```ts
 import type { ConfigFactory } from '@chubbyts/chubbyts-dic-config/dist/dic-config';
 import { createContainerByConfigFactory } from '@chubbyts/chubbyts-dic-config/dist/dic-config';
-import type { Decoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/decoder';
-import type { Encoder } from '@chubbyts/chubbyts-decode-encode/dist/encoder/encoder';
-import { decoderServiceFactory, encoderServiceFactory } from '@chubbyts/chubbyts-decode-encode/dist/service-factory';
+import type { Decoder } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+import type { Encoder } from '@chubbyts/chubbyts-decode-encode/encoder/encoder';
+import { decoderServiceFactory, encoderServiceFactory } from '@chubbyts/chubbyts-decode-encode/service-factory';
 
 const container = createContainerByConfigFactory({
   debug: false,
@@ -206,17 +305,17 @@ const decoder = container.get<Decoder>('decoder');
 const encoder = container.get<Encoder>('encoder');
 ```
 
-To replace the type decoders / encoders, register a `typeDecoders` / `typeEncoders` service:
+To replace the type decoders / encoders, register a `typeDecoders` / `typeEncoders` service (`createNdjsonTypeDecoder` from [Custom type decoders / encoders](#custom-type-decoders--encoders)):
 
 ```ts
-import type { TypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/decoder';
-import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/dist/decoder/json-type-decoder';
+import type { TypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/decoder';
+import { createJsonTypeDecoder } from '@chubbyts/chubbyts-decode-encode/decoder/json-type-decoder';
 
 const container = createContainerByConfigFactory({
   dependencies: {
     factories: new Map<string, ConfigFactory>([
       ['decoder', decoderServiceFactory()],
-      ['typeDecoders', (): Array<TypeDecoder> => [createJsonTypeDecoder(), createCustomTypeDecoder()]],
+      ['typeDecoders', (): Array<TypeDecoder> => [createJsonTypeDecoder(), createNdjsonTypeDecoder()]],
     ]),
   },
 })();

package/dist/decoder/json-type-decoder.d.ts

@@ -1,2 +1,2 @@
 import type { TypeDecoder } from './decoder.js';
-export declare const createJsonTypeDecoder: () => TypeDecoder;
+export declare const createJsonTypeDecoder: (contentType?: string) => TypeDecoder;

package/dist/decoder/json-type-decoder.js

@@ -1,6 +1,6 @@
 import { throwableToError } from '@chubbyts/chubbyts-throwable-to-error/dist/throwable-to-error';
 import { DecodeError } from './decoder.js';
-export const createJsonTypeDecoder = () => {
+export const createJsonTypeDecoder = (contentType = 'application/json') => {
     return {
         decode: (encodedData) => {
             try {
@@ -11,6 +11,6 @@ export const createJsonTypeDecoder = () => {
                 throw new DecodeError(error.message, error.stack);
             }
         },
-        contentType: 'application/json',
+        contentType,
     };
 };

package/dist/decoder/yaml-type-decoder.d.ts

@@ -1,2 +1,2 @@
 import type { TypeDecoder } from './decoder.js';
-export declare const createYamlTypeDecoder: () => TypeDecoder;
+export declare const createYamlTypeDecoder: (contentType?: string) => TypeDecoder;

package/dist/decoder/yaml-type-decoder.js

@@ -1,7 +1,7 @@
 import { parse } from 'yaml';
 import { throwableToError } from '@chubbyts/chubbyts-throwable-to-error/dist/throwable-to-error';
 import { DecodeError } from './decoder.js';
-export const createYamlTypeDecoder = () => {
+export const createYamlTypeDecoder = (contentType = 'application/x-yaml') => {
     return {
         decode: (encodedData) => {
             try {
@@ -12,6 +12,6 @@ export const createYamlTypeDecoder = () => {
                 throw new DecodeError(error.message, error.stack);
             }
         },
-        contentType: 'application/x-yaml',
+        contentType,
     };
 };

package/dist/encoder/json-type-encoder.d.ts

@@ -1,2 +1,2 @@
 import type { TypeEncoder } from './encoder.js';
-export declare const createJsonTypeEncoder: (prettyPrint?: boolean) => TypeEncoder;
+export declare const createJsonTypeEncoder: (prettyPrint?: boolean, contentType?: string) => TypeEncoder;

package/dist/encoder/json-type-encoder.js

@@ -1,6 +1,6 @@
-export const createJsonTypeEncoder = (prettyPrint = false) => {
+export const createJsonTypeEncoder = (prettyPrint = false, contentType = 'application/json') => {
     return {
         encode: (data) => JSON.stringify(data, undefined, prettyPrint ? 4 : undefined),
-        contentType: 'application/json',
+        contentType,
     };
 };

package/dist/encoder/yaml-type-encoder.d.ts

@@ -1,2 +1,2 @@
 import type { TypeEncoder } from './encoder.js';
-export declare const createYamlTypeEncoder: () => TypeEncoder;
+export declare const createYamlTypeEncoder: (contentType?: string) => TypeEncoder;

package/dist/encoder/yaml-type-encoder.js

@@ -1,7 +1,7 @@
 import { stringify } from 'yaml';
-export const createYamlTypeEncoder = () => {
+export const createYamlTypeEncoder = (contentType = 'application/x-yaml') => {
     return {
         encode: (data) => stringify(data, { indent: 4 }),
-        contentType: 'application/x-yaml',
+        contentType,
     };
 };

package/dist/service-factory.js

@@ -10,7 +10,13 @@ import { createJsonxTypeEncoder } from './encoder/jsonx-type-encoder.js';
 import { createUrlEncodedTypeEncoder } from './encoder/url-encoded-type-encoder.js';
 import { createYamlTypeEncoder } from './encoder/yaml-type-encoder.js';
 export const typeDecodersServiceFactory = createAbstractFactory(() => {
-    return [createJsonTypeDecoder(), createJsonxTypeDecoder(), createUrlEncodedTypeDecoder(), createYamlTypeDecoder()];
+    return [
+        createJsonTypeDecoder(),
+        createJsonxTypeDecoder(),
+        createUrlEncodedTypeDecoder(),
+        createYamlTypeDecoder(),
+        createYamlTypeDecoder('application/yaml'),
+    ];
 });
 export const decoderServiceFactory = createAbstractFactory((container, { resolveDependency }) => {
     return createDecoder(resolveDependency(container, 'typeDecoders', typeDecodersServiceFactory));
@@ -22,6 +28,7 @@ export const typeEncodersServiceFactory = createAbstractFactory((container) => {
         createJsonxTypeEncoder(debug),
         createUrlEncodedTypeEncoder(),
         createYamlTypeEncoder(),
+        createYamlTypeEncoder('application/yaml'),
     ];
 });
 export const encoderServiceFactory = createAbstractFactory((container, { resolveDependency }) => {

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@chubbyts/chubbyts-decode-encode",
   "type": "module",
-  "version": "2.5.2",
-  "description": "A simple decode/encode solution for json / jsonx / url-encoded / xml / yaml.",
+  "version": "2.6.0",
+  "description": "Decode and encode request/response bodies by content type: json, jsonx, url-encoded and yaml.",
   "keywords": [
     "chubbyts",
+    "content-type",
     "decode",
     "encode",
     "json",
     "jsonx",
+    "serializer",
     "url-encoded",
     "xml",
     "yaml"
@@ -44,10 +46,15 @@
       "import": "./dist/encoder/index.js",
       "default": "./dist/encoder/index.js"
     },
+    "./dist/*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    },
     "./*": {
-      "types": "./*.d.ts",
-      "import": "./*.js",
-      "default": "./*.js"
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "engines": {