valixa 1.0.0-rc.1 → 1.0.0-rc.2

package/README.md

@@ -1,29 +1,31 @@
-# valixa
-
-Framework-independent form state, validation, subscriptions and submission.
-ESM and TypeScript declarations, with no runtime dependencies.
-
-```js
-import { createValixa } from 'valixa';
-
-const form = createValixa({ email: ['', 'required | email'] });
-form.setValue('email', 'user@example.com');
-const result = await form.validate();
-if (result.valid) await form.submit(async data => data.email);
-form.dispose();
-```
-
-Core API: `blueprint`, `createValixa`, `nested`, `collection`, `registerLocale`, `parseRules`, `RuleSyntaxError`,
-`defaultMessages`, `Blueprint`, `ValixaForm`, plus public TypeScript contracts.
-Use `form.state` to read immutable snapshots, `subscribe` / `subscribeField` to
-observe them, and `handleSubmit` for an event callback.
-
-Supported rules: required, email, url, min/max length, minValue/maxValue, same.
-Custom and asynchronous validators are supported with abort signals and stale-result
-protection. Values are acyclic plain data. Existing object/array fields stay atomic;
-explicit `nested` and `collection` constructors opt into typed paths and stable rows.
-Dependency graphs, field scheduling, conditional behaviors, form validation and
-English/Arabic localization are included. Framework bindings remain separate packages.
-See [API.md](API.md) and the [advanced guide](ADVANCED.md) for semantics and examples.
-
-MIT license. This initial version has not been published.
+# valixa
+
+Framework-independent form state, validation, subscriptions and submission.
+ESM and TypeScript declarations, with no runtime dependencies.
+
+```js
+import { createValixa } from 'valixa';
+
+const form = createValixa({ email: ['', 'required | email'] });
+form.setValue('email', 'user@example.com');
+const result = await form.validate();
+if (result.valid) await form.submit(async data => data.email);
+form.dispose();
+```
+
+Core API: `blueprint`, `createValixa`, `nested`, `collection`, `registerLocale`, `parseRules`, `RuleSyntaxError`,
+`defaultMessages`, `Blueprint`, `ValixaForm`, plus public TypeScript contracts.
+Use `form.state` to read immutable snapshots, `subscribe` / `subscribeField` to
+observe them, and `handleSubmit` for an event callback.
+
+Supported rules: required, email, url, min/max length, minValue/maxValue, same.
+Custom and asynchronous validators are supported with abort signals and stale-result
+protection. Values are acyclic plain data. Existing object/array fields stay atomic;
+explicit `nested` and `collection` constructors opt into typed paths and stable rows.
+Dependency graphs, field scheduling, conditional behaviors, form validation and
+English/Arabic localization are included. Framework bindings remain separate packages.
+See [API.md](API.md) and the [advanced guide](ADVANCED.md) for semantics and examples.
+
+MIT license. This 1.0.0-rc.2 candidate includes optional Standard Schema integration
+at `valixa/standard`, supporting Zod, Yup and Valibot without bundled providers.
+Version 1.0.0-rc.1 does not include this subpath. See docs/standard-schema.md in the repository.

package/dist/standard.d.ts

