@teamteanpm2024/ab-deserunt-culpa

Generates Typescript/Javascript decoders source code expressions from JSON schema specifications.

You can also try it in your browser with any JSON schema.

Description

This package aims to provide the best possible conversion of a JSON Schema type into it's equivalent decoder function.

It has a wide support of different features from different JSON Schema drafts, check the Support Matrix for more details.

Installation

To use the CLI you can install the package globally:

npm install -g @teamteanpm2024/ab-deserunt-culpa

To use it as a library in your package, install it locally:

npm install --dev @teamteanpm2024/ab-deserunt-culpa
# or
yarn add -D @teamteanpm2024/ab-deserunt-culpa

Usage

To convert a JSON definition file to decoders, use the following command CLI:

@teamteanpm2024/ab-deserunt-culpa <schema.json>

The package also exports an API that be used for more elaborate integrations:

import Converter from "@teamteanpm2024/ab-deserunt-culpa";

console.log(await Converter.convertFile("path/to/schema.json"));

API Reference

There are a few functios you can use for invoking the converter:

// Synchronous variations
convertSchema(schema: Schema, options?: ConverterOptions): string;
convertContents(buffer: string, options?: ConverterOptions): string;

// Asynchronous variations
convertFile(file: string, options?: ConverterOptions): Promise<string>;
convert(url: string | Schema, options?: ConverterOptions): Promise<string>;

The ConverterOptions have the following properties:

• nsPrefix: An optional namespace where to look for decoder functions into.

  For example, if you are importing the decoders like so:

  import * as D from "decoders";

  Then you can use:

  const code = convertSchema(schema, {
    nsPrefix: "D.",
  });

• nsLib: An optional namespace where to look for extra decoder library functions exposed by the @teamteanpm2024/ab-deserunt-culpa package.

  If not specified, all of the avanced decoders would be disabled.

  For example, if you can import the utility library like so:

  import * as L from "@teamteanpm2024/ab-deserunt-culpa/decoders";

  Then you can use:

  const code = convertSchema(schema, {
    nsLib: "L.",
  });

• resolveRefPointer : An optional function to call when a $ref is encountered. The returned value will replace the contents of that ref.

  For example, given the following logic:

  const schema = {
    type: "array",
    items: {
      $ref: "#/components/schema/Item",
    },
  };
  const code = convertSchema(schema, {
    resolveRefPointer: (expr) => {
      return expr.split("/").pop();
    },
  });

  Will produce the following code:

  array(Item);

• resolveRefSchema : An optional function to call when a $ref is encountered and the schema of it is required.

  In contrast to resolveRefPointer, where a variable reference is emitted, this function expects the value of the referred schema to be returned.

  If missing, resolveRefPointer would be used when possible, and if not, an exception would be thrown.

Support Matrix

The following table summarizes the supported conversion between JSON Schema types and decoders.

| Type | Validation / Keyword | Status | | :------------------ | :----------------------- | :----- | | All Types | enum | ✅ | | | const | ✅ | | References | Basic Support | ✅ [1] | | any | Basic Support | ✅ | | string | Basic Support | ✅ | | | minLength | ✅ | | | maxLength | ✅ | | | pattern | ✅ | | | format: "date-time | ✅ | | | format: "time | - | | | format: "date | - | | | format: "duration | - | | | format: "email | ✅ | | | format: "idn-email | - | | | format: "hostname | ✅ | | | format: "idn-hostname | - | | | format: "ipv4 | - | | | format: "ipv6 | - | | | format: "uuid | ✅ | | | format: "uri | ✅ | | | format: "uri-reference | - | | | format: "iri | - | | | format: "iri-reference | - | | integer | Basic Support | ✅ | | number | Basic Support | ✅ | | | multipleOf | ✅ | | | minimum | ✅ | | | maximum | ✅ | | | exclusiveMinimum | ✅ | | | exclusiveMaximum | ✅ | | boolean | Basic Support | ✅ | | null | Basic Support | ✅ | | array | Basic Support | ✅ | | | Unevaluated Items | - | | | items | ✅ | | | prefixItems | 🟨 [2] | | | contains | - | | | minContains | - | | | maxContains | - | | | minItems | ✅ | | | maxItems | ✅ | | | uniqueItems | ✅ | | object | Basic Support | ✅ [3] | | | Unevaluated Properties | - | | | Extending Closed Schemas | - | | | properties | ✅ | | | additionalProperties | ✅ | | | required | ✅ | | | patternProperties | ✅ | | | propertyNames | ✅ | | | minProperties | ✅ | | | maxProperties | ✅ | | Schema Composition | allOf | ✅ | | | oneOf | 🟨 [4] | | | anyOf | ✅ | | | discriminator | ✅ | | Conditional Schemas | dependentRequired | - | | | dependentSchemas | - | | | if | - | | | then | - | | | else | - |

Remarks:

[1] Implemented through a user-provided reference resolution function that returns the variable name of a previously defined decoder.

[2] Currently prefixItems cannot be used together with items. This means that declaring additional items for arrays is not supported.

[3] Note that while for type: "object" the JSON Schema spec indicates that "Using non-strings as keys is invalid JSON", the javascript implementation implicitly converts all properties to strings, so the decoders will always validate even numbers in the object keys.

[4] The oneOf is currently polyfilled with the anyOf behaviour. This means that the "exactly one" validation is not respected.