@livon/schema 0.27.0-rc.1

package/dist/schemaFactory.d.ts

@@ -0,0 +1,97 @@
+import { Schema, SchemaContext, SchemaDoc } from './types.js';
+import { TypeGuard } from './typeGuards.js';
+export interface SchemaFactoryErrorLike {
+    message: string;
+    code?: string;
+    context?: Readonly<Record<string, unknown>>;
+}
+export interface SchemaFactoryValidate<T> {
+    (input: unknown, ctx: SchemaContext): T;
+}
+/**
+ * Defines one chain operation for a schema value.
+ *
+ * @typeParam TValue - Current schema output type.
+ * @typeParam TArgs - Operation argument tuple.
+ * @typeParam TNext - Output type after applying the operation.
+ *
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/schema-factory
+ *
+ * @example
+ * interface MinChain {
+ *   (value: number): (min: number) => number;
+ * }
+ */
+export interface SchemaFactoryChainOperation<TValue, TArgs extends readonly unknown[], TNext> {
+    (value: TValue, ctx: SchemaContext): (...args: TArgs) => TNext;
+}
+/**
+ * Map of chain operation names to chain operation implementations.
+ *
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/schema-factory
+ */
+export type SchemaFactoryChainDefinition<TValue> = Record<string, SchemaFactoryChainOperation<TValue, readonly any[], any>>;
+/**
+ * Public chain method surface inferred from a chain definition.
+ *
+ * Every chain method returns a new schema that keeps the same chain API.
+ *
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/schema-factory
+ */
+export type SchemaChainMethods<TChain extends SchemaFactoryChainDefinition<any>> = {
+    [K in keyof TChain]: TChain[K] extends SchemaFactoryChainOperation<any, infer TArgs, infer TNext> ? (...args: TArgs) => SchemaWithChain<TNext, TChain> : never;
+};
+/**
+ * Schema type enriched with fluent chain methods.
+ *
+ * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/schema-factory
+ *
+ * @example
+ * const Name = string().min(3).max(50);
+ */
+export type SchemaWithChain<TValue, TChain extends SchemaFactoryChainDefinition<TValue>> = Schema<TValue> & SchemaChainMethods<TChain>;
+export interface SchemaFactoryInput<TValue, TChain extends SchemaFactoryChainDefinition<TValue>> {
+    name: string;
+    type: string;
+    validate: SchemaFactoryValidate<TValue>;
+    ast: (ctx: SchemaContext) => ReturnType<Schema<TValue>['ast']>;
+    doc?: SchemaDoc;
+    chain?: TChain;
+}
+export interface SchemaFactory {
+    <TValue, TChain extends SchemaFactoryChainDefinition<TValue> = SchemaFactoryChainDefinition<TValue>>(input: SchemaFactoryInput<TValue, TChain>): SchemaWithChain<TValue, TChain>;
+}
+export interface GuardFactoryInput<T> {
+    name: string;
+    type: string;
+    guard: TypeGuard<T>;
+    message: string;
+    code?: string;
+}
+export interface GuardFactory {
+    <T>(input: GuardFactoryInput<T>): Schema<T>;
+}
+/**
+ * schemaFactory 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/schema-factory
+ *
+ * @example
+ * const result = schemaFactory(undefined as never);
+ */
+export declare const schemaFactory: <TValue, TChain extends SchemaFactoryChainDefinition<TValue> = SchemaFactoryChainDefinition<TValue>>({ name, type, validate, ast, doc, chain, }: SchemaFactoryInput<TValue, TChain>) => SchemaWithChain<TValue, TChain>;
+/**
+ * guardFactory 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/schema-factory
+ *
+ * @example
+ * const result = guardFactory(undefined as never);
+ */
+export declare const guardFactory: GuardFactory;

package/dist/schemaFactory.js

