@livon/schema 0.27.0-rc.1

package/dist/typeGuards.spec.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __webpack_exports__ = {};
+const external_vitest_namespaceObject = require("vitest");
+const external_typeGuards_cjs_namespaceObject = require("./typeGuards.cjs");
+(0, external_vitest_namespaceObject.describe)('typeGuards', ()=>{
+    let validDate;
+    let invalidDate;
+    let bytes;
+    (0, external_vitest_namespaceObject.beforeAll)(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    (0, external_vitest_namespaceObject.beforeEach)(()=>{
+        validDate = new Date('2026-01-01T00:00:00.000Z');
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([
+            1,
+            2,
+            3
+        ]);
+    });
+    (0, external_vitest_namespaceObject.afterEach)(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    (0, external_vitest_namespaceObject.afterAll)(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    (0, external_vitest_namespaceObject.describe)('happy', ()=>{
+        (0, external_vitest_namespaceObject.it)('should return true when isString receives string input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isString)('livon')).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isNumber receives finite number input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isNumber)(42)).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isBoolean receives boolean input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isBoolean)(false)).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isDate receives valid date input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isDate)(validDate)).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isUint8Array receives uint8array input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isUint8Array)(bytes)).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isRecord receives plain object input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isRecord)({
+                id: 'u-1'
+            })).toBe(true);
+        });
+        (0, external_vitest_namespaceObject.it)('should return true when isArray guard receives array input', ()=>{
+            const guard = (0, external_typeGuards_cjs_namespaceObject.isArray)();
+            (0, external_vitest_namespaceObject.expect)(guard([
+                'a',
+                'b'
+            ])).toBe(true);
+        });
+    });
+    (0, external_vitest_namespaceObject.describe)('sad', ()=>{
+        (0, external_vitest_namespaceObject.it)('should return false when isString receives non-string input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isString)(42)).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isNumber receives nan input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isNumber)(NaN)).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isBoolean receives non-boolean input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isBoolean)('true')).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isDate receives invalid date input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isDate)(invalidDate)).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isUint8Array receives non-uint8array input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isUint8Array)([
+                1,
+                2,
+                3
+            ])).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isRecord receives null input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isRecord)(null)).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isRecord receives array input', ()=>{
+            (0, external_vitest_namespaceObject.expect)((0, external_typeGuards_cjs_namespaceObject.isRecord)([
+                'a'
+            ])).toBe(false);
+        });
+        (0, external_vitest_namespaceObject.it)('should return false when isArray guard receives non-array input', ()=>{
+            const guard = (0, external_typeGuards_cjs_namespaceObject.isArray)();
+            (0, external_vitest_namespaceObject.expect)(guard({
+                value: 'x'
+            })).toBe(false);
+        });
+    });
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/typeGuards.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/typeGuards.spec.js

