@livon/schema 0.27.0-rc.1

package/dist/operation.spec.js

@@ -0,0 +1,448 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createSchemaContext } from "./context.js";
+import { fieldOperation, operation, runFieldOperation, runOperation, withFieldOperationName, withOperationName } from "./operation.js";
+import { string } from "./string.js";
+import { createBaseSchemaMock } from "./testing/mocks/index.js";
+describe('operation utilities', ()=>{
+    let context;
+    beforeAll(()=>{
+        context = createSchemaContext();
+    });
+    beforeEach(()=>{
+        context = createSchemaContext();
+    });
+    afterEach(()=>{
+        vi.clearAllMocks();
+    });
+    afterAll(()=>{
+        vi.restoreAllMocks();
+    });
+    describe('operation()', ()=>{
+        describe('happy', ()=>{
+            it('should return operation payload when output schema is provided', ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    name: 'Input',
+                    type: 'input',
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const outputSchema = createBaseSchemaMock({
+                    name: 'Output',
+                    type: 'output',
+                    outputValue: {
+                        ok: true
+                    }
+                });
+                const exec = vi.fn(async ()=>({
+                        ok: true
+                    }));
+                const result = operation({
+                    input: inputSchema,
+                    output: outputSchema,
+                    exec,
+                    doc: {
+                        summary: 'operation doc'
+                    }
+                });
+                expect(result.type).toBe('operation');
+                expect(result.input).toBe(inputSchema);
+                expect(result.output).toBe(outputSchema);
+                expect(result.exec).toBe(exec);
+                expect(result.doc).toEqual({
+                    summary: 'operation doc'
+                });
+            });
+        });
+        describe('sad', ()=>{
+            it('should keep output undefined when output schema is omitted', ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'input'
+                });
+                const result = operation({
+                    input: inputSchema,
+                    exec: (input)=>input.length
+                });
+                expect(result.output).toBeUndefined();
+            });
+        });
+    });
+    describe('fieldOperation()', ()=>{
+        describe('happy', ()=>{
+            it('should normalize shape dependsOn and shape input when shape values are provided', ()=>{
+                const result = fieldOperation({
+                    dependsOn: {
+                        id: string()
+                    },
+                    input: {
+                        name: string()
+                    },
+                    exec: ()=>'ok'
+                });
+                expect(result.type).toBe('field');
+                expect(result.dependsOn.name).toBe('dependsOn');
+                expect(result.input?.name).toBe('input');
+            });
+            it('should keep provided schema dependsOn without wrapping when schema is provided', ()=>{
+                const dependsOn = createBaseSchemaMock({
+                    name: 'DependsOnSchema',
+                    type: 'dependsOn',
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const result = fieldOperation({
+                    dependsOn,
+                    exec: ()=>'ok'
+                });
+                expect(result.dependsOn).toBe(dependsOn);
+            });
+        });
+        describe('sad', ()=>{
+            it('should keep output undefined when output is omitted', ()=>{
+                const dependsOn = createBaseSchemaMock({
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const result = fieldOperation({
+                    dependsOn,
+                    exec: ()=>'ok'
+                });
+                expect(result.output).toBeUndefined();
+            });
+        });
+    });
+    describe('withOperationName()', ()=>{
+        describe('happy', ()=>{
+            it('should set operation name when wrapper is used', ()=>{
+                const op = operation({
+                    input: createBaseSchemaMock({
+                        outputValue: 'value'
+                    }),
+                    exec: ()=>'ok'
+                });
+                const named = withOperationName({
+                    name: 'createUser',
+                    operation: op
+                });
+                expect(named.name).toBe('createUser');
+                expect(named.type).toBe('operation');
+            });
+        });
+        describe('sad', ()=>{
+            it('should preserve original operation members when name is injected', ()=>{
+                const exec = vi.fn(async ()=>'ok');
+                const op = operation({
+                    input: createBaseSchemaMock({
+                        outputValue: 'value'
+                    }),
+                    exec
+                });
+                const named = withOperationName({
+                    name: 'createUser',
+                    operation: op
+                });
+                expect(named.exec).toBe(exec);
+            });
+        });
+    });
+    describe('withFieldOperationName()', ()=>{
+        describe('happy', ()=>{
+            it('should set field operation name when wrapper is used', ()=>{
+                const op = fieldOperation({
+                    dependsOn: createBaseSchemaMock({
+                        outputValue: {
+                            id: 'u-1'
+                        }
+                    }),
+                    exec: ()=>'ok'
+                });
+                const named = withFieldOperationName({
+                    name: 'user.displayName',
+                    operation: op
+                });
+                expect(named.name).toBe('user.displayName');
+                expect(named.type).toBe('field');
+            });
+        });
+        describe('sad', ()=>{
+            it('should preserve original field operation members when name is injected', ()=>{
+                const exec = vi.fn(async ()=>'ok');
+                const dependsOn = createBaseSchemaMock({
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const op = fieldOperation({
+                    dependsOn,
+                    exec
+                });
+                const named = withFieldOperationName({
+                    name: 'user.displayName',
+                    operation: op
+                });
+                expect(named.dependsOn).toBe(dependsOn);
+                expect(named.exec).toBe(exec);
+            });
+        });
+    });
+    describe('runOperation()', ()=>{
+        describe('happy', ()=>{
+            it('should parse input and output and publish to all rooms when publish hook returns payload', async ()=>{
+                const parsedInput = {
+                    id: 'u-1'
+                };
+                const parsedOutput = {
+                    id: 'result'
+                };
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: parsedInput
+                });
+                const outputSchema = createBaseSchemaMock({
+                    outputValue: parsedOutput
+                });
+                const publisher = vi.fn(async ()=>void 0);
+                const publishHook = vi.fn(()=>({
+                        event: 'created'
+                    }));
+                const exec = vi.fn(async ()=>parsedOutput);
+                context = createSchemaContext({
+                    request: {
+                        publisher
+                    }
+                });
+                const op = operation({
+                    input: inputSchema,
+                    output: outputSchema,
+                    publish: {
+                        userCreated: publishHook
+                    },
+                    rooms: ()=>[
+                            'room-a',
+                            'room-b'
+                        ],
+                    ack: {
+                        required: true,
+                        mode: 'handled'
+                    },
+                    exec
+                });
+                const result = await runOperation(op, {
+                    rawInput: true
+                }, context);
+                expect(exec).toHaveBeenCalledWith(parsedInput, context);
+                expect(outputSchema.parse).toHaveBeenCalledWith(parsedOutput, context);
+                expect(publishHook).toHaveBeenCalledWith(parsedOutput, context);
+                expect(publisher).toHaveBeenCalledTimes(2);
+                expect(publisher).toHaveBeenNthCalledWith(1, {
+                    topic: 'userCreated',
+                    payload: {
+                        event: 'created'
+                    },
+                    input: parsedInput,
+                    ack: {
+                        required: true,
+                        mode: 'handled'
+                    },
+                    meta: {
+                        room: 'room-a'
+                    }
+                });
+                expect(publisher).toHaveBeenNthCalledWith(2, {
+                    topic: 'userCreated',
+                    payload: {
+                        event: 'created'
+                    },
+                    input: parsedInput,
+                    ack: {
+                        required: true,
+                        mode: 'handled'
+                    },
+                    meta: {
+                        room: 'room-b'
+                    }
+                });
+                expect(result).toEqual(parsedOutput);
+            });
+            it('should skip publish when request publisher is missing', async ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'parsed-input'
+                });
+                const outputSchema = createBaseSchemaMock({
+                    outputValue: 'parsed-output'
+                });
+                const publishHook = vi.fn(()=>'payload');
+                const exec = vi.fn(async ()=>'result');
+                context = createSchemaContext();
+                const op = operation({
+                    input: inputSchema,
+                    output: outputSchema,
+                    publish: {
+                        topic: publishHook
+                    },
+                    exec
+                });
+                const result = await runOperation(op, 'raw-input', context);
+                expect(result).toBe('parsed-output');
+                expect(publishHook).not.toHaveBeenCalled();
+            });
+        });
+        describe('sad', ()=>{
+            it('should report publish hook errors when publish hook throws', async ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'parsed-input'
+                });
+                const publisher = vi.fn(async ()=>void 0);
+                const publishHookError = new Error('hook failed');
+                const publishHook = vi.fn(()=>{
+                    throw publishHookError;
+                });
+                const onPublishError = vi.fn();
+                const logger = {
+                    error: vi.fn()
+                };
+                context = createSchemaContext({
+                    request: {
+                        publisher,
+                        onPublishError,
+                        logger
+                    }
+                });
+                const op = operation({
+                    input: inputSchema,
+                    exec: async ()=>'output',
+                    publish: {
+                        topic: publishHook
+                    }
+                });
+                await runOperation(op, 'raw-input', context);
+                expect(onPublishError).toHaveBeenCalledWith(publishHookError, {
+                    topic: 'topic',
+                    phase: 'publish-hook'
+                });
+                expect(logger.error).toHaveBeenCalled();
+            });
+            it('should report publisher errors when publisher throws', async ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'parsed-input'
+                });
+                const publisherError = new Error('publisher failed');
+                const publisher = vi.fn(async ()=>{
+                    throw publisherError;
+                });
+                const onPublishError = vi.fn();
+                const logger = {
+                    error: vi.fn()
+                };
+                context = createSchemaContext({
+                    request: {
+                        publisher,
+                        onPublishError,
+                        logger
+                    }
+                });
+                const op = operation({
+                    input: inputSchema,
+                    exec: async ()=>'output',
+                    publish: {
+                        topic: ()=>({
+                                ok: true
+                            })
+                    }
+                });
+                await runOperation(op, 'raw-input', context);
+                expect(onPublishError).toHaveBeenCalledWith(publisherError, {
+                    topic: 'topic',
+                    phase: 'publisher'
+                });
+                expect(logger.error).toHaveBeenCalled();
+            });
+        });
+    });
+    describe('runFieldOperation()', ()=>{
+        describe('happy', ()=>{
+            it('should parse dependsOn and input and output when input and output schemas are provided', async ()=>{
+                const parsedDependsOn = {
+                    id: 'u-1'
+                };
+                const parsedInput = {
+                    field: 'name'
+                };
+                const parsedOutput = {
+                    value: 'Alice'
+                };
+                const dependsOnSchema = createBaseSchemaMock({
+                    outputValue: parsedDependsOn
+                });
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: parsedInput
+                });
+                const outputSchema = createBaseSchemaMock({
+                    outputValue: parsedOutput
+                });
+                const exec = vi.fn(async ()=>({
+                        raw: true
+                    }));
+                const op = fieldOperation({
+                    dependsOn: dependsOnSchema,
+                    input: inputSchema,
+                    output: outputSchema,
+                    exec
+                });
+                const result = await runFieldOperation(op, {
+                    rawDependsOn: true
+                }, {
+                    rawInput: true
+                }, context);
+                expect(dependsOnSchema.parse).toHaveBeenCalledWith({
+                    rawDependsOn: true
+                }, context);
+                expect(inputSchema.parse).toHaveBeenCalledWith({
+                    rawInput: true
+                }, context);
+                expect(exec).toHaveBeenCalledWith(parsedDependsOn, parsedInput, context);
+                expect(outputSchema.parse).toHaveBeenCalledWith({
+                    raw: true
+                }, context);
+                expect(result).toEqual(parsedOutput);
+            });
+            it('should treat second parameter as context when input schema is missing', async ()=>{
+                const parsedDependsOn = {
+                    id: 'u-1'
+                };
+                const dependsOnSchema = createBaseSchemaMock({
+                    outputValue: parsedDependsOn
+                });
+                const exec = vi.fn(async ()=>'resolved');
+                const op = fieldOperation({
+                    dependsOn: dependsOnSchema,
+                    exec
+                });
+                const result = await runFieldOperation(op, {
+                    rawDependsOn: true
+                }, context);
+                expect(exec).toHaveBeenCalledWith(parsedDependsOn, context);
+                expect(result).toBe('resolved');
+            });
+        });
+        describe('sad', ()=>{
+            it('should create request context when context has no request before execution', async ()=>{
+                const dependsOnSchema = createBaseSchemaMock({
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                context = createSchemaContext();
+                const op = fieldOperation({
+                    dependsOn: dependsOnSchema,
+                    exec: async ()=>'ok'
+                });
+                await runFieldOperation(op, {
+                    rawDependsOn: true
+                }, context);
+                expect(context.getRequestContext()).toBeDefined();
+            });
+        });
+    });
+});

