Schema API

Generated public TypeScript reference for @relkit/schema.

Common APIs

• z
• validate

For configuration and examples, read Runtime schemas, requests, uploads.

For a complete workflow, follow upload product images.

Public imports

• @relkit/schema — 56 exports

All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.

builder-composites.ts

arraySchema

Builds an array validator from one item schema.

Example

arraySchema(z.number());

Signature

declare const arraySchema: <S extends AnySchema>(schema: S) => Schema<InputOf<S>[], OutputOf<S>[]>;

Source

objectSchema

Builds an object validator from named child schemas.

Example

objectSchema({ id: z.string() });

Signature

declare const objectSchema: <S extends Shape>(shape: S) => Schema<ObjectInput<S>, ObjectOutput<S>>;

Source

unionSchema

Builds a nonempty union with first-success precedence.

Example

unionSchema([z.string(), z.number()]);

Signature

declare const unionSchema: <S extends SchemaTuple>(
  schemas: S,
) => Schema<InputOf<S[number]>, OutputOf<S[number]>>;

Source

builder-composites.types.ts

AnySchema (type alias)

Any compatible validator accepted by a composite builder.

Example

const child: AnySchema = z.string();

Signature

type AnySchema = StandardSchemaV1;

Source

InputOf (type alias)

Accepted input of a child validator.

Example

type Input = InputOf<typeof schema>;

Signature

type InputOf<S extends AnySchema> = InferInput<S>;

Source

ObjectInput (type alias)

Object input with optional keys inferred from child schemas.

Example

type Input = ObjectInput<{ id: typeof idSchema }>;

Signature

type ObjectInput<S extends Shape> = {
  [K in RequiredInputKeys<S>]: InputOf<S[K]>;
} & {
  [K in OptionalInputKeys<S>]?: Exclude<InputOf<S[K]>, undefined>;
};

Source

ObjectOutput (type alias)

Object output with optional keys inferred from child schemas.

Example

type Output = ObjectOutput<{ id: typeof idSchema }>;

Signature

type ObjectOutput<S extends Shape> = {
  [K in RequiredOutputKeys<S>]: OutputOf<S[K]>;
} & {
  [K in OptionalOutputKeys<S>]?: Exclude<OutputOf<S[K]>, undefined>;
};

Source

OutputOf (type alias)

Validated output of a child validator.

Example

type Output = OutputOf<typeof schema>;

Signature

type OutputOf<S extends AnySchema> = InferOutput<S>;

Source

SchemaTuple (type alias)

Nonempty tuple of union members, preserving declaration order.

Example

const members: SchemaTuple = [z.string(), z.number()];

Signature

type SchemaTuple = readonly [AnySchema, ...AnySchema[]];

Source

Shape (type alias)

Named child validators for an object schema.

Example

const shape: Shape = { id: z.string() };

Signature

type Shape = Record<string, AnySchema>;

Source

builder-effect.ts

SchemaBuilderError (class)

Tagged failure when a schema builder rejects options or its dependencies throw. The original exception remains available in cause.

Example

Effect.catchTag("SchemaBuilderError", (error) => Effect.succeed(error.cause));

Signature

declare class SchemaBuilderError

Source

buildSchema

Runs a synchronous schema builder and preserves its original error.

Throws

The original construction error.

Example

buildSchema("builder.string", () => z.string());

Signature

declare const buildSchema: <A>(operation: SchemaOperation, build: () => A) => A;

Source

buildSchemaEffect

Constructs a schema inside an observed Effect.

Example

Effect.runSync(buildSchemaEffect("builder.string", () => z.string()));

Signature

declare const buildSchemaEffect: <A>(
  operation: SchemaOperation,
  build: () => A,
) => Effect.Effect<A, SchemaBuilderError>;

Source

builder-refinements.ts

numberSchema

Builds a finite-number schema with numeric refinements.

Example

numberSchema().int().parse(2);

Signature

declare const numberSchema: () => NumberSchema;

Source

stringSchema

Builds a string schema with format and length refinements.

Example

stringSchema().min(2).parse("ok");

Signature

declare const stringSchema: () => StringSchema;

Source

builder-refinements.types.ts

NumberSchema (interface)

Finite-number schema with range and integer refinement methods.

Example

const schema: NumberSchema = z.number().int();

Signature

export interface NumberSchema extends Schema<number, number> {
  /**
   * Requires an inclusive minimum.
   * @param value - Minimum value.
   * @param message - Optional issue text.
   * @returns A refined number schema.
   * @example z.number().min(1);
   */
  min(value: number, message?: string): NumberSchema;
  /**
   * Requires an inclusive maximum.
   * @param value - Maximum value.
   * @param message - Optional issue text.
   * @returns A refined number schema.
   * @example z.number().max(10);
   */
  max(value: number, message?: string): NumberSchema;
  /**
   * Requires an integer.
   * @param message - Optional issue text.
   * @returns An integer schema.
   * @example z.number().int();
   */
  int(message?: string): NumberSchema;
  /**
   * Requires a value above zero.
   * @param message - Optional issue text.
   * @returns A positive number schema.
   * @example z.number().positive();
   */
  positive(message?: string): NumberSchema;
  /**
   * Requires a value of zero or greater.
   * @param message - Optional issue text.
   * @returns A nonnegative number schema.
   * @example z.number().nonnegative();
   */
  nonnegative(message?: string): NumberSchema;
}

Source