@@ -0,0 +1,95 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { isArray, isBoolean, isDate, isNumber, isRecord, isString, isUint8Array } from "./typeGuards.js";
+describe('typeGuards', ()=>{
+    let validDate;
+    let invalidDate;
+    let bytes;
+    beforeAll(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    beforeEach(()=>{
+        validDate = new Date('2026-01-01T00:00:00.000Z');
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([
+            1,
+            2,
+            3
+        ]);
+    });
+    afterEach(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    afterAll(()=>{
+        validDate = new Date(0);
+        invalidDate = new Date('invalid');
+        bytes = new Uint8Array([]);
+    });
+    describe('happy', ()=>{
+        it('should return true when isString receives string input', ()=>{
+            expect(isString('livon')).toBe(true);
+        });
+        it('should return true when isNumber receives finite number input', ()=>{
+            expect(isNumber(42)).toBe(true);
+        });
+        it('should return true when isBoolean receives boolean input', ()=>{
+            expect(isBoolean(false)).toBe(true);
+        });
+        it('should return true when isDate receives valid date input', ()=>{
+            expect(isDate(validDate)).toBe(true);
+        });
+        it('should return true when isUint8Array receives uint8array input', ()=>{
+            expect(isUint8Array(bytes)).toBe(true);
+        });
+        it('should return true when isRecord receives plain object input', ()=>{
+            expect(isRecord({
+                id: 'u-1'
+            })).toBe(true);
+        });
+        it('should return true when isArray guard receives array input', ()=>{
+            const guard = isArray();
+            expect(guard([
+                'a',
+                'b'
+            ])).toBe(true);
+        });
+    });
+    describe('sad', ()=>{
+        it('should return false when isString receives non-string input', ()=>{
+            expect(isString(42)).toBe(false);
+        });
+        it('should return false when isNumber receives nan input', ()=>{
+            expect(isNumber(NaN)).toBe(false);
+        });
+        it('should return false when isBoolean receives non-boolean input', ()=>{
+            expect(isBoolean('true')).toBe(false);
+        });
+        it('should return false when isDate receives invalid date input', ()=>{
+            expect(isDate(invalidDate)).toBe(false);
+        });
+        it('should return false when isUint8Array receives non-uint8array input', ()=>{
+            expect(isUint8Array([
+                1,
+                2,
+                3
+            ])).toBe(false);
+        });
+        it('should return false when isRecord receives null input', ()=>{
+            expect(isRecord(null)).toBe(false);
+        });
+        it('should return false when isRecord receives array input', ()=>{
+            expect(isRecord([
+                'a'
+            ])).toBe(false);
+        });
+        it('should return false when isArray guard receives non-array input', ()=>{
+            const guard = isArray();
+            expect(guard({
+                value: 'x'
+            })).toBe(false);
+        });
+    });
+});

package/dist/types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/types.d.ts

@@ -0,0 +1,289 @@
+export type SchemaPath = readonly (string | number)[];
+export type SchemaIssue = {
+    path: SchemaPath;
+    message: string;
+    code?: string;
+    context?: Readonly<Record<string, unknown>>;
+};
+export type SchemaResultOk<T> = {
+    ok: true;
+    value: T;
+};
+export type SchemaResultFail = {
+    ok: false;
+    issues: readonly SchemaIssue[];
+    meta?: SchemaErrorMeta;
+};
+export type SchemaResult<T> = SchemaResultOk<T> | SchemaResultFail;
+export type SchemaErrorMeta = {
+    request?: SchemaRequestContext;
+    build?: SchemaBuildContext;
+    type?: string;
+    name?: string;
+};
+export interface AstNode {
+    type: string;
+    name?: string;
+    doc?: Readonly<Record<string, unknown>>;
+    request?: string;
+    response?: string;
+    dependsOn?: string;
+    constraints?: Readonly<Record<string, unknown>>;
+    children?: readonly AstNode[];
+}
+export type SchemaDoc = string | Readonly<Record<string, unknown>>;
+export interface AstBuilderAdd {
+    (node: AstNode): AstNode;
+}
+export interface AstBuilderGetAll {
+    (): readonly AstNode[];
+}
+export interface AstBuilder {
+    add: AstBuilderAdd;
+    getAll: AstBuilderGetAll;
+}
+export interface SchemaBuildContext {
+    buildId: string;
+    builder: AstBuilder;
+    parentNode?: AstNode;
+    schemaPath: readonly string[];
+    buildOptions: Readonly<Record<string, unknown>>;
+}
+export type SchemaBuildContextInput = Partial<SchemaBuildContext>;
+export interface SchemaStateGet {
+    <T = unknown>(key: string): T | undefined;
+}
+export interface SchemaStateSet {
+    <T = unknown>(key: string, value: T): void;
+}
+export interface SchemaStateUpdater<T> {
+    (current: T | undefined): T;
+}
+export interface SchemaStateUpdate {
+    <T = unknown>(key: string, updater: SchemaStateUpdater<T>): void;
+}
+export interface SchemaStateSnapshot {
+    (): Readonly<Record<string, unknown>>;
+}
+export interface SchemaState {
+    get: SchemaStateGet;
+    set: SchemaStateSet;
+    update: SchemaStateUpdate;
+    snapshot: SchemaStateSnapshot;
+}
+export type AckMode = 'received' | 'handled';
+export interface AckConfig {
+    required?: boolean;
+    mode?: AckMode;
+    timeoutMs?: number;
+    retries?: number;
+}
+export type PublishAck = boolean | AckConfig;
+export type PublishInput = {
+    topic: string;
+    payload: unknown;
+    input?: unknown;
+    ack?: PublishAck;
+    key?: string;
+    meta?: Readonly<Record<string, unknown>>;
+};
+export interface Publisher {
+    (input: PublishInput): void | Promise<void>;
+}
+export interface Logger {
+    error?: (message: string, info?: Readonly<Record<string, unknown>>, error?: unknown) => void;
+    warn?: (message: string, info?: Readonly<Record<string, unknown>>) => void;
+    info?: (message: string, info?: Readonly<Record<string, unknown>>) => void;
+    debug?: (message: string, info?: Readonly<Record<string, unknown>>) => void;
+}
+export interface PublishErrorHandler {
+    (error: unknown, info?: Readonly<Record<string, unknown>>): void;
+}
+export interface SchemaRequestContext {
+    requestId: string;
+    timestamp: number;
+    correlationId?: string;
+    sourceId?: string;
+    userId?: string;
+    tenantId?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+    normalized?: true;
+    state: SchemaState;
+    publisher?: Publisher;
+    onPublishError?: PublishErrorHandler;
+    logger?: Logger;
+}
+export type SchemaRequestContextInput = Partial<Omit<SchemaRequestContext, 'normalized' | 'state'>> | SchemaRequestContext;
+export interface SchemaContextGetBuild {
+    (): SchemaBuildContext | undefined;
+}
+export interface SchemaContextSetBuild {
+    (ctx?: SchemaBuildContext): void;
+}
+export interface SchemaContextGetRequest {
+    (): SchemaRequestContext | undefined;
+}
+export interface SchemaContextSetRequest {
+    (ctx?: SchemaRequestContextInput): void;
+}
+export interface SchemaContext {
+    getBuildContext: SchemaContextGetBuild;
+    setBuildContext: SchemaContextSetBuild;
+    getRequestContext: SchemaContextGetRequest;
+    setRequestContext: SchemaContextSetRequest;
+    request?: SchemaRequestContext;
+    state: SchemaState;
+}
+export interface SchemaParse<T> {
+    (input: unknown, ctx?: SchemaContext): T;
+}
+export interface SchemaValidate<T> {
+    (input: unknown, ctx?: SchemaContext): SchemaResult<T>;
+}
+export interface SchemaTyped<T> {
+    (input: T, ctx?: SchemaContext): T;
+}
+export interface SchemaAst {
+    (input?: SchemaBuildContextInput): AstNode;
+}
+export interface SchemaRefine<T> {
+    (value: T, ctx: SchemaContext): boolean;
+}
+export interface SchemaRefineInput<T> {
+    predicate: SchemaRefine<T>;
+    message: string;
+    code?: string;
+}
+export type SchemaHookBeforeResult = unknown | {
+    input: unknown;
+} | {
+    issues: readonly SchemaIssue[];
+} | {
+    input: unknown;
+    issues: readonly SchemaIssue[];
+};
+export type SchemaHookAfterResult<U> = U | {
+    value: U;
+} | {
+    issues: readonly SchemaIssue[];
+} | {
+    value: U;
+    issues: readonly SchemaIssue[];
+};
+export interface SchemaHookBefore {
+    (input: unknown, ctx: SchemaContext): SchemaHookBeforeResult;
+}
+export interface SchemaHookAfter<T, U> {
+    (value: T, ctx: SchemaContext): SchemaHookAfterResult<U>;
+}
+/**
+ * Adds `undefined` as an accepted value for the current schema.
+ *
+ * @returns A schema that accepts the original type or `undefined`.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const MaybeName = string().optional();
+ */
+export interface SchemaOptional<T> {
+    (): Schema<T | undefined>;
+}
+/**
+ * Adds `null` as an accepted value for the current schema.
+ *
+ * @returns A schema that accepts the original type or `null`.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const NullableName = string().nullable();
+ */
+export interface SchemaNullable<T> {
+    (): Schema<T | null>;
+}
+/**
+ * Adds an additional predicate-based validation step.
+ *
+ * @param input - Predicate and error metadata.
+ * @returns A schema with the extra refinement rule.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const Adult = number().refine({
+ *   predicate: (value) => value >= 18,
+ *   message: 'Must be at least 18',
+ * });
+ */
+export interface SchemaRefineMethod<T> {
+    (input: SchemaRefineInput<T>): Schema<T>;
+}
+/**
+ * Runs a preprocessing hook before base validation.
+ *
+ * @param hook - Hook that can transform input and/or emit issues.
+ * @returns A schema with the before-hook applied.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const Trimmed = string().before((input) =>
+ *   typeof input === 'string' ? input.trim() : input
+ * );
+ */
+export interface SchemaBeforeMethod<T> {
+    (hook: SchemaHookBefore): Schema<T>;
+}
+/**
+ * Runs a postprocessing hook after successful validation.
+ *
+ * @param hook - Hook that maps validated value to a new value.
+ * @returns A schema of the transformed output type.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const UserId = string().after((value) => value.toUpperCase());
+ */
+export interface SchemaAfterMethod<T> {
+    <U>(hook: SchemaHookAfter<T, U>): Schema<U>;
+}
+/**
+ * Creates an intersection schema with another schema.
+ *
+ * @param other - Schema to intersect with.
+ * @returns A schema that must satisfy both schemas.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const Combined = LeftSchema.and(RightSchema);
+ */
+export interface SchemaAndMethod<T> {
+    <U>(other: Schema<U>): Schema<T & U>;
+}
+/**
+ * Attaches documentation metadata to the schema AST node.
+ *
+ * @param doc - Documentation text or structured metadata.
+ * @returns A schema with merged documentation metadata.
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ *
+ * @example
+ * const Email = string().describe('User e-mail address');
+ */
+export interface SchemaDescribeMethod<T> {
+    (doc: SchemaDoc): Schema<T>;
+}
+export interface Schema<T> {
+    name: string;
+    type: string;
+    ast: SchemaAst;
+    validate: SchemaValidate<T>;
+    parse: SchemaParse<T>;
+    typed: SchemaTyped<T>;
+    optional: SchemaOptional<T>;
+    nullable: SchemaNullable<T>;
+    describe: SchemaDescribeMethod<T>;
+    refine: SchemaRefineMethod<T>;
+    before: SchemaBeforeMethod<T>;
+    after: SchemaAfterMethod<T>;
+    and: SchemaAndMethod<T>;
+}
+export type Shape = Readonly<Record<string, Schema<unknown>>>;
+export type Infer<TSchema> = TSchema extends Schema<infer TValue> ? TValue : never;

package/dist/union.cjs

@@ -0,0 +1,74 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    union: ()=>union
+});
+const external_schemaFactory_cjs_namespaceObject = require("./schemaFactory.cjs");
+const resolveUnionMatch = ({ input, ctx, options })=>{
+    const matches = options.map((option)=>{
+        try {
+            return {
+                ok: true,
+                value: option.parse(input, ctx)
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error
+            };
+        }
+    }).find((result)=>result.ok);
+    if (!matches) throw {
+        message: 'No union match',
+        code: 'union.match'
+    };
+    return matches.value;
+};
+const union = ({ name, options, doc })=>(0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+        name,
+        type: 'union',
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'union',
+                name,
+                children: options.map((option)=>option.ast(build ?? void 0))
+            };
+        },
+        validate: (input, ctx)=>resolveUnionMatch({
+                input,
+                ctx,
+                options
+            })
+    });
+exports.union = __webpack_exports__.union;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "union"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/union.d.ts