@@ -0,0 +1,88 @@
+import { createIssueForPath, createSchema, ensureSchemaContext, fail, ok } from "./schema.js";
+import { mergeDoc, normalizeDoc } from "./doc.js";
+const normalizeError = (error)=>{
+    if (error && 'object' == typeof error && 'message' in error) {
+        const err = error;
+        return {
+            message: err.message,
+            code: err.code,
+            context: err.context
+        };
+    }
+    return {
+        message: 'Schema validation failed'
+    };
+};
+const schemaFactory = ({ name, type, validate, ast, doc, chain })=>{
+    const docRecord = normalizeDoc(doc);
+    const astWithDoc = docRecord ? (ctx)=>{
+        const node = ast(ctx);
+        const merged = mergeDoc(node.doc, docRecord);
+        return merged ? {
+            ...node,
+            doc: merged
+        } : node;
+    } : ast;
+    const base = createSchema({
+        name,
+        type,
+        ast: astWithDoc,
+        validate: (input, ctx)=>{
+            const context = ensureSchemaContext(ctx);
+            try {
+                const value = validate(input, context);
+                return ok({
+                    value
+                });
+            } catch (error) {
+                const normalized = normalizeError(error);
+                return fail({
+                    issues: [
+                        createIssueForPath({
+                            path: [],
+                            message: normalized.message,
+                            code: normalized.code,
+                            context: normalized.context
+                        })
+                    ]
+                });
+            }
+        }
+    });
+    const result = base;
+    if (!chain) return result;
+    Object.entries(chain).forEach(([key, operation])=>{
+        result[key] = (...args)=>schemaFactory({
+                name: `${name}.${key}`,
+                type,
+                ast,
+                validate: (input, ctx)=>{
+                    const context = ensureSchemaContext(ctx);
+                    const value = base.parse(input, context);
+                    const next = operation(value, context)(...args);
+                    return next;
+                },
+                chain: chain
+            });
+    });
+    return result;
+};
+const guardFactory = ({ name, type, guard, message, code })=>schemaFactory({
+        name,
+        type,
+        ast: ()=>({
+                type,
+                name
+            }),
+        validate: (input)=>{
+            if (!guard(input)) {
+                const error = {
+                    message,
+                    code
+                };
+                throw error;
+            }
+            return input;
+        }
+    });
+export { guardFactory, schemaFactory };

package/dist/schemaFactory.spec.cjs