StringSchema (interface)

String schema with length and format refinement methods.

Example

const schema: StringSchema = z.string().min(1);

Signature

export interface StringSchema extends Schema<string, string> {
  /**
   * Requires a minimum string length.
   * @param length - Minimum length.
   * @param message - Optional issue text.
   * @returns A refined string schema.
   * @example z.string().min(2);
   */
  min(length: number, message?: string): StringSchema;
  /**
   * Requires a maximum string length.
   * @param length - Maximum length.
   * @param message - Optional issue text.
   * @returns A refined string schema.
   * @example z.string().max(8);
   */
  max(length: number, message?: string): StringSchema;
  /**
   * Requires a UUID string.
   * @param message - Optional issue text.
   * @returns A UUID string schema.
   * @example z.string().uuid();
   */
  uuid(message?: string): StringSchema;
  /**
   * Requires a parseable datetime string.
   * @param message - Optional issue text.
   * @returns A datetime string schema.
   * @example z.string().datetime();
   */
  datetime(message?: string): StringSchema;
  /**
   * Requires an email address string.
   * @param message - Optional issue text.
   * @returns An email string schema.
   * @example z.string().email();
   */
  email(message?: string): StringSchema;
}

Source

builder.ts

z

Builds RELKIT Standard Schema validators with familiar composition helpers.

Example

import { z } from "@relkit/app/schema";

const order = z.object({ id: z.string(), quantity: z.number().int().positive() });
order.parse({ id: "order-1", quantity: 2 });

Signature

declare const z: ZBuilder;

Source

Since v0.1.0

AnySchema

Signature

declare const AnySchema: AnySchema;

Source

InputOf

Signature

declare const InputOf: InputOf<S>;

Source

NumberSchema

Signature

declare const NumberSchema: NumberSchema;

Source

ObjectInput

Signature

declare const ObjectInput: ObjectInput<S>;

Source

ObjectOutput

Signature

declare const ObjectOutput: ObjectOutput<S>;

Source

OutputOf

Signature

declare const OutputOf: OutputOf<S>;

Source

SchemaTuple

Signature

declare const SchemaTuple: SchemaTuple;

Source

Shape

Signature

declare const Shape: Shape;

Source

StringSchema

Signature

declare const StringSchema: StringSchema;

Source

ZBuilder

Signature

declare const ZBuilder: ZBuilder;

Source

builder.types.ts

AnySchema

Signature

declare const AnySchema: AnySchema;

Source

InputOf

Signature

declare const InputOf: InputOf<S>;

Source

NumberSchema

Signature

declare const NumberSchema: NumberSchema;

Source

ObjectInput

Signature

declare const ObjectInput: ObjectInput<S>;

Source

ObjectOutput

Signature

declare const ObjectOutput: ObjectOutput<S>;

Source

OutputOf

Signature

declare const OutputOf: OutputOf<S>;

Source

SchemaTuple

Signature

declare const SchemaTuple: SchemaTuple;

Source

Shape

Signature

declare const Shape: Shape;

Source

StringSchema

Signature

declare const StringSchema: StringSchema;

Source

ZBuilder (interface)

Builder methods used to compose Standard Schema validators.

Example

const builder: ZBuilder = z;

Signature

export interface ZBuilder {
  /**
   * Builds a string validator.
   * @returns A string schema with refinement methods.
   * @example z.string().min(1);
   */
  string(): StringSchema;
  /**
   * Builds a finite-number validator.
   * @returns A number schema with refinement methods.
   * @example z.number().int();
   */
  number(): NumberSchema;
  /**
   * Builds a boolean validator.
   * @returns A boolean schema.
   * @example z.boolean().parse(true);
   */
  boolean(): Schema<boolean, boolean>;
  /**
   * Builds a validator accepting any input without changing it.
   * @returns An unknown-value schema.
   * @example z.unknown().parse({ name: "Ada" });
   */
  unknown(): Schema<unknown, unknown>;
  /**
   * Builds an unrestricted value validator.
   * @returns An unknown-value schema.
   * @example z.any().parse(null);
   */
  any(): Schema<unknown, unknown>;
  /**
   * Builds a null validator.
   * @returns A null schema.
   * @example z.null().parse(null);
   */
  null(): Schema<null, null>;
  /**
   * Builds a buffered Web File validator.
   * @param options - Byte and media-type constraints.
   * @returns A File schema.
   * @example z.file({ maxBytes: 1024 });
   */
  file(options?: FileSchemaOptions): FileSchema;
  /**
   * Builds an undefined validator.
   * @returns An undefined schema.
   * @example z.undefined().parse(undefined);
   */
  undefined(): Schema<undefined, undefined>;
  /**
   * Builds a void-result validator.
   * @returns An undefined schema.
   * @example z.void().parse(undefined);
   */
  void(): Schema<undefined, undefined>;
  /**
   * Builds an exact-value validator.
   * @param value - Literal value to require.
   * @returns A literal schema.
   * @example z.literal("ready").parse("ready");
   */
  literal<T extends string | number | boolean | null | undefined>(value: T): Schema<T, T>;
  /**
   * Builds a named object validator.
   * @param shape - Child schemas by property name.
   * @returns An object schema with inferred input and output.
   * @example z.object({ id: z.string() });
   */
  object<S extends Shape>(shape: S): Schema<ObjectInput<S>, ObjectOutput<S>>;
  /**
   * Builds an array validator.
   * @param schema - Child item schema.
   * @returns An array schema with inferred item types.
   * @example z.array(z.number());
   */
  array<S extends AnySchema>(schema: S): Schema<InputOf<S>[], OutputOf<S>[]>;
  /**
   * Builds a nonempty union validator.
   * @param schemas - Member schemas in precedence order.
   * @returns A union schema with inferred member types.
   * @example z.union([z.string(), z.number()]);
   */
  union<S extends SchemaTuple>(schemas: S): Schema<InputOf<S[number]>, OutputOf<S[number]>>;
}