@@ -0,0 +1,33 @@
+import { Schema, SchemaDoc } from './types.js';
+type AnySchema = Schema<any>;
+export interface UnionSchemaInput<TValues extends readonly AnySchema[]> {
+    name: string;
+    options: TValues;
+    doc?: SchemaDoc;
+}
+/**
+ * union is part of the public LIVON API.
+ *
+ * @remarks
+ * Parameter and return types are defined in the TypeScript signature.
+ *
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/union
+ *
+ * @example
+ * // Creates a union schema that accepts either string or number identifiers.
+ * const Identifier = union({
+ *   name: 'identifier',
+ *   options: [string(), number()] as const,
+ * });
+ * Identifier.parse('user-1');
+ *
+ * @example
+ * // Extends the union schema to also allow undefined.
+ * const OptionalIdentifier = union({
+ *   name: 'identifier',
+ *   options: [string(), number()] as const,
+ * }).optional();
+ * OptionalIdentifier.parse(undefined);
+ */
+export declare const union: <TValues extends readonly AnySchema[]>({ name, options, doc, }: UnionSchemaInput<TValues>) => import("./schemaFactory.js").SchemaWithChain<ReturnType<TValues[number]["parse"]>, import("./schemaFactory.js").SchemaFactoryChainDefinition<ReturnType<TValues[number]["parse"]>>>;
+export {};

package/dist/union.js

@@ -0,0 +1,40 @@
+import { schemaFactory } from "./schemaFactory.js";
+const resolveUnionMatch = ({ input, ctx, options })=>{
+    const matches = options.map((option)=>{
+        try {
+            return {
+                ok: true,
+                value: option.parse(input, ctx)
+            };
+        } catch (error) {
+            return {
+                ok: false,
+                error
+            };
+        }
+    }).find((result)=>result.ok);
+    if (!matches) throw {
+        message: 'No union match',
+        code: 'union.match'
+    };
+    return matches.value;
+};
+const union = ({ name, options, doc })=>schemaFactory({
+        name,
+        type: 'union',
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'union',
+                name,
+                children: options.map((option)=>option.ast(build ?? void 0))
+            };
+        },
+        validate: (input, ctx)=>resolveUnionMatch({
+                input,
+                ctx,
+                options
+            })
+    });
+export { union };