@livon/schema 0.27.0-rc.1

package/dist/api.spec.js

@@ -0,0 +1,506 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { api, composeApi, subscription } from "./api.js";
+import { fieldOperation, operation } from "./operation.js";
+import { createBaseSchemaMock } from "./testing/mocks/index.js";
+describe('api utilities', ()=>{
+    beforeAll(()=>{
+        vi.useRealTimers();
+    });
+    beforeEach(()=>{
+        vi.clearAllMocks();
+    });
+    afterEach(()=>{
+        vi.clearAllMocks();
+    });
+    afterAll(()=>{
+        vi.restoreAllMocks();
+    });
+    describe("subscription()", ()=>{
+        describe('happy', ()=>{
+            it('should include optional fields when optional values are provided', ()=>{
+                const payload = createBaseSchemaMock({
+                    name: 'Payload',
+                    type: 'payload'
+                });
+                const input = createBaseSchemaMock({
+                    name: 'Input',
+                    type: 'input'
+                });
+                const output = createBaseSchemaMock({
+                    name: 'Output',
+                    type: 'output'
+                });
+                const filter = vi.fn(()=>true);
+                const exec = vi.fn(()=>({
+                        event: 'created'
+                    }));
+                const result = subscription({
+                    name: 'userCreated',
+                    input,
+                    payload,
+                    output,
+                    filter,
+                    exec,
+                    doc: {
+                        summary: "subscription doc"
+                    }
+                });
+                expect(result.type).toBe("subscription");
+                expect(result.name).toBe('userCreated');
+                expect(result.input).toBe(input);
+                expect(result.payload).toBe(payload);
+                expect(result.output).toBe(output);
+                expect(result.filter).toBe(filter);
+                expect(result.exec).toBe(exec);
+                expect(result.doc).toEqual({
+                    summary: "subscription doc"
+                });
+            });
+        });
+        describe('sad', ()=>{
+            it('should only include mandatory payload when optional values are omitted', ()=>{
+                const payload = createBaseSchemaMock({
+                    name: 'Payload',
+                    type: 'payload'
+                });
+                const result = subscription({
+                    payload
+                });
+                expect(result.type).toBe("subscription");
+                expect(result.payload).toBe(payload);
+                expect(result.input).toBeUndefined();
+                expect(result.output).toBeUndefined();
+                expect(result.filter).toBeUndefined();
+                expect(result.exec).toBeUndefined();
+            });
+        });
+    });
+    describe('api()', ()=>{
+        describe('happy', ()=>{
+            it('should merge explicit and inline operations when both are provided', ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    name: 'Input',
+                    type: 'input',
+                    outputValue: 'x'
+                });
+                const explicitOperation = operation({
+                    input: inputSchema,
+                    exec: async ()=>'explicit'
+                });
+                const inlineOperation = operation({
+                    input: inputSchema,
+                    exec: async ()=>'inline'
+                });
+                const result = api({
+                    operations: {
+                        explicit: explicitOperation
+                    },
+                    inline: inlineOperation
+                });
+                const operations = result.operations;
+                expect(operations.explicit?.name).toBe('explicit');
+                expect(operations.explicit?.exec).toBe(explicitOperation.exec);
+                expect(operations.inline?.name).toBe('inline');
+                expect(operations.inline?.exec).toBe(inlineOperation.exec);
+            });
+            it("should assign missing names to operations field operations and subscriptions", ()=>{
+                const entity = createBaseSchemaMock({
+                    name: 'User',
+                    type: 'object',
+                    astNode: {
+                        type: 'object',
+                        name: 'User'
+                    },
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const inputSchema = createBaseSchemaMock({
+                    name: 'Input',
+                    type: 'input',
+                    outputValue: 'x'
+                });
+                const payloadSchema = createBaseSchemaMock({
+                    name: 'Payload',
+                    type: 'payload'
+                });
+                const op = operation({
+                    input: inputSchema,
+                    exec: async ()=>'ok'
+                });
+                const fieldOp = fieldOperation({
+                    dependsOn: entity,
+                    exec: async ()=>'field'
+                });
+                const sub = subscription({
+                    payload: payloadSchema
+                });
+                const result = api({
+                    type: entity,
+                    operations: {
+                        createUser: op
+                    },
+                    fieldOperations: {
+                        displayName: fieldOp
+                    },
+                    subscriptions: {
+                        userCreated: sub
+                    }
+                });
+                expect(result.operations.createUser.name).toBe('createUser');
+                expect(result.fieldOperations.displayName.name).toBe('displayName');
+                expect(result.subscriptions.userCreated?.name).toBe('userCreated');
+            });
+            it("should build ast with operation subscription and field nodes when ast is requested", ()=>{
+                const entity = createBaseSchemaMock({
+                    name: 'User',
+                    type: 'object',
+                    astNode: {
+                        type: 'object',
+                        name: 'User'
+                    },
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const operationInput = createBaseSchemaMock({
+                    name: 'OperationInput',
+                    type: 'operation-input',
+                    astNode: {
+                        type: 'object',
+                        name: 'OperationInput'
+                    },
+                    outputValue: {
+                        name: 'Alice'
+                    }
+                });
+                const operationOutput = createBaseSchemaMock({
+                    name: 'OperationOutput',
+                    type: 'operation-output',
+                    astNode: {
+                        type: 'object',
+                        name: 'OperationOutput'
+                    },
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const subscriptionPayload = createBaseSchemaMock({
+                    name: "SubscriptionPayload",
+                    type: "subscription-payload",
+                    astNode: {
+                        type: 'object',
+                        name: "SubscriptionPayload"
+                    }
+                });
+                const fieldInput = createBaseSchemaMock({
+                    name: 'FieldInput',
+                    type: 'field-input',
+                    astNode: {
+                        type: 'object',
+                        name: 'FieldInput'
+                    },
+                    outputValue: {
+                        locale: 'en'
+                    }
+                });
+                const fieldOutput = createBaseSchemaMock({
+                    name: 'FieldOutput',
+                    type: 'field-output',
+                    astNode: {
+                        type: 'object',
+                        name: 'FieldOutput'
+                    },
+                    outputValue: {
+                        value: 'Alice'
+                    }
+                });
+                const createUser = operation({
+                    input: operationInput,
+                    output: operationOutput,
+                    exec: async ()=>({
+                            id: 'u-1'
+                        }),
+                    publish: {
+                        userCreated: ()=>({
+                                id: 'u-1'
+                            })
+                    },
+                    ack: {
+                        required: true,
+                        mode: 'handled'
+                    },
+                    doc: {
+                        summary: 'create user'
+                    }
+                });
+                const displayName = fieldOperation({
+                    dependsOn: entity,
+                    input: fieldInput,
+                    output: fieldOutput,
+                    exec: async ()=>({
+                            value: 'Alice'
+                        }),
+                    doc: {
+                        summary: 'field doc'
+                    }
+                });
+                const userCreated = subscription({
+                    payload: subscriptionPayload,
+                    doc: {
+                        summary: 'sub doc'
+                    }
+                });
+                const result = api({
+                    doc: {
+                        summary: 'api doc'
+                    },
+                    type: entity,
+                    operations: {
+                        createUser
+                    },
+                    fieldOperations: {
+                        displayName
+                    },
+                    subscriptions: {
+                        userCreated
+                    }
+                });
+                const ast = result.ast();
+                const operationNode = ast.children?.find((node)=>'operation' === node.type);
+                const subscriptionNode = ast.children?.find((node)=>"subscription" === node.type);
+                const fieldNode = ast.children?.find((node)=>'field' === node.type);
+                expect(ast.type).toBe('api');
+                expect(ast.doc).toEqual({
+                    summary: 'api doc'
+                });
+                expect(operationNode).toMatchObject({
+                    name: 'createUser',
+                    constraints: {
+                        publish: [
+                            'userCreated'
+                        ],
+                        ack: {
+                            required: true,
+                            mode: 'handled'
+                        },
+                        request: 'OperationInput',
+                        response: 'OperationOutput'
+                    }
+                });
+                expect(subscriptionNode).toMatchObject({
+                    name: 'userCreated',
+                    constraints: {
+                        payload: "SubscriptionPayload",
+                        output: "SubscriptionPayload"
+                    }
+                });
+                expect(fieldNode).toMatchObject({
+                    name: 'User.displayName',
+                    constraints: {
+                        owner: 'User',
+                        field: 'displayName',
+                        request: 'FieldInput',
+                        response: 'FieldOutput',
+                        dependsOn: 'User'
+                    }
+                });
+            });
+        });
+        describe('sad', ()=>{
+            it('should throw when field operations are provided without entity type', ()=>{
+                const fieldOp = fieldOperation({
+                    dependsOn: createBaseSchemaMock({
+                        outputValue: {
+                            id: 'u-1'
+                        }
+                    }),
+                    exec: async ()=>'field'
+                });
+                expect(()=>api({
+                        fieldOperations: {
+                            displayName: fieldOp
+                        }
+                    })).toThrowError('api.type is required when fieldOperations are provided.');
+            });
+            it("should throw when operation publishes topic without matching subscription", ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'x'
+                });
+                const publishingOperation = operation({
+                    input: inputSchema,
+                    exec: async ()=>'ok',
+                    publish: {
+                        missingTopic: ()=>({
+                                payload: true
+                            })
+                    }
+                });
+                expect(()=>api({
+                        operations: {
+                            createUser: publishingOperation
+                        }
+                    })).toThrowError('api: operation "createUser" publishes "missingTopic" but no subscription with that name exists.');
+            });
+        });
+    });
+    describe('composeApi()', ()=>{
+        describe('happy', ()=>{
+            it("should compose operations field operations and subscriptions from multiple apis", ()=>{
+                const userSchema = createBaseSchemaMock({
+                    name: 'User',
+                    type: 'object',
+                    astNode: {
+                        type: 'object',
+                        name: 'User'
+                    },
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'x'
+                });
+                const payloadSchema = createBaseSchemaMock({
+                    name: 'Payload',
+                    type: 'payload'
+                });
+                const usersApi = api({
+                    type: userSchema,
+                    operations: {
+                        createUser: operation({
+                            input: inputSchema,
+                            exec: async ()=>'ok'
+                        })
+                    },
+                    fieldOperations: {
+                        displayName: fieldOperation({
+                            dependsOn: userSchema,
+                            exec: async ()=>'name'
+                        })
+                    },
+                    subscriptions: {
+                        userCreated: subscription({
+                            payload: payloadSchema
+                        })
+                    }
+                });
+                const systemApi = api({
+                    operations: {
+                        health: operation({
+                            input: inputSchema,
+                            exec: async ()=>'ok'
+                        })
+                    }
+                });
+                const composed = composeApi({
+                    users: usersApi,
+                    system: systemApi
+                });
+                const ast = composed.ast();
+                expect(composed.type).toBe('api-composed');
+                expect(Object.keys(composed.operations)).toEqual([
+                    'createUser',
+                    'health'
+                ]);
+                expect(Object.keys(composed.fieldOperations)).toEqual([
+                    'User.displayName'
+                ]);
+                expect(Object.keys(composed.subscriptions)).toEqual([
+                    'userCreated'
+                ]);
+                expect(ast.type).toBe('api-composed');
+                expect(ast.children?.map((node)=>node.name)).toEqual([
+                    'users',
+                    'system'
+                ]);
+            });
+        });
+        describe('sad', ()=>{
+            it('should throw when two apis contain duplicate operation names', ()=>{
+                const inputSchema = createBaseSchemaMock({
+                    outputValue: 'x'
+                });
+                const left = api({
+                    operations: {
+                        ping: operation({
+                            input: inputSchema,
+                            exec: async ()=>'left'
+                        })
+                    }
+                });
+                const right = api({
+                    operations: {
+                        ping: operation({
+                            input: inputSchema,
+                            exec: async ()=>'right'
+                        })
+                    }
+                });
+                expect(()=>composeApi({
+                        left,
+                        right
+                    })).toThrowError('composeApi: duplicate operation name "ping"');
+            });
+            it('should throw when two apis contain duplicate field operation names', ()=>{
+                const owner = createBaseSchemaMock({
+                    name: 'User',
+                    type: 'object',
+                    astNode: {
+                        type: 'object',
+                        name: 'User'
+                    },
+                    outputValue: {
+                        id: 'u-1'
+                    }
+                });
+                const left = api({
+                    type: owner,
+                    fieldOperations: {
+                        displayName: fieldOperation({
+                            dependsOn: owner,
+                            exec: async ()=>'left'
+                        })
+                    }
+                });
+                const right = api({
+                    type: owner,
+                    fieldOperations: {
+                        displayName: fieldOperation({
+                            dependsOn: owner,
+                            exec: async ()=>'right'
+                        })
+                    }
+                });
+                expect(()=>composeApi({
+                        left,
+                        right
+                    })).toThrowError('composeApi: duplicate field operation name "User.displayName"');
+            });
+            it("should throw when two apis contain duplicate subscription names", ()=>{
+                const payload = createBaseSchemaMock({
+                    name: 'Payload',
+                    type: 'payload'
+                });
+                const left = api({
+                    subscriptions: {
+                        userCreated: subscription({
+                            payload
+                        })
+                    }
+                });
+                const right = api({
+                    subscriptions: {
+                        userCreated: subscription({
+                            payload
+                        })
+                    }
+                });
+                expect(()=>composeApi({
+                        left,
+                        right
+                    })).toThrowError('composeApi: duplicate subscription name "userCreated"');
+            });
+        });
+    });
+});

