@atscript/typescript 0.1.2 → 0.1.4

package/dist/utils.d.ts

@@ -3,7 +3,14 @@ interface TError {
     message: string;
     details?: TError[];
 }
+/**
+ * A plugin function that can intercept validation.
+ *
+ * Return `true` to accept the value, `false` to reject it,
+ * or `undefined` to fall through to the default validation.
+ */
 type TValidatorPlugin = (ctx: TValidatorPluginContext, def: TAtscriptAnnotatedType, value: any) => boolean | undefined;
+/** Options for configuring {@link Validator} behavior. */
 interface TValidatorOptions {
     partial: boolean | 'deep' | ((type: TAtscriptAnnotatedType<TAtscriptTypeObject>, path: string) => boolean);
     replace?: (type: TAtscriptAnnotatedType, path: string) => TAtscriptAnnotatedType;
@@ -12,16 +19,43 @@ interface TValidatorOptions {
     errorLimit: number;
     skipList?: Set<string>;
 }
+/** Context exposed to {@link TValidatorPlugin} functions. */
 interface TValidatorPluginContext {
     opts: Validator<any>['opts'];
     validateAnnotatedType: Validator<any>['validateAnnotatedType'];
     error: Validator<any>['error'];
     path: Validator<any>['path'];
 }
-declare class Validator<T extends TAtscriptAnnotatedTypeConstructor, IT = InstanceType<T>> {
+/**
+ * Validates values against an {@link TAtscriptAnnotatedType} definition.
+ *
+ * `DataType` is automatically inferred from the type definition's phantom generic,
+ * enabling the {@link validate} method to act as a type guard.
+ *
+ * @example
+ * ```ts
+ * // From a generated interface class:
+ * const validator = new Validator(MyInterface)
+ * if (validator.validate(data, true)) {
+ *   data // narrowed to MyInterface
+ * }
+ *
+ * // Or use the built-in factory:
+ * MyInterface.validator().validate(data)
+ * ```
+ *
+ * @typeParam T - The annotated type definition.
+ * @typeParam DataType - The TypeScript type that `validate` narrows to (auto-inferred).
+ */
+declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = T extends {
+    type: {
+        __dataType?: infer D;
+    };
+} ? unknown extends D ? T extends new (...args: any[]) => infer I ? I : unknown : D : unknown> {
     protected readonly def: T;
     protected opts: TValidatorOptions;
     constructor(def: T, opts?: Partial<TValidatorOptions>);
+    /** Validation errors collected during the last {@link validate} call. */
     errors: TError[];
     protected stackErrors: TError[][];
     protected stackPath: string[];
@@ -31,7 +65,18 @@ declare class Validator<T extends TAtscriptAnnotatedTypeConstructor, IT = Instan
     protected clear(): void;
     protected error(message: string, path?: string, details?: TError[]): void;
     protected throw(): void;
-    validate<TT = IT>(value: any, safe?: boolean): value is TT;
+    /**
+     * Validates a value against the type definition.
+     *
+     * Acts as a TypeScript type guard — when it returns `true`, the value
+     * is narrowed to `DataType`.
+     *
+     * @param value - The value to validate.
+     * @param safe - If `true`, returns `false` on failure instead of throwing.
+     * @returns `true` if the value matches the type definition.
+     * @throws {ValidatorError} When validation fails and `safe` is not `true`.
+     */
+    validate<TT = DataType>(value: any, safe?: boolean): value is TT;
     protected validateSafe(def: TAtscriptAnnotatedType, value: any): boolean;
     protected get path(): string;
     protected validateAnnotatedType(def: TAtscriptAnnotatedType, value: any): boolean;
@@ -44,23 +89,31 @@ declare class Validator<T extends TAtscriptAnnotatedTypeConstructor, IT = Instan
     protected validateString(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: string): boolean;
     protected validateNumber(def: TAtscriptAnnotatedType<TAtscriptTypeFinal>, value: number): boolean;
 }
+/** Error thrown by {@link Validator.validate} when validation fails. Contains structured error details. */
 declare class ValidatorError extends Error {
     readonly errors: TError[];
     name: string;
     constructor(errors: TError[]);
 }
 
-interface TAtscriptTypeComplex {
+/** Type definition for union, intersection, or tuple types. */
+interface TAtscriptTypeComplex<DataType = unknown> {
     kind: 'union' | 'intersection' | 'tuple';
     items: TAtscriptAnnotatedType[];
     tags: Set<AtscriptPrimitiveTags>;
+    /** @internal phantom — carries the DataType at the type level, never set at runtime */
+    __dataType?: DataType;
 }
-interface TAtscriptTypeArray {
+/** Type definition for array types. */
+interface TAtscriptTypeArray<DataType = unknown[]> {
     kind: 'array';
     of: TAtscriptAnnotatedType;
     tags: Set<AtscriptPrimitiveTags>;
+    /** @internal phantom — carries the DataType at the type level, never set at runtime */
+    __dataType?: DataType;
 }
-interface TAtscriptTypeObject<K extends string = string> {
+/** Type definition for object types with named and pattern-matched properties. */
+interface TAtscriptTypeObject<K extends string = string, DataType = Record<K, unknown>> {
     kind: 'object';
     props: Map<K, TAtscriptAnnotatedType>;
     propsPatterns: {
@@ -68,27 +121,49 @@ interface TAtscriptTypeObject<K extends string = string> {
         def: TAtscriptAnnotatedType;
     }[];
     tags: Set<AtscriptPrimitiveTags>;
+    /** @internal phantom — carries the DataType at the type level, never set at runtime */
+    __dataType?: DataType;
 }
-interface TAtscriptTypeFinal {
+/** Type definition for primitive/literal types (string, number, boolean, null, etc.). */
+interface TAtscriptTypeFinal<DataType = unknown> {
     kind: '';
     /**
      * design type
      */
-    designType: 'string' | 'number' | 'boolean' | 'undefined' | 'null' | 'object' | 'any' | 'never';
+    designType: 'string' | 'number' | 'boolean' | 'undefined' | 'null' | 'object' | 'any' | 'never' | 'phantom';
     /**
      * value for literals
      */
     value?: string | number | boolean;
     tags: Set<AtscriptPrimitiveTags>;
+    /** @internal phantom — carries the DataType at the type level, never set at runtime */
+    __dataType?: DataType;
 }
-type TAtscriptTypeDef = TAtscriptTypeComplex | TAtscriptTypeFinal | TAtscriptTypeArray | TAtscriptTypeObject<string>;
-interface TAtscriptAnnotatedType<T = TAtscriptTypeDef> {
+/**
+ * Extract DataType from a type def's phantom generic
+ */
+type InferDataType<T> = T extends {
+    __dataType?: infer D;
+} ? D : unknown;
+/** Union of all possible type definition shapes. */
+type TAtscriptTypeDef<DataType = unknown> = TAtscriptTypeComplex<DataType> | TAtscriptTypeFinal<DataType> | TAtscriptTypeArray<DataType> | TAtscriptTypeObject<string, DataType>;
+/**
+ * Core annotated type — wraps a type definition with metadata and a validator factory.
+ *
+ * Generated `.as` files produce classes/namespaces that conform to this interface.
+ * The `DataType` phantom generic carries the TypeScript data shape for type-safe validation.
+ *
+ * @typeParam T - The underlying type definition (e.g. {@link TAtscriptTypeObject}).
+ * @typeParam DataType - The TypeScript type the validated data narrows to (auto-inferred from `T`).
+ */
+interface TAtscriptAnnotatedType<T extends TAtscriptTypeDef = TAtscriptTypeDef, DataType = InferDataType<T>> {
     __is_atscript_annotated_type: true;
     type: T;
-    validator: <TT extends TAtscriptAnnotatedTypeConstructor>(opts?: Partial<TValidatorOptions>) => Validator<TT>;
+    validator(opts?: Partial<TValidatorOptions>): Validator<this, DataType>;
     metadata: TMetadataMap<AtscriptMetadata>;
     optional?: boolean;
 }
+/** An annotated type that is also a class constructor (i.e. a generated interface class). */
 type TAtscriptAnnotatedTypeConstructor = TAtscriptAnnotatedType & (new (...args: any[]) => any);
 /**
  * Type Guard to check if a type is atscript-annotated
@@ -100,6 +175,25 @@ declare function isAnnotatedType(type: any): type is TAtscriptAnnotatedType;
  */
 declare function annotate<K extends keyof AtscriptMetadata>(metadata: TMetadataMap<AtscriptMetadata> | undefined, key: K, value: AtscriptMetadata[K] extends (infer E)[] ? E : AtscriptMetadata[K], asArray?: boolean): void;
 type TKind = '' | 'array' | 'object' | 'union' | 'intersection' | 'tuple';
+/**
+ * Creates a builder handle for constructing a {@link TAtscriptAnnotatedType} at runtime.
+ *
+ * This is primarily used by generated `.as.js` code. The returned handle provides
+ * a fluent API for setting the type definition, metadata, and properties.
+ *
+ * @example
+ * ```ts
+ * const handle = defineAnnotatedType('object')
+ *   .prop('name', defineAnnotatedType().designType('string').$type)
+ *   .prop('age', defineAnnotatedType().designType('number').$type)
+ *
+ * handle.$type // the resulting TAtscriptAnnotatedType
+ * ```
+ *
+ * @param _kind - The kind of type to create (e.g. `'object'`, `'array'`, `'union'`). Defaults to `''` (primitive/final).
+ * @param base - Optional existing object to augment with annotated type fields.
+ * @returns A builder handle for fluent type construction.
+ */
 declare function defineAnnotatedType(_kind?: TKind, base?: any): TAnnotatedTypeHandle;
 /**
  * Atscript Metadata Map with typed setters/getters
@@ -108,6 +202,7 @@ interface TMetadataMap<O extends object> extends Map<keyof O, O[keyof O]> {
     get<K extends keyof O>(key: K): O[K] | undefined;
     set<K extends keyof O>(key: K, value: O[K]): this;
 }
+/** Fluent builder handle returned by {@link defineAnnotatedType}. */
 interface TAnnotatedTypeHandle {
     $type: TAtscriptAnnotatedType;
     $def: {
@@ -129,10 +224,189 @@ interface TAnnotatedTypeHandle {
     }, chain?: string[]): TAnnotatedTypeHandle;
     annotate(key: keyof AtscriptMetadata, value: any, asArray?: boolean): TAnnotatedTypeHandle;
 }
+/**
+ * Checks whether an annotated type is a phantom type.
+ *
+ * Phantom types do not affect the data type, validation, or schema,
+ * but are discoverable via runtime type traversal.
+ */
+declare function isPhantomType(def: TAtscriptAnnotatedType): boolean;
+/**
+ * Checks whether an annotated type resolves to a primitive (non-object, non-array) shape.
+ *
+ * Returns `true` for final types and for unions/intersections/tuples
+ * whose members are all primitives.
+ */
 declare function isAnnotatedTypeOfPrimitive(t: TAtscriptAnnotatedType): boolean;
 
+/** A JSON Schema object (draft-compatible). */
 type TJsonSchema = Record<string, any>;
+/**
+ * Builds a JSON Schema from an {@link TAtscriptAnnotatedType}.
+ *
+ * Translates the atscript type structure and validation metadata
+ * (min/max, patterns, integer constraints, etc.) into a standard JSON Schema.
+ *
+ * @example
+ * ```ts
+ * import { buildJsonSchema } from '@atscript/typescript'
+ *
+ * const schema = buildJsonSchema(MyInterface)
+ * // { type: 'object', properties: { ... }, required: [...] }
+ * ```
+ *
+ * @param type - The annotated type to convert.
+ * @returns A JSON Schema object.
+ */
 declare function buildJsonSchema(type: TAtscriptAnnotatedType): TJsonSchema;
+/**
+ * Converts a JSON Schema object into a {@link TAtscriptAnnotatedType}.
+ *
+ * This is the inverse of {@link buildJsonSchema}. A round-trip
+ * `buildJsonSchema(fromJsonSchema(schema))` preserves structure and constraints.
+ *
+ * Supports the JSON Schema subset produced by `buildJsonSchema` plus
+ * common extensions like `oneOf` (treated as union) and `enum` (union of literals).
+ *
+ * @example
+ * ```ts
+ * import { fromJsonSchema } from '@atscript/typescript'
+ *
+ * const type = fromJsonSchema({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] })
+ * type.validator().validate({ name: 'Alice' }) // passes
+ * ```
+ *
+ * @param schema - A JSON Schema object.
+ * @returns An annotated type with full validator support.
+ */
+declare function fromJsonSchema(schema: TJsonSchema): TAtscriptAnnotatedType;
+
+/**
+ * Type-safe dispatch over `TAtscriptAnnotatedType` by its `type.kind`.
+ *
+ * Provides the common `switch (def.type.kind)` pattern used by
+ * the validator, JSON-schema builder, and serializer.
+ * Each caller supplies its own handlers that control recursion.
+ *
+ * When a `phantom` handler is provided, phantom types (`designType === 'phantom'`)
+ * are dispatched to it instead of `final`. This allows consumers to skip or
+ * handle phantom props without polluting their `final` handler.
+ */
+declare function forAnnotatedType<R>(def: TAtscriptAnnotatedType, handlers: {
+    final: (def: TAtscriptAnnotatedType<TAtscriptTypeFinal>) => R;
+    object: (def: TAtscriptAnnotatedType<TAtscriptTypeObject<string>>) => R;
+    array: (def: TAtscriptAnnotatedType<TAtscriptTypeArray>) => R;
+    union: (def: TAtscriptAnnotatedType<TAtscriptTypeComplex>) => R;
+    intersection: (def: TAtscriptAnnotatedType<TAtscriptTypeComplex>) => R;
+    tuple: (def: TAtscriptAnnotatedType<TAtscriptTypeComplex>) => R;
+    phantom?: (def: TAtscriptAnnotatedType<TAtscriptTypeFinal>) => R;
+}): R;
+
+/** Current serialization format version. Bumped on breaking changes to the serialized shape. */
+declare const SERIALIZE_VERSION = 1;
+/** Top-level serialized annotated type. JSON-safe representation of a {@link TAtscriptAnnotatedType}. */
+interface TSerializedAnnotatedType extends TSerializedAnnotatedTypeInner {
+    /** Format version for forward compatibility */
+    $v: number;
+}
+/** Serialized annotated type node (used for nested types within the top-level). */
+interface TSerializedAnnotatedTypeInner {
+    type: TSerializedTypeDef;
+    metadata: Record<string, unknown>;
+    optional?: boolean;
+}
+interface TSerializedTypeFinal {
+    kind: '';
+    designType: string;
+    value?: string | number | boolean;
+    tags: string[];
+}
+interface TSerializedTypeObject {
+    kind: 'object';
+    props: Record<string, TSerializedAnnotatedTypeInner>;
+    propsPatterns: {
+        pattern: {
+            source: string;
+            flags: string;
+        };
+        def: TSerializedAnnotatedTypeInner;
+    }[];
+    tags: string[];
+}
+interface TSerializedTypeArray {
+    kind: 'array';
+    of: TSerializedAnnotatedTypeInner;
+    tags: string[];
+}
+interface TSerializedTypeComplex {
+    kind: 'union' | 'intersection' | 'tuple';
+    items: TSerializedAnnotatedTypeInner[];
+    tags: string[];
+}
+type TSerializedTypeDef = TSerializedTypeFinal | TSerializedTypeObject | TSerializedTypeArray | TSerializedTypeComplex;
+/** Context passed to {@link TSerializeOptions.processAnnotation} for each annotation entry. */
+interface TProcessAnnotationContext {
+    /** Annotation key, e.g. "meta.label" */
+    key: string;
+    /** Annotation value */
+    value: unknown;
+    /** Property path to the current node, e.g. ["address", "city"] */
+    path: string[];
+    /** The `kind` of the current type node */
+    kind: '' | 'object' | 'array' | 'union' | 'intersection' | 'tuple';
+}
+/** Options for controlling which annotations are included during serialization. */
+interface TSerializeOptions {
+    /** Simple list of annotation keys to strip */
+    ignoreAnnotations?: string[];
+    /**
+     * Advanced per-annotation callback. Called after `ignoreAnnotations` filtering.
+     * Return `{ key, value }` to keep (possibly renamed/transformed).
+     * Return `undefined` or `void` to strip the annotation.
+     */
+    processAnnotation?: (ctx: TProcessAnnotationContext) => {
+        key: string;
+        value: unknown;
+    } | undefined | void;
+}
+/**
+ * Converts a runtime {@link TAtscriptAnnotatedType} into a plain JSON-safe object.
+ *
+ * The result can be stored, transmitted over the network, and later
+ * restored with {@link deserializeAnnotatedType}.
+ *
+ * @example
+ * ```ts
+ * import { serializeAnnotatedType } from '@atscript/typescript'
+ *
+ * const json = serializeAnnotatedType(MyInterface)
+ * // json is a plain object safe for JSON.stringify
+ * ```
+ *
+ * @param type - The annotated type to serialize.
+ * @param options - Optional filtering/transformation for annotations.
+ * @returns A versioned, JSON-safe representation of the type.
+ */
+declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?: TSerializeOptions): TSerializedAnnotatedType;
+/**
+ * Restores a runtime {@link TAtscriptAnnotatedType} from its serialized form.
+ *
+ * The returned object is fully functional — it has a working `.validator()` method
+ * and can be used with {@link buildJsonSchema} or the {@link Validator} directly.
+ *
+ * @example
+ * ```ts
+ * import { deserializeAnnotatedType } from '@atscript/typescript'
+ *
+ * const type = deserializeAnnotatedType(json)
+ * type.validator().validate(someValue) // works
+ * ```
+ *
+ * @param data - A serialized type produced by {@link serializeAnnotatedType}.
+ * @returns A live annotated type with validator support.
+ * @throws If the serialized version doesn't match {@link SERIALIZE_VERSION}.
+ */
+declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
-export { Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, isAnnotatedType, isAnnotatedTypeOfPrimitive };
-export type { TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TMetadataMap, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext };
+export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, defineAnnotatedType, deserializeAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, serializeAnnotatedType };
+export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext };