@sinclair/typebox 0.32.0-dev-16 → 0.32.0-dev-18

package/build/import/value/transform/decode.d.mts

@@ -11,4 +11,9 @@ export declare class TransformDecodeError extends Error {
     readonly value: unknown;
     constructor(schema: TSchema, value: unknown, error: any);
 }
+/**
+ * `[Internal]` Decodes the value and returns the result. This function requires that
+ * the caller `Check` the value before use. Passing unchecked values may result in
+ * undefined behavior. Refer to the `Value.Decode()` for implementation details.
+ */
 export declare function TransformDecode(schema: TSchema, references: TSchema[], value: unknown): unknown;

package/build/import/value/transform/decode.mjs

@@ -5,6 +5,10 @@ import { KeyOfPropertyKeys } from '../../type/keyof/index.mjs';
 import { Index } from '../../type/indexed/index.mjs';
 import { Deref } from '../deref/index.mjs';
 import { Check } from '../check/index.mjs';
+// ------------------------------------------------------------------
+// Errors
+// ------------------------------------------------------------------
+// thrown externally
 export class TransformDecodeCheckError extends Error {
     schema;
     value;
@@ -25,6 +29,10 @@ export class TransformDecodeError extends Error {
         this.value = value;
     }
 }
+// ------------------------------------------------------------------
+// Decode
+// ------------------------------------------------------------------
+// prettier-ignore
 function Default(schema, value) {
     try {
         return IsTransformType(schema) ? schema[TransformKind].Decode(value) : value;
@@ -33,11 +41,13 @@ function Default(schema, value) {
         throw new TransformDecodeError(schema, value, error);
     }
 }
+// prettier-ignore
 function TArray(schema, references, value) {
     return (IsArray(value))
         ? Default(schema, value.map((value) => Visit(schema.items, references, value)))
         : Default(schema, value);
 }
+// prettier-ignore
 function TIntersect(schema, references, value) {
     if (!IsPlainObject(value) || IsValueType(value))
         return Default(schema, value);
@@ -62,6 +72,7 @@ function TIntersect(schema, references, value) {
 function TNot(schema, references, value) {
     return Default(schema, Visit(schema.not, references, value));
 }
+// prettier-ignore
 function TObject(schema, references, value) {
     if (!IsPlainObject(value))
         return Default(schema, value);
@@ -83,6 +94,7 @@ function TObject(schema, references, value) {
     }, knownProperties);
     return Default(schema, unknownProperties);
 }
+// prettier-ignore
 function TRecord(schema, references, value) {
     if (!IsPlainObject(value))
         return Default(schema, value);
@@ -105,28 +117,34 @@ function TRecord(schema, references, value) {
     }, knownProperties);
     return Default(schema, unknownProperties);
 }
+// prettier-ignore
 function TRef(schema, references, value) {
     const target = Deref(schema, references);
     return Default(schema, Visit(target, references, value));
 }
+// prettier-ignore
 function TThis(schema, references, value) {
     const target = Deref(schema, references);
     return Default(schema, Visit(target, references, value));
 }
+// prettier-ignore
 function TTuple(schema, references, value) {
     return (IsArray(value) && IsArray(schema.items))
         ? Default(schema, schema.items.map((schema, index) => Visit(schema, references, value[index])))
         : Default(schema, value);
 }
+// prettier-ignore
 function TUnion(schema, references, value) {
     for (const subschema of schema.anyOf) {
         if (!Check(subschema, references, value))
             continue;
+        // note: ensure interior is decoded first
         const decoded = Visit(subschema, references, value);
         return Default(schema, decoded);
     }
     return Default(schema, value);
 }
+// prettier-ignore
 function Visit(schema, references, value) {
     const references_ = typeof schema.$id === 'string' ? [...references, schema] : references;
     const schema_ = schema;
@@ -155,6 +173,11 @@ function Visit(schema, references, value) {
             return Default(schema_, value);
     }
 }
+/**
+ * `[Internal]` Decodes the value and returns the result. This function requires that
+ * the caller `Check` the value before use. Passing unchecked values may result in
+ * undefined behavior. Refer to the `Value.Decode()` for implementation details.
+ */
 export function TransformDecode(schema, references, value) {
     return Visit(schema, references, value);
 }

package/build/import/value/transform/encode.d.mts

@@ -11,4 +11,10 @@ export declare class TransformEncodeError extends Error {
     readonly value: unknown;
     constructor(schema: TSchema, value: unknown, error: any);
 }
+/**
+ * `[Internal]` Encodes the value and returns the result. This function expects the
+ * caller to pass a statically checked value. This function does not check the encoded
+ * result, meaning the result should be passed to `Check` before use. Refer to the
+ * `Value.Encode()` function for implementation details.
+ */
 export declare function TransformEncode(schema: TSchema, references: TSchema[], value: unknown): unknown;

package/build/import/value/transform/encode.mjs

@@ -5,6 +5,9 @@ import { KeyOfPropertyKeys } from '../../type/keyof/index.mjs';
 import { Index } from '../../type/indexed/index.mjs';
 import { Deref } from '../deref/index.mjs';
 import { Check } from '../check/index.mjs';
+// ------------------------------------------------------------------
+// Errors
+// ------------------------------------------------------------------
 export class TransformEncodeCheckError extends Error {
     schema;
     value;
@@ -25,6 +28,10 @@ export class TransformEncodeError extends Error {
         this.value = value;
     }
 }
+// ------------------------------------------------------------------
+// Encode
+// ------------------------------------------------------------------
+// prettier-ignore
 function Default(schema, value) {
     try {
         return IsTransformType(schema) ? schema[TransformKind].Encode(value) : value;
@@ -33,12 +40,14 @@ function Default(schema, value) {
         throw new TransformEncodeError(schema, value, error);
     }
 }
+// prettier-ignore
 function TArray(schema, references, value) {
     const defaulted = Default(schema, value);
     return IsArray(defaulted)
         ? defaulted.map((value) => Visit(schema.items, references, value))
         : defaulted;
 }
+// prettier-ignore
 function TIntersect(schema, references, value) {
     const defaulted = Default(schema, value);
     if (!IsPlainObject(value) || IsValueType(value))
@@ -60,9 +69,11 @@ function TIntersect(schema, references, value) {
             : value;
     }, knownProperties);
 }
+// prettier-ignore
 function TNot(schema, references, value) {
     return Default(schema.not, Default(schema, value));
 }
+// prettier-ignore
 function TObject(schema, references, value) {
     const defaulted = Default(schema, value);
     if (!IsPlainObject(value))
@@ -84,6 +95,7 @@ function TObject(schema, references, value) {
             : value;
     }, knownProperties);
 }