Source

file.ts

FileSchema

Signature

declare const FileSchema: FileSchema;

Source

FileSchemaOptions

Signature

declare const FileSchemaOptions: FileSchemaOptions;

Source

fileSchema

Builds a buffered Web File validator with binary projection metadata.

Throws

TypeError for invalid options in this synchronous adapter.

Example

fileSchema({ maxBytes: 1024, mediaTypes: ["image/*"] });

Signature

declare const fileSchema: (options?: FileSchemaOptions) => FileSchema;

Source

file.types.ts

FileSchema (type alias)

A schema that accepts and returns a Web File.

Example

const schema: FileSchema = z.file();

Signature

type FileSchema = Schema<File, File>;

Source

FileSchemaOptions (interface)

Constraints for a buffered Web File validator.

Example

const options: FileSchemaOptions = { maxBytes: 1024, mediaTypes: ["image/*"] };

Signature

export interface FileSchemaOptions {
  readonly maxBytes?: number;
  readonly mediaTypes?: readonly string[];
}

Source

index.ts

FileSchema

Signature

declare const FileSchema: FileSchema;

Source

FileSchemaOptions

Signature

declare const FileSchemaOptions: FileSchemaOptions;

Source

InferInput

Signature

declare const InferInput: InferInput<S>;

Source

InferOutput

Signature

declare const InferOutput: InferOutput<S>;

Source

JSON_SCHEMA_UNAVAILABLE

Signature

declare const JSON_SCHEMA_UNAVAILABLE: "RELKIT_SCHEMA_UNAVAILABLE";

Source

JsonSchema

Signature

declare const JsonSchema: JsonSchema;

Source

JsonSchemaAvailable

Signature

declare const JsonSchemaAvailable: JsonSchemaAvailable;

Source

JsonSchemaDirection

Signature

declare const JsonSchemaDirection: SchemaProjectionDirection;

Source

JsonSchemaFactory

Signature

declare const JsonSchemaFactory: JsonSchemaFactory;

Source

JsonSchemaOptions

Signature

declare const JsonSchemaOptions: JsonSchemaOptions;

Source

JsonSchemaResult

Signature

declare const JsonSchemaResult: JsonSchemaResult;

Source

JsonSchemaUnavailable

Signature

declare const JsonSchemaUnavailable: JsonSchemaUnavailable;

Source

JsonSchemaUnavailableError

Signature

declare const JsonSchemaUnavailableError: typeof JsonSchemaUnavailableError;

Source

NumberSchema

Signature

declare const NumberSchema: NumberSchema;

Source

RelkitSchema

Signature

declare const RelkitSchema: RelkitSchema<TInput, TOutput>;

Source

Schema

Signature

declare const Schema: Schema<TInput, TOutput>;

Source

SchemaAsyncError

Signature

declare const SchemaAsyncError: typeof SchemaAsyncError;

Source

SchemaBuilderError

Signature

declare const SchemaBuilderError: typeof SchemaBuilderError;

Source

SchemaExecutionError

Signature

declare const SchemaExecutionError: typeof SchemaExecutionError;

Source

SchemaInvalidError

Signature

declare const SchemaInvalidError: typeof SchemaInvalidError;

Source

SchemaIssuesError

Signature

declare const SchemaIssuesError: typeof SchemaIssuesError;

Source

SchemaProjector

Signature

declare const SchemaProjector: typeof SchemaProjector;

Source

SchemaProjectorLive

Signature

declare const SchemaProjectorLive: Layer<SchemaProjector, never, never>;

Source

SchemaProjectorService

Signature

declare const SchemaProjectorService: SchemaProjectorService;

Source

SchemaTelemetry

Signature

declare const SchemaTelemetry: typeof SchemaTelemetry;

Source

SchemaTelemetryLive

Signature

declare const SchemaTelemetryLive: Layer<SchemaTelemetry, never, never>;

Source

SchemaTelemetryService

Signature

declare const SchemaTelemetryService: SchemaTelemetryService;

Source

SchemaValidationError

Signature

declare const SchemaValidationError: typeof SchemaValidationError;

Source

SchemaValidator

Signature

declare const SchemaValidator: typeof SchemaValidator;

Source

SchemaValidatorLive

Signature

declare const SchemaValidatorLive: Layer<SchemaValidator, never, never>;

Source

SchemaValidatorService

Signature

declare const SchemaValidatorService: SchemaValidatorService;

Source

StandardFailure

Signature

declare const StandardFailure: StandardFailure;

Source

StandardIssue

Signature

declare const StandardIssue: StandardIssue;

Source

StandardJSONSchemaV1

Signature

declare const StandardJSONSchemaV1: StandardJSONSchemaV1<TInput, TOutput>;

Source

StandardPathSegment

Signature

declare const StandardPathSegment: StandardPathSegment;

Source

StandardResult

Signature