package/dist/or.cjs

@@ -0,0 +1,85 @@
+"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__, {
+    or: ()=>or
+});
+const external_schemaFactory_cjs_namespaceObject = require("./schemaFactory.cjs");
+const resolveOrMatch = ({ input, ctx, options, discriminator })=>{
+    if (discriminator) {
+        const selected = discriminator(input, ctx);
+        if (selected) {
+            if (!options.includes(selected)) throw {
+                message: 'Discriminator selected an unknown schema option.',
+                code: 'or.discriminator'
+            };
+            return selected.parse(input, ctx);
+        }
+    }
+    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 or = ({ name, options, discriminator, doc })=>(0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+        name,
+        type: 'or',
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'union',
+                name,
+                children: options.map((option)=>option.ast(build ?? void 0))
+            };
+        },
+        validate: (input, ctx)=>resolveOrMatch({
+                input,
+                ctx,
+                options,
+                discriminator
+            })
+    });
+exports.or = __webpack_exports__.or;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "or"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/or.d.ts

@@ -0,0 +1,37 @@
+import { Schema, SchemaContext, SchemaDoc } from './types.js';
+type AnySchema = Schema<any>;
+export interface OrSchemaDiscriminator<TValues extends readonly AnySchema[]> {
+    (input: unknown, ctx: SchemaContext): TValues[number] | undefined;
+}
+export interface OrSchemaInput<TValues extends readonly AnySchema[]> {
+    name: string;
+    options: TValues;
+    discriminator?: OrSchemaDiscriminator<TValues>;
+    doc?: SchemaDoc;
+}
+/**
+ * or 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/or
+ *
+ * @example
+ * // Creates an or-schema that accepts either string or number identifiers.
+ * const Identifier = or({
+ *   name: 'identifier',
+ *   options: [string(), number()] as const,
+ * });
+ * Identifier.parse('user-1');
+ *
+ * @example
+ * // Extends the or-schema to also allow undefined.
+ * const OptionalIdentifier = or({
+ *   name: 'identifier',
+ *   options: [string(), number()] as const,
+ * }).optional();
+ * OptionalIdentifier.parse(undefined);
+ */
+export declare const or: <TValues extends readonly AnySchema[]>({ name, options, discriminator, doc, }: OrSchemaInput<TValues>) => import("./schemaFactory.js").SchemaWithChain<ReturnType<TValues[number]["parse"]>, import("./schemaFactory.js").SchemaFactoryChainDefinition<ReturnType<TValues[number]["parse"]>>>;
+export {};

package/dist/or.js

@@ -0,0 +1,51 @@
+import { schemaFactory } from "./schemaFactory.js";
+const resolveOrMatch = ({ input, ctx, options, discriminator })=>{
+    if (discriminator) {
+        const selected = discriminator(input, ctx);
+        if (selected) {
+            if (!options.includes(selected)) throw {
+                message: 'Discriminator selected an unknown schema option.',
+                code: 'or.discriminator'
+            };
+            return selected.parse(input, ctx);
+        }
+    }
+    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 or = ({ name, options, discriminator, doc })=>schemaFactory({
+        name,
+        type: 'or',
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'union',
+                name,
+                children: options.map((option)=>option.ast(build ?? void 0))
+            };
+        },
+        validate: (input, ctx)=>resolveOrMatch({
+                input,
+                ctx,
+                options,
+                discriminator
+            })
+    });
+export { or };