@@ -0,0 +1,44 @@
+import { Blueprint } from './blueprint.js';
+import type { BlueprintInput, FormOptions, InferValues, Validator, ValueInput } from './types.js';
+/** Structural Standard Schema v1 contract. No schema vendor is bundled. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    };
+}
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}
+export type StandardResult<T> = {
+    readonly value: T;
+    readonly issues?: undefined;
+} | {
+    readonly issues: readonly StandardIssue[];
+};
+export type StandardInput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['input'];
+export type StandardOutput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['output'];
+/** Field validation preserves the input value; schema transformations are not stored. */
+export declare function standardValidator<S extends StandardSchemaV1>(schema: S): Validator<StandardInput<S>>;
+/** Map provider paths through the actual blueprint, including literal dotted keys.
+ * Issues inside a collection are aggregated on its collection field. Row forms
+ * can use their own adapter for individual row-field messages.
+ */
+export declare function standardFormValidator<S extends StandardSchemaV1, const B extends BlueprintInput>(schema: S, input: (B | Blueprint<B>) & (ValueInput<InferValues<NoInfer<B>>> extends StandardInput<NoInfer<S>> ? unknown : never)): NonNullable<FormOptions<InferValues<B>>['validateForm']>;
+export declare class StandardSchemaError extends Error {
+    readonly issues: readonly StandardIssue[];
+    constructor(issues: readonly StandardIssue[]);
+}
+/** Explicit typed output parsing for submit/API boundaries, not a form-state mutation. */
+export declare function parseStandard<S extends StandardSchemaV1>(schema: S, value: StandardInput<S>, options?: {
+    readonly signal?: AbortSignal;
+}): Promise<StandardOutput<S>>;
+//# sourceMappingURL=standard.d.ts.map

package/dist/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAElG,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;KACjG,CAAC;CACH;AACD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,EAAE,GAAG,SAAS,CAAC;CACtF;AACD,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,CAAC;AACnI,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,gBAAgB,IAAI,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACtG,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,gBAAgB,IAAI,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AA6BxG,yFAAyF;AACzF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,gBAAgB,EAAE,MAAM,EAAE,CAAC,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAMpG;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,gBAAgB,EAAE,KAAK,CAAC,CAAC,SAAS,cAAc,EAC9F,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC,GACpH,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAiB1D;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;gBAC9B,MAAM,EAAE,SAAS,aAAa,EAAE;CAI7C;AACD,0FAA0F;AAC1F,wBAAsB,aAAa,CAAC,CAAC,SAAS,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAK/K"}

package/dist/standard.js

@@ -0,0 +1,85 @@
+import { blueprint, Blueprint } from './blueprint.js';
+import { copy } from './data.js';
+function assertSchema(schema) {
+    if (schema?.['~standard']?.version !== 1 || typeof schema['~standard'].validate !== 'function')
+        throw new TypeError('Expected a Standard Schema v1 validator');
+}
+function aborted() { const error = new Error('Schema validation aborted'); error.name = 'AbortError'; return error; }
+async function run(schema, value, signal) {
+    if (signal?.aborted)
+        throw aborted();
+    // Providers may cast/mutate input. Never expose a form snapshot or caller-owned data.
+    const input = copy(value);
+    let off = () => { };
+    const cancelled = new Promise((_, reject) => {
+        const abort = () => reject(aborted());
+        signal?.addEventListener('abort', abort, { once: true });
+        off = () => signal?.removeEventListener('abort', abort);
+    });
+    try {
+        const work = Promise.resolve().then(() => {
+            if (signal?.aborted)
+                throw aborted();
+            return schema['~standard'].validate(input);
+        });
+        const result = await Promise.race([work, cancelled]);
+        if (signal?.aborted)
+            throw aborted();
+        if (!result || typeof result !== 'object' || (result.issues !== undefined && (!Array.isArray(result.issues) || result.issues.length === 0)) || (result.issues === undefined && !Object.hasOwn(result, 'value')))
+            throw new TypeError('Invalid Standard Schema result');
+        if (result.issues?.some(issue => !issue || typeof issue.message !== 'string'))
+            throw new TypeError('Invalid Standard Schema issue');
+        return result;
+    }
+    finally {
+        off();
+    }
+}
+/** Field validation preserves the input value; schema transformations are not stored. */
+export function standardValidator(schema) {
+    assertSchema(schema);
+    return async (value, { signal }) => {
+        const result = await run(schema, value, signal);
+        return result.issues?.[0]?.message ?? true;
+    };
+}
+/** Map provider paths through the actual blueprint, including literal dotted keys.
+ * Issues inside a collection are aggregated on its collection field. Row forms
+ * can use their own adapter for individual row-field messages.
+ */
+export function standardFormValidator(schema, input) {
+    assertSchema(schema);
+    const definition = input instanceof Blueprint ? input : blueprint(input);
+    const fields = Object.entries(definition.description.fields);
+    if (fields.some(([name]) => name === '$form'))
+        throw new TypeError('Standard form validation reserves the $form field name');
+    return async (values, { signal }) => {
+        const result = await run(schema, values, signal);
+        const errors = Object.create(null);
+        for (const issue of result.issues ?? []) {
+            const path = issue.path?.map(segment => typeof segment === 'object' && segment !== null ? segment.key : segment);
+            const exact = path && fields.find(([, field]) => field.path.length === path.length && field.path.every((key, i) => key === path[i]));
+            const collection = !exact && path ? fields.find(([name, field]) => Object.hasOwn(definition.collections, name) && field.path.every((key, i) => key === path[i])) : undefined;
+            const name = (exact || collection)?.[0] ?? '$form';
+            (errors[name] ??= []).push(issue.message);
+        }
+        return errors;
+    };
+}
+export class StandardSchemaError extends Error {
+    issues;
+    constructor(issues) {
+        super('Schema validation failed');
+        this.name = 'StandardSchemaError';
+        this.issues = Object.freeze(issues.map(issue => Object.freeze({ message: issue.message, ...(issue.path ? { path: Object.freeze(issue.path.map(part => typeof part === 'object' && part !== null ? Object.freeze({ key: part.key }) : part)) } : {}) })));
+    }
+}
+/** Explicit typed output parsing for submit/API boundaries, not a form-state mutation. */
+export async function parseStandard(schema, value, options = {}) {
+    assertSchema(schema);
+    const result = await run(schema, value, options.signal);
+    if (result.issues)
+        throw new StandardSchemaError(result.issues);
+    return result.value;
+}
+//# sourceMappingURL=standard.js.map