@@ -0,0 +1,197 @@
+"use strict";
+var __webpack_exports__ = {};
+const external_vitest_namespaceObject = require("vitest");
+const external_context_cjs_namespaceObject = require("./context.cjs");
+const index_cjs_namespaceObject = require("./testing/mocks/index.cjs");
+const external_schemaFactory_cjs_namespaceObject = require("./schemaFactory.cjs");
+(0, external_vitest_namespaceObject.describe)('schemaFactory()', ()=>{
+    let astNode;
+    let context;
+    (0, external_vitest_namespaceObject.beforeAll)(()=>{
+        astNode = {
+            type: 'custom',
+            name: 'Custom'
+        };
+        context = (0, external_context_cjs_namespaceObject.createSchemaContext)();
+    });
+    (0, external_vitest_namespaceObject.beforeEach)(()=>{
+        astNode = {
+            type: 'custom',
+            name: 'Custom'
+        };
+        context = (0, external_context_cjs_namespaceObject.createSchemaContext)();
+    });
+    (0, external_vitest_namespaceObject.afterEach)(()=>{
+        external_vitest_namespaceObject.vi.clearAllMocks();
+    });
+    (0, external_vitest_namespaceObject.afterAll)(()=>{
+        external_vitest_namespaceObject.vi.restoreAllMocks();
+    });
+    (0, external_vitest_namespaceObject.describe)('happy', ()=>{
+        (0, external_vitest_namespaceObject.it)('should create schema that parses validated value when validate succeeds', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+                name: 'Custom',
+                type: 'custom',
+                ast: ()=>astNode,
+                validate: (input)=>String(input)
+            });
+            const parsed = schema.parse(123, context);
+            (0, external_vitest_namespaceObject.expect)(parsed).toBe('123');
+            (0, external_vitest_namespaceObject.expect)(schema.name).toBe('Custom');
+            (0, external_vitest_namespaceObject.expect)(schema.type).toBe('custom');
+        });
+        (0, external_vitest_namespaceObject.it)('should merge schema level doc into ast when doc is provided', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+                name: 'WithDoc',
+                type: 'custom',
+                doc: {
+                    summary: 'Schema doc'
+                },
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'WithDoc',
+                        doc: {
+                            source: 'internal'
+                        }
+                    }),
+                validate: (input)=>input
+            });
+            const ast = schema.ast();
+            (0, external_vitest_namespaceObject.expect)(ast.doc).toEqual({
+                source: 'internal',
+                summary: 'Schema doc'
+            });
+        });
+        (0, external_vitest_namespaceObject.it)('should build chained schema when chain method is called', ()=>{
+            const plusOperation = external_vitest_namespaceObject.vi.fn((value, _ctx)=>(step)=>value + step);
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+                name: 'Score',
+                type: 'number',
+                ast: ()=>({
+                        type: 'number',
+                        name: 'Score'
+                    }),
+                validate: (input)=>Number(input),
+                chain: {
+                    plus: plusOperation
+                }
+            });
+            const plusSchema = schema.plus(2);
+            const parsed = plusSchema.parse(3, context);
+            (0, external_vitest_namespaceObject.expect)(parsed).toBe(5);
+            (0, external_vitest_namespaceObject.expect)(plusOperation).toHaveBeenCalledWith(3, context);
+            (0, external_vitest_namespaceObject.expect)(plusSchema.name).toBe('Score.plus');
+        });
+    });
+    (0, external_vitest_namespaceObject.describe)('sad', ()=>{
+        (0, external_vitest_namespaceObject.it)('should convert thrown object into schema issue when validate throws error-like value', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+                name: 'Failing',
+                type: 'custom',
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'Failing'
+                    }),
+                validate: ()=>{
+                    throw {
+                        message: 'Validation exploded',
+                        code: 'custom.fail',
+                        context: {
+                            reason: 'test'
+                        }
+                    };
+                }
+            });
+            const thrown = (0, index_cjs_namespaceObject.captureThrow)(()=>schema.parse('x', context));
+            (0, external_vitest_namespaceObject.expect)(thrown.threw).toBe(true);
+            (0, external_vitest_namespaceObject.expect)(thrown.value).toMatchObject({
+                message: 'Schema validation failed',
+                issues: [
+                    {
+                        message: 'Validation exploded',
+                        code: 'custom.fail',
+                        context: {
+                            reason: 'test'
+                        }
+                    }
+                ]
+            });
+        });
+        (0, external_vitest_namespaceObject.it)('should convert thrown primitive into default validation message when validate throws non-object', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+                name: 'PrimitiveThrow',
+                type: 'custom',
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'PrimitiveThrow'
+                    }),
+                validate: ()=>{
+                    throw 'primitive failure';
+                }
+            });
+            const thrown = (0, index_cjs_namespaceObject.captureThrow)(()=>schema.parse('x', context));
+            (0, external_vitest_namespaceObject.expect)(thrown.threw).toBe(true);
+            (0, external_vitest_namespaceObject.expect)(thrown.value).toMatchObject({
+                issues: [
+                    {
+                        message: 'Schema validation failed'
+                    }
+                ]
+            });
+        });
+    });
+});
+(0, external_vitest_namespaceObject.describe)('guardFactory()', ()=>{
+    let context;
+    (0, external_vitest_namespaceObject.beforeAll)(()=>{
+        context = (0, external_context_cjs_namespaceObject.createSchemaContext)();
+    });
+    (0, external_vitest_namespaceObject.beforeEach)(()=>{
+        context = (0, external_context_cjs_namespaceObject.createSchemaContext)();
+    });
+    (0, external_vitest_namespaceObject.afterEach)(()=>{
+        external_vitest_namespaceObject.vi.clearAllMocks();
+    });
+    (0, external_vitest_namespaceObject.afterAll)(()=>{
+        external_vitest_namespaceObject.vi.restoreAllMocks();
+    });
+    (0, external_vitest_namespaceObject.describe)('happy', ()=>{
+        (0, external_vitest_namespaceObject.it)('should return input value when guard accepts input', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.guardFactory)({
+                name: 'GuardedString',
+                type: 'string',
+                guard: (input)=>'string' == typeof input,
+                message: 'Expected string',
+                code: 'string.type'
+            });
+            const parsed = schema.parse('ok', context);
+            (0, external_vitest_namespaceObject.expect)(parsed).toBe('ok');
+            (0, external_vitest_namespaceObject.expect)(schema.ast().type).toBe('string');
+        });
+    });
+    (0, external_vitest_namespaceObject.describe)('sad', ()=>{
+        (0, external_vitest_namespaceObject.it)('should throw schema validation error when guard rejects input', ()=>{
+            const schema = (0, external_schemaFactory_cjs_namespaceObject.guardFactory)({
+                name: 'GuardedString',
+                type: 'string',
+                guard: (input)=>'string' == typeof input,
+                message: 'Expected string',
+                code: 'string.type'
+            });
+            const thrown = (0, index_cjs_namespaceObject.captureThrow)(()=>schema.parse(1, context));
+            (0, external_vitest_namespaceObject.expect)(thrown.threw).toBe(true);
+            (0, external_vitest_namespaceObject.expect)(thrown.value).toMatchObject({
+                issues: [
+                    {
+                        message: 'Expected string',
+                        code: 'string.type'
+                    }
+                ]
+            });
+        });
+    });
+});
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/schemaFactory.spec.d.ts

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

package/dist/schemaFactory.spec.js