declare const StandardResult: StandardResult<T>;

Source

StandardSchemaOptions

Signature

declare const StandardSchemaOptions: StandardSchemaOptions;

Source

StandardSchemaTypes

Signature

declare const StandardSchemaTypes: StandardSchemaTypes<TInput, TOutput>;

Source

StandardSchemaV1

Signature

declare const StandardSchemaV1: StandardSchemaV1<TInput, TOutput>;

Source

StandardSuccess

Signature

declare const StandardSuccess: StandardSuccess<T>;

Source

StringSchema

Signature

declare const StringSchema: StringSchema;

Source

ZBuilder

Signature

declare const ZBuilder: ZBuilder;

Source

buildSchemaEffect

Signature

declare const buildSchemaEffect: <A>(
  operation: SchemaOperation,
  build: () => A,
) => Effect<A, SchemaBuilderError>;

Source

getJsonSchema

Signature

declare const getJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;

Source

getJsonSchemaEffect

Signature

declare const getJsonSchemaEffect: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => Effect<JsonSchema, JsonSchemaUnavailableError, SchemaProjector>;

Source

getSchemaMetadata

Signature

declare const getSchemaMetadata: (schema: StandardSchemaV1) => SchemaMetadata | undefined;

Source

getSchemaMetadataEffect

Signature

declare const getSchemaMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect<SchemaMetadata | undefined>;

Source

isJsonSchemaAvailable

Signature

declare const isJsonSchemaAvailable: (result: JsonSchemaResult) => result is JsonSchemaAvailable;

Source

isSchemaTransformed

Signature

declare const isSchemaTransformed: (schema: StandardSchemaV1) => boolean;

Source

isSchemaTransformedEffect

Signature

declare const isSchemaTransformedEffect: (schema: StandardSchemaV1) => Effect<boolean>;

Source

toJsonSchema

Signature

declare const toJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;

Source

validate

Signature

declare const validate: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>> | Promise<StandardResult<InferOutput<S>>>;

Source

validateEffect

Signature

declare const validateEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError,
  SchemaValidator
>;

Source

validateSync

Signature

declare const validateSync: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => StandardResult<InferOutput<S>>;

Source

validateSyncEffect

Signature

declare const validateSyncEffect: <S extends StandardSchemaV1>(
  schema: S,
  value: InferInput<S>,
) => Effect<
  InferOutput<S>,
  SchemaIssuesError | SchemaInvalidError | SchemaExecutionError | SchemaAsyncError,
  SchemaValidator
>;

Source

z

Signature

declare const z: ZBuilder;

Source

json-schema-effect.ts

JsonSchemaUnavailableError (class)

Tagged failure for an unavailable or invalid JSON Schema projection.

Example

Effect.catchTag("JsonSchemaUnavailableError", (error) => Effect.succeed(error.reason));

Signature

declare class JsonSchemaUnavailableError

Source

SchemaProjector (class)

Injectable JSON Schema projection boundary.

Example

Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive);

Signature

declare class SchemaProjector

Source

SchemaProjectorLive

Live JSON Schema projector using registered schema metadata and hooks.

Example

Effect.runSync(Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive));

Signature

declare const SchemaProjectorLive: Layer.Layer<SchemaProjector, never, never>;

Source

getJsonSchemaEffect

Projects a validator into canonical JSON Schema with typed failures.

Example

Effect.runSync(Effect.provide(getJsonSchemaEffect(z.string()), SchemaProjectorLive));

Signature

declare const getJsonSchemaEffect: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => Effect.Effect<JsonSchema, JsonSchemaUnavailableError, SchemaProjector>;

Source

json-schema-effect.types.ts

SchemaProjectorService (interface)

Injectable boundary for a schema’s JSON projection hook. Test Layers can substitute projection without a third-party schema package.

Example

Layer.succeed(SchemaProjector, { projection: () => () => ({ type: "string" }) });

Signature

export interface SchemaProjectorService {
  /**
   * Selects a directional or legacy projection hook.
   * @param schema - Compatible schema to inspect.
   * @param direction - Input, output, or legacy projection.
   * @returns A projection factory when the schema exposes one.
   * @example projector.projection(z.string(), "input");
   */
  readonly projection: (
    schema: StandardSchemaV1,
    direction: JsonSchemaDirection | "legacy",
  ) => JsonSchemaFactory | undefined;
}

Source

json-schema-inspection.ts

getSchemaProjection

Finds a deterministic projection hook without executing it.

Example

getSchemaProjection(z.string(), "input");

Signature

declare const getSchemaProjection: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => JsonSchemaFactory | undefined;

Source

getSchemaProjectionEffect

Finds a deterministic projection hook inside Effect.

Example

Effect.runSync(getSchemaProjectionEffect(z.string(), "input"));

Signature

declare const getSchemaProjectionEffect: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => Effect.Effect<JsonSchemaFactory | undefined>;

Source

isSchemaOptional

Checks whether a schema accepts an omitted property.

Example

isSchemaOptional(z.string().optional());

Signature

declare const isSchemaOptional: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => boolean;

Source

isSchemaOptionalEffect

Checks schema optionality inside Effect.

Example

Effect.runSync(isSchemaOptionalEffect(z.string().optional()));

Signature

declare const isSchemaOptionalEffect: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => Effect.Effect<boolean>;

Source

json-schema-inspection.types.ts

RelkitProjectable (type alias)

