@livon/schema 0.27.0-rc.3 → 0.28.0-rc.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LIVON contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,174 @@
+<!-- Generated from website/docs/packages/*.md. Do not edit directly. -->
+
 # @livon/schema
 
-Package docs (GitHub Pages):
-- https://live-input-vector-output-node.github.io/livon-ts/docs/packages/schema
 
-License:
-- MIT
-- Root license text: `../../LIZENZ.md`
+[![npm](https://img.shields.io/npm/v/%40livon%2Fschema)](https://www.npmjs.com/package/@livon/schema)
+[![dependencies](https://img.shields.io/librariesio/release/npm/%40livon%2Fschema?label=dependencies)](https://libraries.io/npm/%40livon%2Fschema)
+[![code quality](https://img.shields.io/github/actions/workflow/status/live-input-vector-output-node/livon-ts/code-quality.yml?branch=main&label=code%20quality)](https://github.com/live-input-vector-output-node/livon-ts/actions/workflows/code-quality.yml)
+[![package size](https://img.shields.io/npm/unpacked-size/%40livon%2Fschema?label=package%20size)](https://www.npmjs.com/package/@livon/schema)
+[![license](https://img.shields.io/github/license/live-input-vector-output-node/livon-ts)](https://github.com/live-input-vector-output-node/livon-ts)
+
+## Install
+
+```sh
+pnpm add @livon/schema
+```
+
+## Purpose
+
+[@livon/schema](https://livon.tech/docs/packages/schema) defines:
+
+- [value schemas](https://livon.tech/docs/schema) (`string`, `number`, `object`, `array`, `or`, `union`, ...)
+- operation schemas
+- subscription schemas
+- [schema module](https://livon.tech/docs/technical/runtime-design) (`schemaModule`)
+
+## Best for
+
+Use this package when you want a single schema source for validation, typing, and generated client APIs.
+
+## Schema API docs
+
+Each schema/combinator has its own usage page:
+
+- [Schema APIs overview](https://livon.tech/docs/schema)
+- [Schema Type Safety](https://livon.tech/docs/schema/type-safety)
+- [Schema Context](https://livon.tech/docs/schema/context)
+- [string](https://livon.tech/docs/schema/string)
+- [number](https://livon.tech/docs/schema/number)
+- [boolean](https://livon.tech/docs/schema/boolean)
+- [date](https://livon.tech/docs/schema/date)
+- [enumeration](https://livon.tech/docs/schema/enumeration)
+- [object](https://livon.tech/docs/schema/object)
+- [array](https://livon.tech/docs/schema/array)
+- [tuple](https://livon.tech/docs/schema/tuple)
+- [literal](https://livon.tech/docs/schema/literal)
+- [union](https://livon.tech/docs/schema/union)
+- [or](https://livon.tech/docs/schema/or)
+- [binary](https://livon.tech/docs/schema/binary)
+- [before](https://livon.tech/docs/schema/before)
+- [after](https://livon.tech/docs/schema/after)
+- [and](https://livon.tech/docs/schema/and)
+- [api](https://livon.tech/docs/schema/api)
+- [operation](https://livon.tech/docs/schema/operation)
+- [subscription](https://livon.tech/docs/schema/subscription)
+- [fieldResolver](https://livon.tech/docs/schema/field-resolver)
+- [schemaFactory](https://livon.tech/docs/schema/schema-factory)
+- [typeGuards](https://livon.tech/docs/schema/type-guards)
+
+## Type safety model
+
+LIVON [schemas](https://livon.tech/docs/schema) are both runtime validators and type sources.
+Primitive schema names are optional, so `string()` and `number()` are valid defaults.
+
+1. Define payload shape once in [schema](https://livon.tech/docs/schema).
+2. Validate unknown input with `parse()`.
+3. Reuse schema entrypoint with `typed()`.
+4. Derive types with `Infer` instead of hand-written payload interfaces.
+
+```ts
+import {object, string, number, type Infer} from '@livon/schema';
+
+const User = object({
+  name: 'User',
+  shape: {
+    id: string(),
+    age: number().int().min(0),
+  },
+});
+
+type UserType = Infer<typeof User>;
+
+const input: unknown = JSON.parse(raw);
+const parsed = User.parse(input);
+const typedInput: UserType = {id: 'u-1', age: 21};
+const typed = User.typed(typedInput);
+```
+
+### Parameters in this example
+
+`object({...})`:
+
+- `name` (`string`): schema node name.
+- `shape` (`Record<string, Schema>`): field schema map.
+
+`number().int().min(0)`:
+
+- `min` (`number`): minimum allowed numeric value.
+
+`User.parse(input)`:
+
+- `input` (`unknown`): runtime value to validate/parse.
+
+`User.typed(typedInput)`:
+
+- `typedInput` (`UserType`): pretyped value using same schema entrypoint.
+
+## Compose API schema
+
+```ts
+import {api} from '@livon/schema';
+
+const ApiSchema = api({
+  type: User,
+  operations: {
+    sendMessage,
+  },
+  subscriptions: {
+    onMessage,
+  },
+  fieldOperations: {
+    greeting: userGreetingResolver,
+  },
+});
+
+export const serverSchema = ApiSchema;
+```
+
+Use the `api(...)` (or `composeApi(...)`) result directly in `schemaModule(...)`.
+No additional schema-module input factory is required.
+
+### Parameters in this example
+
+`api({...})`:
+
+- `type` (`Schema`, optional): entity schema for field operations.
+- `operations` (`Record<string, Operation>`, optional): request/response operations.
+- `subscriptions` (`Record<string, Subscription | Schema>`, optional): publish topic schemas.
+- `fieldOperations` (`Record<string, FieldOperation>`, optional): field-level resolvers.
+
+For focused usage patterns:
+
+- [api](https://livon.tech/docs/schema/api)
+- [operation](https://livon.tech/docs/schema/operation)
+- [subscription](https://livon.tech/docs/schema/subscription)
+- [fieldResolver](https://livon.tech/docs/schema/field-resolver)
+
+## Mount schema module into runtime
+
+```ts
+import {runtime} from '@livon/runtime';
+import {schemaModule} from '@livon/schema';
+
+runtime(schemaModule(serverSchema, {explain: true}));
+```
+
+### Parameters in this example
+
+`schemaModule(serverSchema, options?)`:
+
+- `serverSchema` (`Api | ComposedApi`): fully composed schema from `api(...)` or `composeApi(...)`.
+- `options.explain` (`boolean`, optional): enables `$explain` endpoint for AST/checksum metadata.
+
+## Explain endpoint
+
+If `explain: true`, [schema module](https://livon.tech/docs/technical/runtime-design) responds to `$explain` with AST/checksum metadata.
+
+## Related pages
+
+- [Validated by Default](https://livon.tech/docs/core/validated-by-default)
+- [parse vs typed](https://livon.tech/docs/core/parse-vs-typed)
+- [Schema APIs overview](https://livon.tech/docs/schema)
+- [Runtime Design](https://livon.tech/docs/technical/runtime-design)
+- [Architecture](https://livon.tech/docs/technical/architecture)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+Third-Party Notices
+
+This package includes third-party software. The following licenses apply:
+
+------------------------------------------------------------------------------
+msgpackr
+------------------------------------------------------------------------------
+License: MIT
+
+Copyright (c) 2020 Kris Zyp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/SchemaValidationError.cjs

@@ -1 +1,41 @@
-"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,r)=>{for(var _ in r)__webpack_require__.o(r,_)&&!__webpack_require__.o(e,_)&&Object.defineProperty(e,_,{enumerable:!0,get:r[_]})},__webpack_require__.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{createSchemaValidationError:()=>createSchemaValidationError});const createSchemaValidationError=({issues:e,meta:r})=>{let _=Error("Schema validation failed");return _.issues=e,_.meta=r,_};for(var __rspack_i in exports.createSchemaValidationError=__webpack_exports__.createSchemaValidationError,__webpack_exports__)-1===["createSchemaValidationError"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"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__, {
+    createSchemaValidationError: ()=>createSchemaValidationError
+});
+const createSchemaValidationError = ({ issues, meta })=>{
+    const error = new Error('Schema validation failed');
+    error.issues = issues;
+    error.meta = meta;
+    return error;
+};
+exports.createSchemaValidationError = __webpack_exports__.createSchemaValidationError;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createSchemaValidationError"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/SchemaValidationError.d.ts

@@ -9,7 +9,7 @@ export type SchemaValidationError = Error & {
  * @remarks
  * Parameter and return types are defined in the TypeScript signature.
  *
- * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/type-safety
+ * @see https://livon.tech/docs/schema/type-safety
  *
  * @example
  * const result = createSchemaValidationError(undefined as never);

package/dist/SchemaValidationError.js

@@ -1 +1,7 @@
-let e=({issues:e,meta:r})=>{let a=Error("Schema validation failed");return a.issues=e,a.meta=r,a};export{e as createSchemaValidationError};
+const createSchemaValidationError = ({ issues, meta })=>{
+    const error = new Error('Schema validation failed');
+    error.issues = issues;
+    error.meta = meta;
+    return error;
+};
+export { createSchemaValidationError };

package/dist/after.cjs

@@ -1 +1,36 @@
-"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,_)=>{for(var r in _)__webpack_require__.o(_,r)&&!__webpack_require__.o(e,r)&&Object.defineProperty(e,r,{enumerable:!0,get:_[r]})},__webpack_require__.o=(e,_)=>Object.prototype.hasOwnProperty.call(e,_),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{after:()=>after});const after=({schema:e,hook:_})=>e.after(_);for(var __rspack_i in exports.after=__webpack_exports__.after,__webpack_exports__)-1===["after"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"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__, {
+    after: ()=>after
+});
+const after = ({ schema, hook })=>schema.after(hook);
+exports.after = __webpack_exports__.after;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "after"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/after.d.ts

@@ -9,7 +9,7 @@ export interface AfterInput<T> {
  * @remarks
  * Parameter and return types are defined in the TypeScript signature.
  *
- * @see https://live-input-vector-output-node.github.io/livon-ts/docs/schema/after
+ * @see https://livon.tech/docs/schema/after
  *
  * @example
  * // Postprocesses validated string output by converting it to uppercase.

package/dist/after.js

@@ -1 +1,2 @@
-let e=({schema:e,hook:t})=>e.after(t);export{e as after};
+const after = ({ schema, hook })=>schema.after(hook);
+export { after };

package/dist/and.cjs

@@ -1 +1,59 @@
-"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(_,e)=>{for(var r in e)__webpack_require__.o(e,r)&&!__webpack_require__.o(_,r)&&Object.defineProperty(_,r,{enumerable:!0,get:e[r]})},__webpack_require__.o=(_,e)=>Object.prototype.hasOwnProperty.call(_,e),__webpack_require__.r=_=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(_,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(_,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{and:()=>and});const and=({left:_,right:e})=>_.and(e);for(var __rspack_i in exports.and=__webpack_exports__.and,__webpack_exports__)-1===["and"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});
+"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__, {
+    and: ()=>and
+});
+const isLegacyInput = (input)=>'left' in input && 'right' in input;
+function and(input) {
+    if (isLegacyInput(input)) {
+        const { left, right, name } = input;
+        return void 0 === name ? left.and(right) : left.and(right, {
+            name
+        });
+    }
+    const { schemas, name } = input;
+    if (schemas.length < 2) throw new Error('and() requires at least 2 schemas in the schemas array');
+    const [first, ...rest] = schemas;
+    const initial = first;
+    const lastIndex = rest.length - 1;
+    const reduced = rest.reduce((state, schema)=>({
+            schema: void 0 !== name && state.index === lastIndex ? state.schema.and(schema, {
+                name
+            }) : state.schema.and(schema),
+            index: state.index + 1
+        }), {
+        schema: initial,
+        index: 0
+    });
+    return reduced.schema;
+}
+exports.and = __webpack_exports__.and;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "and"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/and.d.ts

@@ -1,26 +1,63 @@
 import { Schema } from './types.js';
-export interface AndInput<T, U> {
+type InferSchemasTuple<T extends readonly Schema<unknown>[]> = {
+    [K in keyof T]: T[K] extends Schema<infer U> ? U : never;
+};
+type IntersectTuple<T extends readonly unknown[]> = T extends readonly [infer Head, ...infer Tail] ? Head & IntersectTuple<Tail> : unknown;
+export interface AndSchemaInput<TSchemas extends readonly Schema<unknown>[]> {
+    name?: string;
+    schemas: TSchemas;
+}
+export interface AndLegacyInput<T, U> {
     left: Schema<T>;
     right: Schema<U>;
+    name?: string;
 }
+type VariadicSchemaTuple = readonly [Schema<any>, Schema<any>, ...Schema<any>[]];
 /**
  * and 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/and
+ * @see https://livon.tech/docs/schema/and
+ *
+ * @example
+ * // Extends a base message input schema with an id field (legacy API).
+ * const messageInput = object({
+ *   name: 'MessageInput',
+ *   shape: { text: string() },
+ * });
+ * const withId = object({
+ *   name: 'WithId',
+ *   shape: { id: string() },
+ * });
+ * const MessageWithId = and({ left: messageInput, right: withId });
+ * MessageWithId.parse({ text: 'Hello', id: 'm-1' });
+ *
+ * @example
+ * // Uses explicit naming for generated type surfaces (legacy API).
+ * const MessageWithId = and({
+ *   left: messageInput,
+ *   right: withId,
+ *   name: 'MessageWithId',
+ * });
+ * MessageWithId.parse({ text: 'Hello', id: 'm-1' });
  *
  * @example
- * // Combines two object schemas into one schema that requires both shapes.
- * const WithId = object({ name: 'withId', shape: { id: string() } });
- * const WithAge = object({ name: 'withAge', shape: { age: number() } });
- * const User = and({ left: WithId, right: WithAge });
- * User.parse({ id: 'u1', age: 21 });
+ * // Composes multiple schemas using the schemas array (new API).
+ * const MessageWithId = and({
+ *   name: 'MessageWithId',
+ *   schemas: [messageInput, withId],
+ * });
+ * MessageWithId.parse({ text: 'Hello', id: 'm-1' });
  *
  * @example
- * // Extends the combined schema to also allow undefined.
- * const OptionalUser = and({ left: WithId, right: WithAge }).optional();
- * OptionalUser.parse(undefined);
+ * // Composes three schemas using the schemas array.
+ * const MessageComplete = and({
+ *   schemas: [messageInput, withId, withTimestamp],
+ * });
+ * MessageComplete.parse({ text: 'Hello', id: 'm-1', timestamp: Date.now() });
  */