package/dist/standard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.js","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valixa",
-  "version": "1.0.0-rc.1",
+  "version": "1.0.0-rc.2",
   "description": "Headless, framework-independent form state and validation",
   "type": "module",
   "license": "MIT",
@@ -19,6 +19,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./standard": {
+      "types": "./dist/standard.d.ts",
+      "import": "./dist/standard.js"
     }
   },
   "engines": {

package/src/standard.ts

@@ -0,0 +1,97 @@
+import { blueprint, Blueprint } from './blueprint.js';
+import { copy } from './data.js';
+import type { BlueprintInput, FormOptions, InferValues, Validator, ValueInput } from './types.js';
+
+/** Structural Standard Schema v1 contract. No schema vendor is bundled. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: { readonly input: Input; readonly output: Output } | undefined;
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+  };
+}
+export interface StandardIssue {
+  readonly message: string;
+  readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[] | undefined;
+}
+export type StandardResult<T> = { readonly value: T; readonly issues?: undefined } | { readonly issues: readonly StandardIssue[] };
+export type StandardInput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['input'];
+export type StandardOutput<S extends StandardSchemaV1> = NonNullable<S['~standard']['types']>['output'];
+
+function assertSchema(schema: StandardSchemaV1): void {
+  if (schema?.['~standard']?.version !== 1 || typeof schema['~standard'].validate !== 'function') throw new TypeError('Expected a Standard Schema v1 validator');
+}
+function aborted(): Error { const error = new Error('Schema validation aborted'); error.name = 'AbortError'; return error; }
+async function run<S extends StandardSchemaV1>(schema: S, value: unknown, signal?: AbortSignal): Promise<StandardResult<StandardOutput<S>>> {
+  if (signal?.aborted) throw aborted();
+  // Providers may cast/mutate input. Never expose a form snapshot or caller-owned data.
+  const input = copy(value);
+  let off = () => {};
+  const cancelled = new Promise<never>((_, reject) => {
+    const abort = () => reject(aborted());
+    signal?.addEventListener('abort', abort, { once: true });
+    off = () => signal?.removeEventListener('abort', abort);
+  });
+  try {
+    const work = Promise.resolve().then(() => {
+      if (signal?.aborted) throw aborted();
+      return schema['~standard'].validate(input);
+    });
+    const result = await Promise.race([work, cancelled]);
+    if (signal?.aborted) throw aborted();
+    if (!result || typeof result !== 'object' || (result.issues !== undefined && (!Array.isArray(result.issues) || result.issues.length === 0)) || (result.issues === undefined && !Object.hasOwn(result, 'value'))) throw new TypeError('Invalid Standard Schema result');
+    if (result.issues?.some(issue => !issue || typeof issue.message !== 'string')) throw new TypeError('Invalid Standard Schema issue');
+    return result as StandardResult<StandardOutput<S>>;
+  } finally { off(); }
+}
+
+/** Field validation preserves the input value; schema transformations are not stored. */
+export function standardValidator<S extends StandardSchemaV1>(schema: S): Validator<StandardInput<S>> {
+  assertSchema(schema);
+  return async (value, { signal }) => {
+    const result = await run(schema, value, signal);
+    return result.issues?.[0]?.message ?? true;
+  };
+}
+
+/** Map provider paths through the actual blueprint, including literal dotted keys.
+ * Issues inside a collection are aggregated on its collection field. Row forms
+ * can use their own adapter for individual row-field messages.
+ */
+export function standardFormValidator<S extends StandardSchemaV1, const B extends BlueprintInput>(
+  schema: S,
+  input: (B | Blueprint<B>) & (ValueInput<InferValues<NoInfer<B>>> extends StandardInput<NoInfer<S>> ? unknown : never)
+): NonNullable<FormOptions<InferValues<B>>['validateForm']> {
+  assertSchema(schema);
+  const definition = input instanceof Blueprint ? input : blueprint(input);
+  const fields = Object.entries(definition.description.fields);
+  if (fields.some(([name]) => name === '$form')) throw new TypeError('Standard form validation reserves the $form field name');
+  return async (values, { signal }) => {
+    const result = await run(schema, values, signal);
+    const errors: Record<string, string[]> = Object.create(null);
+    for (const issue of result.issues ?? []) {
+      const path = issue.path?.map(segment => typeof segment === 'object' && segment !== null ? segment.key : segment);
+      const exact = path && fields.find(([, field]) => field.path.length === path.length && field.path.every((key, i) => key === path[i]));
+      const collection = !exact && path ? fields.find(([name, field]) => Object.hasOwn(definition.collections, name) && field.path.every((key, i) => key === path[i])) : undefined;
+      const name = (exact || collection)?.[0] ?? '$form';
+      (errors[name] ??= []).push(issue.message);
+    }
+    return errors;
+  };
+}
+
+export class StandardSchemaError extends Error {
+  readonly issues: readonly StandardIssue[];
+  constructor(issues: readonly StandardIssue[]) {
+    super('Schema validation failed'); this.name = 'StandardSchemaError';
+    this.issues = Object.freeze(issues.map(issue => Object.freeze({ message: issue.message, ...(issue.path ? { path: Object.freeze(issue.path.map(part => typeof part === 'object' && part !== null ? Object.freeze({ key: part.key }) : part)) } : {}) })));
+  }
+}
+/** Explicit typed output parsing for submit/API boundaries, not a form-state mutation. */
+export async function parseStandard<S extends StandardSchemaV1>(schema: S, value: StandardInput<S>, options: { readonly signal?: AbortSignal } = {}): Promise<StandardOutput<S>> {
+  assertSchema(schema);
+  const result = await run(schema, value, options.signal);
+  if (result.issues) throw new StandardSchemaError(result.issues);
+  return result.value;
+}