RELKIT extension hook shapes for directional JSON projections.

Example

const projection = (schema as RelkitProjectable).relkit?.inputJsonSchema;

Signature

type RelkitProjectable = StandardSchemaV1 & {
  readonly relkit?: {
    readonly jsonSchema?: JsonSchemaFactory;
    readonly inputJsonSchema?: JsonSchemaFactory;
    readonly outputJsonSchema?: JsonSchemaFactory;
  };
};

Source

StandardProjectable (type alias)

Standard JSON Schema extension hook shapes for compatible schemas.

Example

const hook = (schema["~standard"] as StandardProjectable).jsonSchema?.input;

Signature

type StandardProjectable = StandardSchemaV1["~standard"] & {
  readonly jsonSchema?: {
    readonly input?: (options: { readonly target: "draft-2020-12" }) => Record<string, unknown>;
    readonly output?: (options: { readonly target: "draft-2020-12" }) => Record<string, unknown>;
  };
};

Source

json-schema.ts

JSON_SCHEMA_UNAVAILABLE

Stable code for unavailable deterministic JSON Schema projections.

Signature

declare const JSON_SCHEMA_UNAVAILABLE: "RELKIT_SCHEMA_UNAVAILABLE";

Source

JsonSchema

Signature

declare const JsonSchema: JsonSchema;

Source

JsonSchemaAvailable

Signature

declare const JsonSchemaAvailable: JsonSchemaAvailable;

Source

JsonSchemaDirection

Signature

declare const JsonSchemaDirection: SchemaProjectionDirection;

Source

JsonSchemaFactory

Signature

declare const JsonSchemaFactory: JsonSchemaFactory;

Source

JsonSchemaOptions

Signature

declare const JsonSchemaOptions: JsonSchemaOptions;

Source

JsonSchemaResult

Signature

declare const JsonSchemaResult: JsonSchemaResult;

Source

JsonSchemaUnavailable

Signature

declare const JsonSchemaUnavailable: JsonSchemaUnavailable;

Source

JsonSchemaValueError (class)

Tagged failure for non-JSON projection data. The original validation exception remains in cause.

Example

Effect.catchTag("JsonSchemaValueError", (error) => Effect.succeed(error.cause));

Signature

declare class JsonSchemaValueError

Source

getJsonSchema

Produces a canonical JSON Schema or an unavailable result.

Example

getJsonSchema(z.string());

Signature

declare const getJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;

Source

getSchemaProjection

Signature

declare const getSchemaProjection: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => JsonSchemaFactory | undefined;

Source

isJsonSchemaAvailable

Narrows a successful projection result.

Example

isJsonSchemaAvailable(getJsonSchema(z.string()));

Signature

declare const isJsonSchemaAvailable: (result: JsonSchemaResult) => result is JsonSchemaAvailable;

Source

isJsonSchemaAvailableEffect

Checks projection availability inside Effect.

Example

Effect.runSync(isJsonSchemaAvailableEffect(getJsonSchema(z.string())));

Signature

declare const isJsonSchemaAvailableEffect: (result: JsonSchemaResult) => Effect.Effect<boolean>;

Source

isSchemaOptional

Signature

declare const isSchemaOptional: (
  schema: StandardSchemaV1,
  direction?: JsonSchemaDirection | "legacy",
) => boolean;

Source

sortJsonValue

Canonicalizes JSON-safe projection data and preserves TypeError behavior.

Throws

TypeError for unsupported data.

Example

sortJsonValue({ b: 2, a: 1 }, "$", undefined);

Signature

declare const sortJsonValue: (value: unknown, path: string, key: string | undefined) => JsonValue;

Source

sortJsonValueEffect

Canonicalizes JSON-safe projection data inside Effect.

Example

Effect.runSync(sortJsonValueEffect({ b: 2, a: 1 }, "$", undefined));

Signature

declare const sortJsonValueEffect: (
  value: unknown,
  path: string,
  key: string | undefined,
) => Effect.Effect<JsonValue, JsonSchemaValueError>;

Source

toJsonSchema

Alias for callers that describe projection as a conversion.

Example

toJsonSchema(z.string());

Signature

declare const toJsonSchema: (
  schema: StandardSchemaV1,
  options?: JsonSchemaOptions,
) => JsonSchemaResult;

Source

json-schema.types.ts

JsonSchema (type alias)

A deterministic JSON Schema document.

Example

const document: JsonSchema = { type: "string" };

Signature

type JsonSchema = { readonly [key: string]: JsonValue };

Source

JsonSchemaAvailable (interface)

A successful JSON Schema projection.

Example

const available: JsonSchemaAvailable = { ok: true, schema: { type: "string" } };

Signature

export interface JsonSchemaAvailable {
  readonly ok: true;
  readonly schema: JsonSchema;
}

Source

JsonSchemaDirection (type alias)

Projection direction accepted by getJsonSchema.

Example

const direction: JsonSchemaDirection = "input";

Signature

type JsonSchemaDirection = SchemaProjectionDirection;

Source

JsonSchemaFactory (type alias)

Factory for a JSON-safe schema value.

Example

const projection: JsonSchemaFactory = () => ({ type: "string" });

Signature

type JsonSchemaFactory = () => JsonValue;

Source

JsonSchemaOptions (interface)

Options for a JSON Schema projection.

Example

const options: JsonSchemaOptions = { direction: "output" };

Signature