+// prettier-ignore
 function TRecord(schema, references, value) {
     const defaulted = Default(schema, value);
     if (!IsPlainObject(value))
@@ -106,27 +118,33 @@ function TRecord(schema, references, value) {
             : value;
     }, knownProperties);
 }
+// prettier-ignore
 function TRef(schema, references, value) {
     const target = Deref(schema, references);
     const resolved = Visit(target, references, value);
     return Default(schema, resolved);
 }
+// prettier-ignore
 function TThis(schema, references, value) {
     const target = Deref(schema, references);
     const resolved = Visit(target, references, value);
     return Default(schema, resolved);
 }
+// prettier-ignore
 function TTuple(schema, references, value) {
     const value1 = Default(schema, value);
     return IsArray(schema.items) ? schema.items.map((schema, index) => Visit(schema, references, value1[index])) : [];
 }
+// prettier-ignore
 function TUnion(schema, references, value) {
+    // test value against union variants
     for (const subschema of schema.anyOf) {
         if (!Check(subschema, references, value))
             continue;
         const value1 = Visit(subschema, references, value);
         return Default(schema, value1);
     }
+    // test transformed value against union variants
     for (const subschema of schema.anyOf) {
         const value1 = Visit(subschema, references, value);
         if (!Check(schema, references, value1))
@@ -135,6 +153,7 @@ function TUnion(schema, references, value) {
     }
     return Default(schema, value);
 }
+// prettier-ignore
 function Visit(schema, references, value) {
     const references_ = typeof schema.$id === 'string' ? [...references, schema] : references;
     const schema_ = schema;
@@ -161,6 +180,12 @@ function Visit(schema, references, value) {
             return Default(schema_, value);
     }
 }
+/**
+ * `[Internal]` Encodes the value and returns the result. This function expects the
+ * caller to pass a statically checked value. This function does not check the encoded
+ * result, meaning the result should be passed to `Check` before use. Refer to the
+ * `Value.Encode()` function for implementation details.
+ */
 export function TransformEncode(schema, references, value) {
     return Visit(schema, references, value);
 }

package/build/import/value/transform/has.d.mts

@@ -1,2 +1,3 @@
 import type { TSchema } from '../../type/schema/index.mjs';
+/** Returns true if this schema contains a transform codec */
 export declare function HasTransform(schema: TSchema, references: TSchema[]): boolean;

package/build/import/value/transform/has.mjs

@@ -2,56 +2,71 @@ import { TTransform as IsTransformType, TSchema as IsSchemaType } from '../../ty
 import { IsString, IsUndefined } from '../guard/index.mjs';
 import { Deref } from '../deref/index.mjs';
 import { Kind } from '../../type/symbols/index.mjs';
+// prettier-ignore
 function TArray(schema, references) {
     return IsTransformType(schema) || Visit(schema.items, references);
 }
+// prettier-ignore
 function TAsyncIterator(schema, references) {
     return IsTransformType(schema) || Visit(schema.items, references);
 }
+// prettier-ignore
 function TConstructor(schema, references) {
     return IsTransformType(schema) || Visit(schema.returns, references) || schema.parameters.some((schema) => Visit(schema, references));
 }
+// prettier-ignore
 function TFunction(schema, references) {
     return IsTransformType(schema) || Visit(schema.returns, references) || schema.parameters.some((schema) => Visit(schema, references));
 }
+// prettier-ignore
 function TIntersect(schema, references) {
     return IsTransformType(schema) || IsTransformType(schema.unevaluatedProperties) || schema.allOf.some((schema) => Visit(schema, references));
 }
+// prettier-ignore
 function TIterator(schema, references) {
     return IsTransformType(schema) || Visit(schema.items, references);
 }
+// prettier-ignore
 function TNot(schema, references) {
     return IsTransformType(schema) || Visit(schema.not, references);
 }
+// prettier-ignore
 function TObject(schema, references) {
     return (IsTransformType(schema) ||
         Object.values(schema.properties).some((schema) => Visit(schema, references)) ||
         (IsSchemaType(schema.additionalProperties) && Visit(schema.additionalProperties, references)));
 }
+// prettier-ignore
 function TPromise(schema, references) {
     return IsTransformType(schema) || Visit(schema.item, references);
 }
+// prettier-ignore
 function TRecord(schema, references) {
     const pattern = Object.getOwnPropertyNames(schema.patternProperties)[0];
     const property = schema.patternProperties[pattern];
     return IsTransformType(schema) || Visit(property, references) || (IsSchemaType(schema.additionalProperties) && IsTransformType(schema.additionalProperties));
 }
+// prettier-ignore
 function TRef(schema, references) {
     if (IsTransformType(schema))
         return true;
     return Visit(Deref(schema, references), references);
 }
+// prettier-ignore
 function TThis(schema, references) {
     if (IsTransformType(schema))
         return true;
     return Visit(Deref(schema, references), references);
 }
+// prettier-ignore
 function TTuple(schema, references) {
     return IsTransformType(schema) || (!IsUndefined(schema.items) && schema.items.some((schema) => Visit(schema, references)));
 }
+// prettier-ignore
 function TUnion(schema, references) {
     return IsTransformType(schema) || schema.anyOf.some((schema) => Visit(schema, references));
 }
+// prettier-ignore
 function Visit(schema, references) {
     const references_ = IsString(schema.$id) ? [...references, schema] : references;
     const schema_ = schema;
@@ -93,6 +108,7 @@ function Visit(schema, references) {
     }
 }
 const visited = new Set();
+/** Returns true if this schema contains a transform codec */
 export function HasTransform(schema, references) {
     visited.clear();
     return Visit(schema, references);

package/build/import/value/value/value.d.mts

@@ -3,27 +3,51 @@ import { Edit } from '../delta/index.mjs';
 import { ValueErrorIterator } from '../../errors/index.mjs';
 import type { TSchema } from '../../type/schema/index.mjs';
 import type { Static, StaticDecode, StaticEncode } from '../../type/static/index.mjs';
+/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
 export declare function Cast<T extends TSchema>(schema: T, references: TSchema[], value: unknown): Static<T>;
+/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
 export declare function Cast<T extends TSchema>(schema: T, value: unknown): Static<T>;
+/** Creates a value from the given type and references */
 export declare function Create<T extends TSchema>(schema: T, references: TSchema[]): Static<T>;
+/** Creates a value from the given type */
 export declare function Create<T extends TSchema>(schema: T): Static<T>;
+/** Returns true if the value matches the given type and references */
 export declare function Check<T extends TSchema>(schema: T, references: TSchema[], value: unknown): value is Static<T>;
+/** Returns true if the value matches the given type */
 export declare function Check<T extends TSchema>(schema: T, value: unknown): value is Static<T>;
+/** `[Mutable]` Removes excess properties from a value and returns the result. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first. */
 export declare function Clean<T extends TSchema>(schema: T, references: TSchema[], value: unknown): unknown;
+/** `[Mutable]` Removes excess properties from a value and returns the result. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first. */
 export declare function Clean<T extends TSchema>(schema: T, value: unknown): unknown;
+/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
 export declare function Convert<T extends TSchema>(schema: T, references: TSchema[], value: unknown): unknown;
+/** Converts any type mismatched values to their target type if a reasonable conversion is possibl. */
 export declare function Convert<T extends TSchema>(schema: T, value: unknown): unknown;
+/** Returns a structural clone of the given value */
 export declare function Clone<T>(value: T): T;
+/** Decodes a value or throws if error */
 export declare function Decode<T extends TSchema, R = StaticDecode<T>>(schema: T, references: TSchema[], value: unknown): R;
+/** Decodes a value or throws if error */
 export declare function Decode<T extends TSchema, R = StaticDecode<T>>(schema: T, value: unknown): R;
+/** `[Mutable]` Generates missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first. */
 export declare function Default<T extends TSchema>(schema: T, references: TSchema[], value: unknown): unknown;
+/** `[Mutable]` Generates missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first. */
 export declare function Default<T extends TSchema>(schema: T, value: unknown): unknown;
+/** Encodes a value or throws if error */
 export declare function Encode<T extends TSchema, R = StaticEncode<T>>(schema: T, references: TSchema[], value: unknown): R;
+/** Encodes a value or throws if error */
 export declare function Encode<T extends TSchema, R = StaticEncode<T>>(schema: T, value: unknown): R;
+/** Returns an iterator for each error in this value. */
 export declare function Errors<T extends TSchema>(schema: T, references: TSchema[], value: unknown): ValueErrorIterator;
+/** Returns an iterator for each error in this value. */
 export declare function Errors<T extends TSchema>(schema: T, value: unknown): ValueErrorIterator;
+/** Returns true if left and right values are structurally equal */
 export declare function Equal<T>(left: T, right: unknown): right is T;
+/** Returns edits to transform the current value into the next value */
 export declare function Diff(current: unknown, next: unknown): Edit[];
+/** Returns a FNV1A-64 non cryptographic hash of the given value */
 export declare function Hash(value: unknown): bigint;
+/** Returns a new value with edits applied to the given value */
 export declare function Patch<T = any>(current: unknown, edits: Edit[]): T;
+/** `[Mutable]` Performs a deep mutable value assignment while retaining internal references. */
 export declare function Mutate(current: Mutable, next: Mutable): void;

package/build/import/value/value/value.mjs

@@ -11,33 +11,42 @@ import { Check as CheckValue } from '../check/index.mjs';
 import { Default as DefaultValue } from '../default/index.mjs';
 import { Diff as DiffValue, Patch as PatchValue } from '../delta/index.mjs';
 import { Errors as ValueErrors } from '../../errors/index.mjs';
+/** Casts a value into a given type. The return value will retain as much information of the original value as possible. */
 export function Cast(...args) {
     return CastValue.apply(CastValue, args);
 }
+/** Creates a value from the given type */
 export function Create(...args) {
     return CreateValue.apply(CreateValue, args);
 }
+/** Returns true if the value matches the given type */
 export function Check(...args) {
     return CheckValue.apply(CheckValue, args);
 }
+/** `[Mutable]` Removes excess properties from a value and returns the result. This function does not check the value and returns an unknown type. You should Check the result before use. Clean is a mutable operation. To avoid mutation, Clone the value first. */
 export function Clean(...args) {
     return CleanValue.apply(CleanValue, args);
 }
+/** Converts any type mismatched values to their target type if a reasonable conversion is possible */
 export function Convert(...args) {
     return ConvertValue.apply(ConvertValue, args);
 }
+/** Returns a structural clone of the given value */
 export function Clone(value) {
     return CloneValue(value);
 }
+/** Decodes a value or throws if error */
 export function Decode(...args) {
     const [schema, references, value] = args.length === 3 ? [args[0], args[1], args[2]] : [args[0], [], args[1]];
     if (!Check(schema, references, value))
         throw new TransformDecodeCheckError(schema, value, Errors(schema, references, value).First());
     return TransformDecode(schema, references, value);
 }
+/** `[Mutable]` Generates missing properties on a value using default schema annotations if available. This function does not check the value and returns an unknown type. You should Check the result before use. Default is a mutable operation. To avoid mutation, Clone the value first. */
 export function Default(...args) {
     return DefaultValue.apply(DefaultValue, args);
 }
+/** Encodes a value or throws if error */
 export function Encode(...args) {
     const [schema, references, value] = args.length === 3 ? [args[0], args[1], args[2]] : [args[0], [], args[1]];
     const encoded = TransformEncode(schema, references, value);
@@ -45,21 +54,27 @@ export function Encode(...args) {
         throw new TransformEncodeCheckError(schema, value, Errors(schema, references, value).First());
     return encoded;
 }
+/** Returns an iterator for each error in this value. */
 export function Errors(...args) {
     return ValueErrors.apply(ValueErrors, args);
 }
+/** Returns true if left and right values are structurally equal */
 export function Equal(left, right) {
     return EqualValue(left, right);
 }
+/** Returns edits to transform the current value into the next value */
 export function Diff(current, next) {
     return DiffValue(current, next);
 }
+/** Returns a FNV1A-64 non cryptographic hash of the given value */
 export function Hash(value) {
     return HashValue(value);
 }
+/** Returns a new value with edits applied to the given value */
 export function Patch(current, edits) {
     return PatchValue(current, edits);
 }
+/** `[Mutable]` Performs a deep mutable value assignment while retaining internal references. */
 export function Mutate(current, next) {
     MutateValue(current, next);
 }

package/build/require/compiler/compiler.d.ts

@@ -9,10 +9,15 @@ export declare class TypeCheck<T extends TSchema> {
     private readonly code;
     private readonly hasTransform;
     constructor(schema: T, references: TSchema[], checkFunc: CheckFunction, code: string);
+    /** Returns the generated assertion code used to validate this type. */
     Code(): string;
+    /** Returns an iterator for each error in this value. */
     Errors(value: unknown): ValueErrorIterator;
+    /** Returns true if the value matches the compiled type. */
     Check(value: unknown): value is Static<T>;
+    /** Decodes a value or throws if error */
     Decode(value: unknown): StaticDecode<T>;
+    /** Encodes a value or throws if error */
     Encode(value: unknown): StaticEncode<T>;
 }
 export declare class TypeCompilerUnknownTypeError extends Error {
@@ -34,8 +39,12 @@ export type TypeCompilerLanguageOption = 'typescript' | 'javascript';
 export interface TypeCompilerCodegenOptions {
     language?: TypeCompilerLanguageOption;
 }
+/** Compiles Types for Runtime Type Checking */
 export declare namespace TypeCompiler {
+    /** Generates the code used to assert this type and returns it as a string */
     function Code<T extends TSchema>(schema: T, references: TSchema[], options?: TypeCompilerCodegenOptions): string;
+    /** Generates the code used to assert this type and returns it as a string */
     function Code<T extends TSchema>(schema: T, options?: TypeCompilerCodegenOptions): string;
+    /** Compiles a TypeBox type for optimal runtime type checking. Types must be valid TypeBox types of TSchema */
     function Compile<T extends TSchema>(schema: T, references?: TSchema[]): TypeCheck<T>;
 }