@@ -0,0 +1,191 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSchemaContext } from "./context.js";
+import { captureThrow } from "./testing/mocks/index.js";
+import { guardFactory, schemaFactory } from "./schemaFactory.js";
+describe('schemaFactory()', ()=>{
+    let astNode;
+    let context;
+    beforeAll(()=>{
+        astNode = {
+            type: 'custom',
+            name: 'Custom'
+        };
+        context = createSchemaContext();
+    });
+    beforeEach(()=>{
+        astNode = {
+            type: 'custom',
+            name: 'Custom'
+        };
+        context = createSchemaContext();
+    });
+    afterEach(()=>{
+        vi.clearAllMocks();
+    });
+    afterAll(()=>{
+        vi.restoreAllMocks();
+    });
+    describe('happy', ()=>{
+        it('should create schema that parses validated value when validate succeeds', ()=>{
+            const schema = schemaFactory({
+                name: 'Custom',
+                type: 'custom',
+                ast: ()=>astNode,
+                validate: (input)=>String(input)
+            });
+            const parsed = schema.parse(123, context);
+            expect(parsed).toBe('123');
+            expect(schema.name).toBe('Custom');
+            expect(schema.type).toBe('custom');
+        });
+        it('should merge schema level doc into ast when doc is provided', ()=>{
+            const schema = schemaFactory({
+                name: 'WithDoc',
+                type: 'custom',
+                doc: {
+                    summary: 'Schema doc'
+                },
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'WithDoc',
+                        doc: {
+                            source: 'internal'
+                        }
+                    }),
+                validate: (input)=>input
+            });
+            const ast = schema.ast();
+            expect(ast.doc).toEqual({
+                source: 'internal',
+                summary: 'Schema doc'
+            });
+        });
+        it('should build chained schema when chain method is called', ()=>{
+            const plusOperation = vi.fn((value, _ctx)=>(step)=>value + step);
+            const schema = schemaFactory({
+                name: 'Score',
+                type: 'number',
+                ast: ()=>({
+                        type: 'number',
+                        name: 'Score'
+                    }),
+                validate: (input)=>Number(input),
+                chain: {
+                    plus: plusOperation
+                }
+            });
+            const plusSchema = schema.plus(2);
+            const parsed = plusSchema.parse(3, context);
+            expect(parsed).toBe(5);
+            expect(plusOperation).toHaveBeenCalledWith(3, context);
+            expect(plusSchema.name).toBe('Score.plus');
+        });
+    });
+    describe('sad', ()=>{
+        it('should convert thrown object into schema issue when validate throws error-like value', ()=>{
+            const schema = schemaFactory({
+                name: 'Failing',
+                type: 'custom',
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'Failing'
+                    }),
+                validate: ()=>{
+                    throw {
+                        message: 'Validation exploded',
+                        code: 'custom.fail',
+                        context: {
+                            reason: 'test'
+                        }
+                    };
+                }
+            });
+            const thrown = captureThrow(()=>schema.parse('x', context));
+            expect(thrown.threw).toBe(true);
+            expect(thrown.value).toMatchObject({
+                message: 'Schema validation failed',
+                issues: [
+                    {
+                        message: 'Validation exploded',
+                        code: 'custom.fail',
+                        context: {
+                            reason: 'test'
+                        }
+                    }
+                ]
+            });
+        });
+        it('should convert thrown primitive into default validation message when validate throws non-object', ()=>{
+            const schema = schemaFactory({
+                name: 'PrimitiveThrow',
+                type: 'custom',
+                ast: ()=>({
+                        type: 'custom',
+                        name: 'PrimitiveThrow'
+                    }),
+                validate: ()=>{
+                    throw 'primitive failure';
+                }
+            });
+            const thrown = captureThrow(()=>schema.parse('x', context));
+            expect(thrown.threw).toBe(true);
+            expect(thrown.value).toMatchObject({
+                issues: [
+                    {
+                        message: 'Schema validation failed'
+                    }
+                ]
+            });
+        });
+    });
+});
+describe('guardFactory()', ()=>{
+    let context;
+    beforeAll(()=>{
+        context = createSchemaContext();
+    });
+    beforeEach(()=>{
+        context = createSchemaContext();
+    });
+    afterEach(()=>{
+        vi.clearAllMocks();
+    });
+    afterAll(()=>{
+        vi.restoreAllMocks();
+    });
+    describe('happy', ()=>{
+        it('should return input value when guard accepts input', ()=>{
+            const schema = guardFactory({
+                name: 'GuardedString',
+                type: 'string',
+                guard: (input)=>'string' == typeof input,
+                message: 'Expected string',
+                code: 'string.type'
+            });
+            const parsed = schema.parse('ok', context);
+            expect(parsed).toBe('ok');
+            expect(schema.ast().type).toBe('string');
+        });
+    });
+    describe('sad', ()=>{
+        it('should throw schema validation error when guard rejects input', ()=>{
+            const schema = guardFactory({
+                name: 'GuardedString',
+                type: 'string',
+                guard: (input)=>'string' == typeof input,
+                message: 'Expected string',
+                code: 'string.type'
+            });
+            const thrown = captureThrow(()=>schema.parse(1, context));
+            expect(thrown.threw).toBe(true);
+            expect(thrown.value).toMatchObject({
+                issues: [
+                    {
+                        message: 'Expected string',
+                        code: 'string.type'
+                    }
+                ]
+            });
+        });
+    });
+});