export interface JsonSchemaOptions {
  readonly direction?: JsonSchemaDirection;
}

Source

JsonSchemaResult (type alias)

The result of a JSON Schema projection.

Example

const result: JsonSchemaResult = getJsonSchema(z.string());

Signature

type JsonSchemaResult = JsonSchemaAvailable | JsonSchemaUnavailable;

Source

JsonSchemaUnavailable (interface)

An unavailable projection with a stable code and reason.

Example

const unavailable: JsonSchemaUnavailable = {
  ok: false,
  code: JSON_SCHEMA_UNAVAILABLE,
  reason: "missing",
};

Signature

export interface JsonSchemaUnavailable {
  readonly ok: false;
  readonly code: typeof JSON_SCHEMA_UNAVAILABLE;
  readonly reason: string;
}

Source

schema-collection.ts

collectResults

Collects object or array validation results and preserves issue order.

Throws

The first rejected child validator in input order.

Example

collectResults([() => ({ value: 1 })], ([value]) => value);

Signature

declare const collectResults: <T, U>(
  tasks: readonly SchemaTask<T>[],
  map: (values: T[]) => U,
) => StandardResult<U> | Promise<StandardResult<U>>;

Source

collectUnion

Selects the first successful union member in declaration order.

Throws

The first rejected validator in input order.

Example

collectUnion([() => ({ value: "ok" })], []);

Signature

declare const collectUnion: <T>(
  tasks: readonly SchemaTask<T>[],
  path: readonly StandardPathSegment[],
) => StandardResult<T> | Promise<StandardResult<T>>;

Source

resolveTasksEffect

Resolves child validators in input order with bounded async concurrency.

Example

Effect.runPromise(resolveTasksEffect([() => Promise.resolve({ value: 1 })]));

Signature

declare const resolveTasksEffect: <T>(
  tasks: readonly SchemaTask<T>[],
) => Effect.Effect<readonly StandardResult<T>[], SchemaExecutionError>;

Source

schema-collection.types.ts

SchemaTask (type alias)

Deferred child validation used by object, array, and union schemas.

Example

const task: SchemaTask<number> = () => ({ value: 1 });

Signature

type SchemaTask<T> = () => StandardResult<T> | Promise<StandardResult<T>>;

Source

schema-execution.ts

throwCause

Rethrows the original cause of an Effect execution failure.

Throws

The original cause.

Example

throwCause(new SchemaExecutionError({ cause: new TypeError("bad") }));

Signature

declare const throwCause: (error: unknown) => never;

Source

schema-impl-helpers.ts

SchemaProjectionError (class)

Tagged failure for an unsupported target or missing projection. The original exception remains available in cause.

Example

Effect.catchTag("SchemaProjectionError", (error) => Effect.succeed(error.cause));

Signature

declare class SchemaProjectionError

Source

addPath

Prefixes nested issues without changing sync/async shape.

Example

addPath({ issues: [{ message: "bad" }] }, ["item"]);

Signature

declare const addPath: <T>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  path: readonly StandardPathSegment[],
) => StandardResult<T> | Promise<StandardResult<T>>;

Source

addPathEffect

Prefixes issues from a nested third-party validator in Effect.

Example

Effect.runSync(addPathEffect({ issues: [{ message: "bad" }] }, ["item"]));

Signature

declare const addPathEffect: <T>(
  result: StandardResult<T> | Promise<StandardResult<T>>,
  path: readonly StandardPathSegment[],
) => Effect.Effect<StandardResult<T> | Promise<StandardResult<T>>>;

Source

projectJsonSchema

Projects metadata through a Standard JSON Schema hook.

Throws

TypeError for an unsupported target or absent projection.

Example

projectJsonSchema({ jsonSchema: () => ({}) }, "input", "draft-07");

Signature

declare const projectJsonSchema: (
  metadata: SchemaMetadata,
  direction: "input" | "output",
  target: StandardJSONSchemaV1.Options["target"],
) => Record<string, unknown>;

Source

projectJsonSchemaEffect

Projects metadata through a Standard JSON Schema hook inside Effect.

Example

Effect.runSync(projectJsonSchemaEffect({ jsonSchema: () => ({}) }, "input", "draft-07"));

Signature

declare const projectJsonSchemaEffect: (
  metadata: SchemaMetadata,
  direction: "input" | "output",
  target: StandardJSONSchemaV1.Options["target"],
) => Effect.Effect<Record<string, unknown>, SchemaProjectionError>;

Source

schema-impl.ts

SchemaValidationError

Signature

declare const SchemaValidationError: typeof SchemaValidationError;

Source

createSchema

Synchronous compatibility adapter for schema construction.

Throws

The original construction error if creation fails.

Example

createSchema((value) => ({ value }));

Signature

declare const createSchema: <TInput, TOutput>(
  check: SchemaCheck<TOutput>,
  metadata?: SchemaMetadata,
) => Schema<TInput, TOutput>;

Source

createSchemaEffect

Constructs a schema within an observed Effect.

Example

Effect.runSync(createSchemaEffect((value) => ({ value })));

Signature

declare const createSchemaEffect: <TInput, TOutput>(
  check: SchemaCheck<TOutput>,
  metadata?: SchemaMetadata,
) => Effect.Effect<Schema<TInput, TOutput>, SchemaExecutionError>;

Source

runSchema

Compatibility adapter for path-aware schema validation.

Throws

The original validator error if evaluation fails.

Example

