Compiler Markers

import {createValidateFn, createJsonEncoderFn} from '@ts-runtypes/core';

type Flag = {kind: 'on' | 'off'};

// These options are read by the BUILD, so they must be a literal written right
// at the call site — the build picks the specialized function from what it sees.
const isFlag = createValidateFn<Flag>(undefined, {noLiterals: true});
const encode = createJsonEncoderFn<Flag>(undefined, {strategy: 'direct'});

// A computed value is NOT a literal, so the build can't read it — this line
// fails compilation with a CTA diagnostic.
const looseAtNight = new Date().getHours() < 6;
createValidateFn<Flag>(undefined, {noLiterals: looseAtNight});

export {isFlag, encode};

// shared-config.ts
export const strict = {noLiterals: true} as const; // `as const` keeps the values literal

// anywhere.ts
createValidateFn<User>(undefined, strict);            // ok: a shared const, even imported
createValidateFn<User>(undefined, {noLiterals: true}); // ok: inline literal

import {getRunType, type InjectRunTypeId} from '@ts-runtypes/core';

// Wrap ts-runtypes into your OWN helper. Declare a trailing
// `id?: InjectRunTypeId<T>` parameter and the build fills it in at every
// call site — you never pass the id yourself.
function describe<T>(id?: InjectRunTypeId<T>): string {
  // The injected `id` is an OPAQUE handle, not a plain string. Resolve it by
  // forwarding it to a public resolver as the trailing argument: getRunType
  // registers T's type graph and returns the node (getRunTypeId returns the id
  // string). The build leaves this forwarded call untouched.
  const runType = getRunType<T>(undefined, id);
  return `type #${runType.id} (kind ${runType.kind})`;
}

// Call it like any generic function — no id argument in sight.
describe<{id: number; name: string}>();
describe<string[]>();

export {describe};

import {createValidateFn, type ValidateFn} from '@ts-runtypes/core';

// A realistic wrapper: parse JSON and validate it against your type in one call.
// A createX<T>() factory needs a CONCRETE type at its OWN call site, so build
// the validator where the type is known and pass it in. Calling
// `createValidateFn<T>()` inside this generic body would use the wrapper's free
// `T` (unknown at build time), which the build reports as MKR003.
function parseChecked<T>(raw: string, isValid: ValidateFn<T>): T {
  const data: unknown = JSON.parse(raw);
  if (!isValid(data)) throw new Error('payload does not match the expected type');
  return data as T;
}

type User = {id: number; name: string};

// createValidateFn<User>() runs at a concrete call site — the build injects here.
const user = parseChecked('{"id":1,"name":"Ada"}', createValidateFn<User>());

export {parseChecked, user};

import {createGetValidationErrorsFn, createJsonDecoderFn, createJsonEncoderFn, type InjectTypeFnArgs} from '@ts-runtypes/core';

// A single marker can ask for SEVERAL generated functions at once. A route
// wrapper wants to validate a request, decode it from JSON, and encode the
// response, so it names all three families in one trailing marker. The build
// injects an array of handles, one per family, in the order you listed them.
type Handler = (...args: any[]) => unknown;

function route<H extends Handler>(handler: H, fns?: InjectTypeFnArgs<Parameters<H>, 'verr', 'jsonDecoder', 'jsonEncoder'>) {
  const getErrors = createGetValidationErrorsFn(undefined, undefined, fns?.[0] as never);
  const decodeParams = createJsonDecoderFn(undefined, undefined, fns?.[1] as never);
  const encodeParams = createJsonEncoderFn(undefined, undefined, fns?.[2] as never);
  return {handler, getErrors, decodeParams, encodeParams};
}

// route() runs at a concrete call site, so the build injects the three handles
// for this handler's parameters here.
const greet = route((name: string, times: number) => name.repeat(times));

export {route, greet};

import {getRTFunction, type InjectTypeFnArgs} from '@ts-runtypes/core';

// Some functions the generated code is built from, like the per-strategy
// prepareForJson and restoreFromJson, have no createX factory of their own. You
// still reach them from a marker: name the primitive and recover the injected
// handle with getRTFunction, which turns it into the callable function for T.
// You pass the same key you named in the marker, so getRTFunction knows the
// function's type.
//
// 'pjs' is the clone prepare (a fresh JSON-safe value with undeclared keys
// dropped) and 'rj' is the matching restore. A framework that owns its own JSON
// envelope uses this pair to transform values without a string round-trip.
function jsonValueCodec<T>(fns?: InjectTypeFnArgs<T, 'pjs', 'rj'>) {
  const prepare = getRTFunction<'pjs'>(fns?.[0]);
  const restore = getRTFunction<'rj'>(fns?.[1]);
  return {prepare, restore};
}

type Message = {id: bigint; sentAt: Date; body: string};

// A concrete call site: the build injects the clone-prepare and restore handles
// for Message here.
const messageCodec = jsonValueCodec<Message>();

// prepare turns a typed value into a JSON-safe one and restore turns it back.
// The caller owns the JSON.stringify and JSON.parse, so many values can share
// one envelope with a single stringify and a single parse.
const message: Message = {id: 42n, sentAt: new Date('2020-01-02T03:04:05.000Z'), body: 'hi'};
const wire = JSON.stringify(messageCodec.prepare(message));
const restored = messageCodec.restore(JSON.parse(wire));

export {jsonValueCodec, messageCodec, restored};

import {getFnHash, getRunTypeId} from '@ts-runtypes/core';

// Every generated function is stored under a key with two parts: a short id for
// the FUNCTION (which family it belongs to, plus any compile-time options) and
// the id for the TYPE it works on, joined as `functionId_typeId`. A framework
// that already holds a type's id can rebuild that key itself with getFnHash. The
// ids getFnHash returns are stable across releases.

// The function id for the default validator.
const validateId = getFnHash('val');

// Options that change the generated function change its id too, and getFnHash
// follows them: a validator that skips literal checks is a different function.
const looseValidateId = getFnHash('val', {noLiterals: true});

// The JSON encoder has several strategies, and each one is its own function.
const encodeMutateId = getFnHash('jsonEncoder', {strategy: 'mutate'});

// Join the function id with a type id to get the full storage key. The type id
// is the same value getRunTypeId returns for that type.
type User = {id: number; name: string};
const userTypeId = getRunTypeId<User>();
const userValidatorKey = `${validateId}_${userTypeId}`;

export {validateId, looseValidateId, encodeMutateId, userValidatorKey};