untyped

To use untyped, you must first define a reference object. This object describes the structure of your data, including types, default values, and optional $resolve normalizer methods.

Special keys available within the object:

• $resolve: A function used to normalize or transform a value.
• $default: The default value to use.
• $schema: Metadata for the field (e.g., a title).

const defaultPlanet = {
  name: "earth",
  specs: {
    gravity: {
      $resolve: (val) => Number.parseFloat(val),
      $default: "9.8",
    },
    moons: {
      $resolve: (val = ["moon"]) => [val].flat(),
      $schema: {
        title: "planet moons",
      },
    },
  },
};

You can install untyped using your preferred package manager. For automatic detection of your package manager, use nypm.

# ✨ Auto-detect
npx nypm install untyped

# npm
npm install untyped

# yarn
yarn add untyped

# pnpm
pnpm add untyped

# bun
bun install untyped

# deno
deno install npm:untyped

When defining your input objects, you can use specific keys to control schema generation:

• $schema: Used to provide existing schema information.
• $default: Defines a static default value for a property.
• $resolve: A function used for asynchronous default value resolution. It receives the current default value and a callback to fetch values from the root object.
• @required (in tags): If a property's tags array contains the string @required, that property will be added to the schema's required array.

const input = {
  // Static default
  port: { $default: 3000 },

  // Dynamic default via $resolve
  user: async (current, getRootValue) => {
    const root = await getRootValue('root_context');
    return root.defaultUser;
  },

  // Required field via tags
  apiKey: {
    tags: ['@required']
  }
};

The resolveSchema function takes a reference object and resolves it into a structured JSON schema. This schema includes processed types, defaults, and metadata.

import { resolveSchema } from "untyped";

const schema = await resolveSchema(defaultPlanet);

The generateMarkdown function converts a resolved schema into a Markdown string, providing a readable list of types and default values for each property.

import { resolveSchema, generateMarkdown } from "untyped";

const markdown = generateMarkdown(await resolveSchema(defaultPlanet));

The generateTypes function converts a resolved schema into a TypeScript interface string. It includes JSDoc comments for default values and schema metadata (like titles).

import { resolveSchema, generateTypes } from "untyped";

const types = generateTypes(await resolveSchema(defaultPlanet));

The resolveSchema function accepts an optional ResolveSchemaOptions object to modify its behavior.

The generateMarkdown function converts a Schema object into a single Markdown string. This is useful for programmatically creating documentation for your typed structures. It recursively traverses the schema, handling objects by nesting headers and representing types, defaults, titles, and descriptions in Markdown format. For function types, it includes a TypeScript signature.

import { generateMarkdown } from 'untyped/generator/md';

// Assuming 'schema' is a valid Schema object
const markdown = generateMarkdown(schema);
console.log(markdown);

The applyDefaults function uses a reference object (the schema definition) to populate missing values in an input object with their corresponding default values. This is useful for ensuring an input object conforms to a schema by filling in gaps.

import { applyDefaults } from 'untyped';

const schemaRef = {
  name: { $default: 'default-name' },
  count: { $default: 0 }
};

const input = { name: 'actual-name' };

// input will be mutated to include { count: 0 }
await applyDefaults(schemaRef, input);