-export declare const and: <T, U>({ left, right }: AndInput<T, U>) => Schema<T & U>;
+export declare function and<TSchemas extends VariadicSchemaTuple>(input: AndSchemaInput<TSchemas>): Schema<IntersectTuple<InferSchemasTuple<TSchemas>>>;
+export declare function and<T, U>(input: AndLegacyInput<T, U>): Schema<T & U>;
+export {};

package/dist/and.js

@@ -1 +1,25 @@
-let a=({left:a,right:d})=>a.and(d);export{a as and};
+const isLegacyInput = (input)=>'left' in input && 'right' in input;
+function and(input) {
+    if (isLegacyInput(input)) {
+        const { left, right, name } = input;
+        return void 0 === name ? left.and(right) : left.and(right, {
+            name
+        });
+    }
+    const { schemas, name } = input;
+    if (schemas.length < 2) throw new Error('and() requires at least 2 schemas in the schemas array');
+    const [first, ...rest] = schemas;
+    const initial = first;
+    const lastIndex = rest.length - 1;
+    const reduced = rest.reduce((state, schema)=>({
+            schema: void 0 !== name && state.index === lastIndex ? state.schema.and(schema, {
+                name
+            }) : state.schema.and(schema),
+            index: state.index + 1
+        }), {
+        schema: initial,
+        index: 0
+    });
+    return reduced.schema;
+}
+export { and };