runSchema(z.string(), "ok", ["name"]);

Signature

declare const runSchema: <TOutput>(
  schema: StandardSchemaV1<unknown, TOutput>,
  value: unknown,
  path?: readonly StandardPathSegment[],
) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;

Source

runSchemaEffect

Evaluates a schema while preserving its synchronous or asynchronous result.

Example

Effect.runSync(runSchemaEffect(z.string(), "ok"));

Signature

declare const runSchemaEffect: <TOutput>(
  schema: StandardSchemaV1<unknown, TOutput>,
  value: unknown,
  path?: readonly StandardPathSegment[],
) => Effect.Effect<
  StandardResult<TOutput> | Promise<StandardResult<TOutput>>,
  SchemaExecutionError
>;

Source

schema-impl.types.ts

InternalSchema (interface)

RELKIT schema with its internal path-aware validation hook. The hook is only used while composing nested schemas.

Example

const internal = schema as InternalSchema<string, string>;

Signature

export interface InternalSchema<TInput, TOutput> extends Schema<TInput, TOutput> {
  readonly _run: SchemaCheck<TOutput>;
}

Source

SchemaCheck (type alias)

Path-aware validation callback used by a constructed RELKIT schema.

Example

const check: SchemaCheck<string> = (value) => ({ value: String(value) });

Signature

type SchemaCheck<T> = (
  value: unknown,
  path: readonly StandardPathSegment[],
) => StandardResult<T> | Promise<StandardResult<T>>;

Source

schema-implementation.ts

SchemaImplementation (class)

Internal path-aware schema with Standard Schema and JSON Schema hooks.

Example

new SchemaImplementation((value) => ({ value }), {});

Signature

declare class SchemaImplementation<TInput, TOutput> {
  constructor(check: SchemaCheck<TOutput>, metadata: SchemaMetadata);
}

Source

optional (method)

Accepts an omitted or undefined value.

Example

z.string().optional();

Signature

declare const optional: () => Schema<TInput | undefined, TOutput | undefined>;

Source

nullable (method)

Accepts null without changing other validation.

Example

z.string().nullable();

Signature

declare const nullable: () => Schema<TInput | null, TOutput | null>;

Source

default (method)

Substitutes a value when input is undefined.

Example

z.string().default("pending");

Signature

declare const default: (value: TInput | (() => TInput)) => Schema<TInput | undefined, TOutput>

Source

transform (method)

Maps a validated value to a new output.

Example

z.string().transform(Number);

Signature

declare const transform: <TNext>(
  transform: (value: TOutput) => TNext | Promise<TNext>,
) => Schema<TInput, TNext>;

Source

refine (method)

Adds a check after base validation succeeds.

Example

z.number().refine((value) => value > 0);

Signature

declare const refine: (
  check: (value: TOutput) => boolean | Promise<boolean>,
  message?: string,
) => Schema<TInput, TOutput>;

Source

parse (method)

Parses one input synchronously.

Throws

SchemaValidationError or TypeError for invalid or asynchronous input.

Example

z.string().parse("ready");

Signature

declare const parse: (value: unknown) => TOutput;

Source

parseAsync (method)

Parses one input and awaits asynchronous checks.

Throws

SchemaValidationError when validation fails.

Example

await z.string().parseAsync("ready");

Signature

declare const parseAsync: (value: unknown) => Promise<TOutput>;

Source

safeParse (method)

Returns issues instead of throwing for invalid input.

Example

z.string().safeParse("ready");

Signature

declare const safeParse: (
  value: unknown,
) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>;

Source

_run (property)

Signature

readonly _run: SchemaCheck<TOutput>

Source

“~standard” (property)

Signature

readonly "~standard": { readonly version: 1; readonly vendor: string; readonly validate: (value: unknown, options?: StandardSchemaOptions) => StandardResult<TOutput> | Promise<StandardResult<TOutput>>; readonly types?: StandardSchemaTypes<TInput, TOutput>; } & StandardJSONSchemaV1.Props<TInput, TOutput>

Source

relkit (property)

Signature

readonly relkit: SchemaProjectionHooks

Source

schema-implementation.types.ts

Schema (interface)

RELKIT schema with parsing and composition methods. Input and output types may differ after transformation.

Example

const schema: Schema<string, number> = z.string().transform(Number);

Signature