package/dist/array.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__, {
+    array: ()=>array
+});
+const external_schemaFactory_cjs_namespaceObject = require("./schemaFactory.cjs");
+const external_typeGuards_cjs_namespaceObject = require("./typeGuards.cjs");
+const array = ({ name, item, doc })=>(0, external_schemaFactory_cjs_namespaceObject.schemaFactory)({
+        name,
+        type: `array<${item.name}>`,
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'array',
+                name,
+                children: [
+                    item.ast(build ?? void 0)
+                ]
+            };
+        },
+        validate: (input, ctx)=>{
+            if (!(0, external_typeGuards_cjs_namespaceObject.isArray)()(input)) throw {
+                message: 'Expected array',
+                code: 'array.type'
+            };
+            const values = [];
+            input.forEach((value, index)=>{
+                try {
+                    values.push(item.parse(value, ctx));
+                } catch (error) {
+                    throw {
+                        message: `Invalid item at index ${index}`,
+                        code: 'array.item',
+                        context: {
+                            index,
+                            error
+                        }
+                    };
+                }
+            });
+            return values;
+        }
+    });
+exports.array = __webpack_exports__.array;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "array"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/array.d.ts

@@ -0,0 +1,25 @@
+import { Schema, SchemaDoc } from './types.js';
+export interface ArraySchemaInput<T> {
+    name: string;
+    item: Schema<T>;
+    doc?: SchemaDoc;
+}
+/**
+ * array 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/array
+ *
+ * @example
+ * // Creates an array schema that validates string items.
+ * const Tags = array({ name: 'tags', item: string() });
+ * Tags.parse(['typescript', 'schema']);
+ *
+ * @example
+ * // Extends the array schema to also allow undefined.
+ * const OptionalTags = array({ name: 'tags', item: string() }).optional();
+ * OptionalTags.parse(undefined);
+ */
+export declare const array: <T>({ name, item, doc }: ArraySchemaInput<T>) => import("./schemaFactory.js").SchemaWithChain<T[], import("./schemaFactory.js").SchemaFactoryChainDefinition<T[]>>;

package/dist/array.js

@@ -0,0 +1,40 @@
+import { schemaFactory } from "./schemaFactory.js";
+import { isArray } from "./typeGuards.js";
+const array = ({ name, item, doc })=>schemaFactory({
+        name,
+        type: `array<${item.name}>`,
+        doc,
+        ast: (ctx)=>{
+            const build = ctx.getBuildContext();
+            return {
+                type: 'array',
+                name,
+                children: [
+                    item.ast(build ?? void 0)
+                ]
+            };
+        },
+        validate: (input, ctx)=>{
+            if (!isArray()(input)) throw {
+                message: 'Expected array',
+                code: 'array.type'
+            };
+            const values = [];
+            input.forEach((value, index)=>{
+                try {
+                    values.push(item.parse(value, ctx));
+                } catch (error) {
+                    throw {
+                        message: `Invalid item at index ${index}`,
+                        code: 'array.item',
+                        context: {
+                            index,
+                            error
+                        }
+                    };
+                }
+            });
+            return values;
+        }
+    });
+export { array };