export interface Schema<TInput = unknown, TOutput = TInput> extends RelkitSchema<TInput, TOutput> {
  /**
   * Accepts undefined as input and output.
   * @returns A schema with optional value types.
   * @example z.string().optional();
   */
  optional(): Schema<TInput | undefined, TOutput | undefined>;
  /**
   * Accepts null as input and output.
   * @returns A nullable schema.
   * @example z.string().nullable();
   */
  nullable(): Schema<TInput | null, TOutput | null>;
  /**
   * Supplies a value for undefined input.
   * @param value - Constant or lazy default.
   * @returns A schema with optional input and required output.
   * @example z.string().default("ready");
   */
  default(value: TInput | (() => TInput)): Schema<TInput | undefined, TOutput>;
  /**
   * Maps a valid output to a new value.
   * @param transform - Synchronous or asynchronous mapper.
   * @returns A schema with the mapped output type.
   * @example z.string().transform(Number);
   */
  transform<TNext>(transform: (value: TOutput) => TNext | Promise<TNext>): Schema<TInput, TNext>;
  /**
   * Checks a valid output with a predicate.
   * @param check - Predicate for valid output.
   * @param message - Failure message.
   * @returns A refined schema.
   * @example z.number().refine((value) => value > 0);
   */
  refine(
    check: (value: TOutput) => boolean | Promise<boolean>,
    message?: string,
  ): Schema<TInput, TOutput>;
  /**
   * Parses synchronously or throws.
   * @param value - Input to parse.
   * @returns Validated output.
   * @throws SchemaValidationError or TypeError for invalid or asynchronous input.
   * @example z.string().parse("ready");
   */
  parse(value: unknown): TOutput;
  /**
   * Parses and awaits asynchronous checks.
   * @param value - Input to parse.
   * @returns A promise of validated output.
   * @throws SchemaValidationError for invalid input.
   * @example await z.string().parseAsync("ready");
   */
  parseAsync(value: unknown): Promise<TOutput>;
  /**
   * Returns a result for sync or async validation.
   * @param value - Input to validate.
   * @returns A result or promise with value or issues.
   * @example z.string().safeParse("ready");
   */
  safeParse(value: unknown): StandardResult<TOutput> | Promise<StandardResult<TOutput>>;
}

Source

SchemaProjectionHooks (interface)

Directional JSON Schema projection hooks carried by a RELKIT schema.

Example

const hooks: SchemaProjectionHooks = { jsonSchema: () => ({ type: "string" }) };

Signature

export interface SchemaProjectionHooks {
  readonly jsonSchema?: () => JsonValue;
  readonly inputJsonSchema?: () => JsonValue;
  readonly outputJsonSchema?: () => JsonValue;
}

Source

schema-metadata-composition.ts

withDefaultMetadata

Adds a static default only to output and legacy projections.

Example

withDefaultMetadata(z.string(), "ready");

Signature

declare const withDefaultMetadata: <T>(
  schema: StandardSchemaV1,
  value: T | (() => T),
) => SchemaMetadata;

Source

withDefaultMetadataEffect

Builds default metadata in Effect without evaluating lazy values.

Example

Effect.runSync(withDefaultMetadataEffect(z.string(), "ready"));

Signature

declare const withDefaultMetadataEffect: <T>(
  schema: StandardSchemaV1,
  value: T | (() => T),
) => Effect.Effect<SchemaMetadata>;

Source

withNullableMetadata

Wraps each available projection in a nullable union.

Example

withNullableMetadata(z.string());

Signature

declare const withNullableMetadata: (schema: StandardSchemaV1) => SchemaMetadata;

Source

withNullableMetadataEffect

Builds nullable metadata in Effect.

Example

Effect.runSync(withNullableMetadataEffect(z.string()));

Signature

declare const withNullableMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;

Source

withOptionalMetadata

Marks a schema optional in both projection directions.

Example

withOptionalMetadata(z.string());

Signature

declare const withOptionalMetadata: (schema: StandardSchemaV1) => SchemaMetadata;

Source

withOptionalMetadataEffect

Builds optional metadata in Effect.

Example

Effect.runSync(withOptionalMetadataEffect(z.string()));

Signature

declare const withOptionalMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;

Source

withRefinementMetadata

Preserves projection metadata while marking a schema refined.

Example

withRefinementMetadata(z.string());

Signature

declare const withRefinementMetadata: (schema: StandardSchemaV1) => SchemaMetadata;

Source

withRefinementMetadataEffect

Builds refinement metadata in Effect.

Example

Effect.runSync(withRefinementMetadataEffect(z.string()));

Signature

declare const withRefinementMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;

Source

withTransformMetadata

Keeps only input projection metadata after a transform.

Example

withTransformMetadata(z.string());

Signature

declare const withTransformMetadata: (schema: StandardSchemaV1) => SchemaMetadata;

Source

withTransformMetadataEffect

Builds transform metadata in Effect.

Example

Effect.runSync(withTransformMetadataEffect(z.string()));

Signature

declare const withTransformMetadataEffect: (
  schema: StandardSchemaV1,
) => Effect.Effect<SchemaMetadata>;

Source

schema-metadata.ts

SchemaMetadata

Signature

declare const SchemaMetadata: SchemaMetadata;

Source

SchemaMetadataError (class)

Tagged failure when schema metadata cannot be attached. The original exception remains available in cause.

Example

Effect.catchTag("SchemaMetadataError", (error) => Effect.succeed(error.cause));

Signature

declare class SchemaMetadataError

Source

SchemaProjection

Signature

declare const SchemaProjection: SchemaProjection;

Source

SchemaProjectionDirection

Signature

declare const SchemaProjectionDirection: SchemaProjectionDirection;

Source

getMetadataProjection

Selects the projection hook for a direction.

Example

getMetadataProjection({}, "output");

Signature

declare const getMetadataProjection: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => SchemaProjection | undefined;

Source

getMetadataProjectionEffect

Selects the requested projection hook inside Effect.

Example

Effect.runSync(getMetadataProjectionEffect({}, "input"));

Signature

declare const getMetadataProjectionEffect: (
  metadata: SchemaMetadata | undefined,
  direction?: SchemaProjectionDirection | "legacy",
) => Effect.Effect<SchemaMetadata["jsonSchema"]>;

Source

getSchemaMetadata

Reads metadata attached to a schema.

Example

getSchemaMetadata(z.string());

Signature

declare const getSchemaMetadata: (schema: StandardSchemaV1) => SchemaMetadata | undefined;