Add Standard Schema validator integration

Introduce support for Standard Schema v1 validators across the project. Adds a new standard-schema module that detects ~standard validators, converts optional JSON Schema output into Async DB field metadata, merges overlays, and produces diagnostics. Runtime validators now support async validators via validateAsync/assertAsync; sync helpers throw DB_SCHEMA_ASYNC_VALIDATOR_REQUIRED when an async validator is encountered. Builder and schema generation were updated to accept validator-first shorthand and optionally emit validator-first .schema.mjs output (controlled by schema.standardSchema config). CLI bundling/unbundling, root bundle generation, and diagnostics were adjusted to import/reference executable validators and preserve behavior. Documentation and a runnable examples/standard-schema were added, plus corresponding type updates and tests.

Author: PatrickJS

README.md

@@ -48,6 +48,7 @@ Other useful paths:
 - [`examples/computed-fields`](./examples/computed-fields): computed field patterns across several schema-backed models.
 - [`examples/rest-client`](./examples/rest-client): calling @async/db from app or test code.
 - [`examples/schema-manifest`](./examples/schema-manifest): schema metadata for admin/CMS UI.
+- [`examples/standard-schema`](./examples/standard-schema): Standard Schema validators with Async DB metadata overlays.
 - [`examples/hono-auth`](./examples/hono-auth): optional Hono auth and write hooks.
 
 See [Which Example Should I Start With?](#which-example-should-i-start-with) for the full examples map.
@@ -200,6 +201,22 @@ In mixed mode, schema files define the contract and data files provide seed reco
 
 Schema defaults fill omitted fields on create and safe additive runtime hydration. Updates, patches, and document puts preserve omitted fields; include a field in the write body when you want to change it.
 
+Executable `.schema.mjs` files can also accept Standard Schema-compatible validators:
+
+```js
+import { collection, field } from '@async/db/schema';
+
+export default collection({
+  validator: UserSchema,
+  fields: {
+    email: field.string({ required: true, unique: true }),
+    displayName: field.computed(field.string(), ({ record }) => record.email),
+  },
+});
+```
+
+The validator owns runtime parsing through `~standard.validate`; Async DB overlays keep generated metadata, relations, defaults, and computed resolvers. Async validators run in package, REST, and GraphQL writes. Sync schema helpers throw `DB_SCHEMA_ASYNC_VALIDATOR_REQUIRED` when the validator returns a Promise; use `validateAsync()` or `assertAsync()` for that path.
+
 See [docs/concepts.md](./docs/concepts.md) and [docs/fixtures-and-schemas.md](./docs/fixtures-and-schemas.md).
 
 ## Validate Or Resolve From Schema
@@ -393,6 +410,7 @@ The examples are a learning path. Run any example with `node ./src/cli.js sync -
 | CSV as the source of truth | [`examples/csv`](./examples/csv) | CSV inference, source hashes, mirror refreshes |
 | Admin/CMS-style field metadata | [`examples/schema-manifest`](./examples/schema-manifest) | `outputs.schemaManifest` and manifest customization |
 | Schema JSON to simple CMS UI templates | [`examples/schema-ui`](./examples/schema-ui) | `serve.mjs` SSR view/editor HTML from manifest + mirror (`node ./examples/schema-ui/serve.mjs`); `/templates` route keeps static placeholders |
+| Standard Schema validators | [`examples/standard-schema`](./examples/standard-schema) | Dependency-free Standard Schema validation, `field.meta(...)` overlays, async write validation, computed fields, and conservative type fallback |
 | Diagnostics for schema/data drift | [`examples/diagnostics`](./examples/diagnostics) | Warnings surfaced without breaking unrelated resources |
 | Several advanced features together | [`examples/advanced`](./examples/advanced) | `.schema.mjs`, mixed mode, defaults, nested objects |
 | Hono auth and write hooks | [`examples/hono-auth`](./examples/hono-auth) | Optional Hono integration with auth lifecycle hooks |

docs/README.md

@@ -10,7 +10,7 @@ This folder is the durable markdown manual for @async/db. The root [README](../R
 
 ## Build Local Data
 
-- [Fixtures And Schemas](./fixtures-and-schemas.md): JSON, JSONC, CSV, schema files, `.schema.mjs`, computed fields, source readers, nested folders, inference, and validation.
+- [Fixtures And Schemas](./fixtures-and-schemas.md): JSON, JSONC, CSV, schema files, `.schema.mjs`, Standard Schema validators, computed fields, source readers, nested folders, inference, and validation.
 - [Generated Files](./generated-files.md): `.db/`, state, generated TypeScript, committed generated outputs, schema manifests, and cleanup rules.
 - [Configuration](./configuration.md): `db.config.mjs`, fixture folders, resource naming, strictness, registered operations, mock delay/errors, server options, and forks.
 - [Schema UI example](../examples/schema-ui/README.md): manifest-driven CMS HTML with **`serve.mjs`** SSR from live mirror rows (`node ./examples/schema-ui/serve.mjs`).

docs/configuration.md

@@ -38,6 +38,7 @@ See [db.config.example.mjs](../db.config.example.mjs) for a commented config wit
 | App-facing data route base | `/db` | `server.dataPath` |
 | Route exposure policy | Open | `server.expose` |
 | Unknown fields | Warn | `schema.unknownFields` |
+| Standard Schema-first output | Off | `schema.standardSchema` |
 | Schema defaults | Create and safe hydration | `defaults` |
 | Schema-only mock records | Off | `seed.generateFromSchema` |
 | Local latency | `30-100ms` | `mock.delay` |
@@ -81,6 +82,7 @@ export default defineConfig({
   },
 
   schema: {
+    standardSchema: false,
     unknownFields: 'warn',
   },
 
@@ -239,6 +241,28 @@ export default defineConfig({
 
 Keep the default `warn` while fixture shape is still changing.
 
+## Standard Schema Output
+
+@async/db detects Standard Schema validators by shape without installing a
+validator dependency. Set `schema.standardSchema: true` when generated
+`.schema.mjs` files should prefer the validator-first authoring form for
+resources that have a Standard Schema validator:
+
+```js
+import { defineConfig } from '@async/db/config';
+
+export default defineConfig({
+  schema: {
+    standardSchema: true,
+  },
+});
+```
+
+With that option, aggregate bundle/unbundle output can emit
+`collection(UserSchema, { fields })` or `document(SettingsSchema, { fields })`
+for Standard Schema-backed resources. Resources without a validator keep the
+normal Async DB-first shape.
+
 ## Schema Defaults
 
 Schema defaults apply when creating collection records through the package API, REST, GraphQL, SQLite adapter, and generated Hono SQLite starter. Updates, patches, and document puts preserve omitted fields instead of backfilling defaults; include a field in the write body when you want to change it.

docs/fixtures-and-schemas.md

@@ -130,6 +130,112 @@ export default collection({
 
 `.schema.mjs` files execute as trusted local project JavaScript.
 
+## Standard Schema Validators
+
+`.schema.mjs` files can also use any object that implements the Standard Schema
+v1 contract. @async/db imports your trusted schema module, recognizes
+`value['~standard'].version === 1`, and calls
+`value['~standard'].validate(...)` during schema helpers and runtime writes.
+The core package does not bundle a validator-library dependency. That means
+Zod, Valibot, ArkType, or a local validator can own parsing and validation
+while Async DB still applies its own lightweight metadata checks for defaults,
+read-only/computed fields, uniqueness, relations, generated metadata, REST, and
+GraphQL.
+
+```js
+import { collection, field } from '@async/db/schema';
+
+const UserSchema = {
+  '~standard': {
+    version: 1,
+    vendor: 'my-validator',
+    async validate(value) {
+      if (!value || typeof value !== 'object' || typeof value.email !== 'string') {
+        return { issues: [{ message: 'Email is required', path: ['email'] }] };
+      }
+      return {
+        value: {
+          ...value,
+          email: value.email.trim().toLowerCase(),
+        },
+      };
+    },
+    jsonSchema: {
+      output() {
+        return {
+          type: 'object',
+          required: ['email'],
+          properties: {
+            id: { type: 'string' },
+            email: { type: 'string' },
+          },
+        };
+      },
+    },
+  },
+};
+
+export default collection({
+  idField: 'id',
+  validator: UserSchema,
+  fields: {
+    email: field.string({
+      required: true,
+      unique: true,
+      description: 'Normalized login email.',
+    }),
+    displayName: field.computed(field.string(), ({ record }) => record.email),
+  },
+  seed: [],
+});
+```
+
+That object-first form keeps Async DB's simplified schema as the main shape and
+mixes Standard Schema in as the parser/validator through `validator`. The equivalent
+validator-first shorthand is useful when the external validator owns the field
+shape:
+
+```js
+export default collection(UserSchema, {
+  fields: {
+    email: field.meta({ unique: true }),
+    displayName: field.computed(field.string(), ({ record }) => record.email),
+  },
+});
+```
+
+Set `schema.standardSchema: true` in `db.config.mjs` when generated
+`.schema.mjs` files should prefer that validator-first form for resources that
+have a Standard Schema validator. Detection still works without the config flag;
+the flag only changes generated authoring output.
+
+If the validator exposes a Standard JSON Schema converter, @async/db uses that
+for generated field metadata and TypeScript output. `field.meta(...)` overlays
+Async DB metadata such as descriptions, defaults, uniqueness, relations,
+constraints, and manifest hints. `field.computed(...)` remains the resolver
+entrypoint.
+
+Package API, REST, and GraphQL writes await async Standard Schema validators and
+store the returned `value`. Synchronous helpers such as
+`schema.validator('users').assert(...)` work for sync validators; if a validator
+returns a Promise, use `validateAsync(...)` or `assertAsync(...)`. The sync path
+throws `DB_SCHEMA_ASYNC_VALIDATOR_REQUIRED` with that hint.
+
+Standard Schema issues become `STANDARD_SCHEMA_VALIDATION_FAILED` diagnostics
+with a normalized field path, vendor, issue path, message, and recovery hint.
+Validator and resolver functions stay in trusted local code and are never
+serialized into generated schema, manifests, viewer metadata, or TypeScript
+output.
+
+When a Standard Schema validator has no JSON Schema converter and no
+`field.meta(...)` overlays, generated TypeScript uses a conservative
+`[key: string]: unknown` fallback and the project diagnostics include
+`STANDARD_SCHEMA_FIELDS_UNKNOWN`. Add overlays or a converter when generated
+metadata needs to be richer.
+
+See [examples/standard-schema](../examples/standard-schema) for a runnable
+dependency-free example.
+
 ## Root Schema Registry
 
 Use `db.schema.mjs` at the project root when you want one canonical schema registry:
@@ -287,6 +393,9 @@ npm run db -- schema bundle users --out artifacts/users.bundle.schema.json
 npm run db -- schema unbundle users
 ```
 
+These single-resource JSON artifacts serialize Async DB metadata and seed data;
+they do not serialize executable validator or resolver functions.
+
 If you omit the resource in an interactive terminal, the CLI prompts for either
 `All schemas` or a specific resource. Use `--all` in scripts to skip the prompt.
 
@@ -307,11 +416,13 @@ example, `source: files('./**/*.mdx', { read: 'frontmatter' })` inside
 `source: files('./db/blog/**/*.mdx', { read: 'frontmatter' })` in
 `db.schema.mjs`, so the root registry can load the same content files.
 
-When aggregate bundling sees computed resolvers from existing `.schema.mjs`
-files, the generated root schema imports the original module and emits inline
-named wrapper functions to preserve behavior. Schema, manifest, type, doctor,
-bundle, unbundle, and generated starter commands import trusted schema modules
-for metadata but do not call computed resolvers.
+When aggregate bundling sees computed resolvers or Standard Schema validators
+from existing `.schema.mjs` files, the generated root schema imports the
+original module, references its validator, and emits inline named resolver
+wrappers to preserve behavior. Aggregate unbundle writes `.schema.mjs` files for
+resources with executable validators or resolvers. Schema, manifest, type,
+doctor, bundle, unbundle, and generated starter commands import trusted schema
+modules for metadata but do not call computed resolvers.
 
 ## Inference
 

examples/standard-schema/README.md

@@ -0,0 +1,55 @@
+# Standard Schema Example
+
+This example shows the dependency-free integration path for validators that implement the Standard Schema v1 contract. The validator object lives in trusted project code; @async/db imports the schema module, recognizes `~standard.validate`, and calls it during schema helpers and runtime writes without bundling a validator-library dependency.
+
+Run it:
+
+```bash
+node ./src/cli.js sync --cwd ./examples/standard-schema
+node ./src/cli.js serve --cwd ./examples/standard-schema
+```
+
+`db/users.schema.mjs` uses a small local Standard Schema-compatible validator. It lowercases email addresses during writes, exposes a Standard JSON Schema converter for field inference, and then layers Async DB metadata on top.
+
+You can keep Async DB's object-first schema shape and mix the validator in:
+
+```js
+export default collection({
+  validator: UserSchema,
+  fields: {
+    email: field.string({ required: true, unique: true }),
+    displayName: field.computed(field.string(), ({ record }) => record.email),
+  },
+});
+```
+
+The validator-first shorthand is also supported when the external schema owns the field shape:
+
+```js
+export default collection(UserSchema, {
+  idField: 'id',
+  fields: {
+    email: field.meta({ unique: true }),
+    displayName: field.computed(field.string(), {
+      resolveMany({ records }) {
+        return new Map(records.map((record) => [
+          record.id,
+          `${record.firstName} ${record.lastName}`,
+        ]));
+      },
+    }),
+  },
+});
+```
+
+`field.meta(...)` is for Async DB metadata such as `unique`, `description`, defaults, relations, and manifest hints. `field.computed(...)` remains the resolver entrypoint, and resolver functions are not written to generated schema or manifest output.
+
+The validator can be async. Package API, REST, and GraphQL writes await it and store the returned `value`.
+
+```bash
+node ./src/cli.js create users '{"id":"u_2","email":" GRACE@EXAMPLE.COM ","firstName":"Grace","lastName":"Hopper"}' --cwd ./examples/standard-schema
+```
+
+The stored email becomes `grace@example.com`.
+
+`db/settings.schema.mjs` intentionally uses an opaque Standard Schema validator with no JSON Schema converter and no field overlay. In that case generated TypeScript falls back to a conservative index signature, and diagnostics ask you to add `field.meta(...)` overlays or provide a JSON Schema converter when you want richer generated metadata.

examples/standard-schema/db/settings.schema.mjs

@@ -0,0 +1,22 @@
+import { document } from '@async/db/schema';
+
+const SettingsSchema = {
+  '~standard': {
+    version: 1,
+    vendor: 'opaque-standard-schema',
+    validate(value) {
+      return value && typeof value === 'object' && !Array.isArray(value)
+        ? { value }
+        : { issues: [{ message: 'Expected settings object' }] };
+    },
+  },
+};
+
+export default document(SettingsSchema, {
+  seed: {
+    theme: 'light',
+    flags: {
+      preview: true,
+    },
+  },
+});

examples/standard-schema/db/users.schema.mjs

@@ -0,0 +1,72 @@
+import { collection, field } from '@async/db/schema';
+
+const UserSchema = {
+  '~standard': {
+    version: 1,
+    vendor: 'example-standard-schema',
+    async validate(value) {
+      await Promise.resolve();
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return { issues: [{ message: 'Expected an object' }] };
+      }
+      if (typeof value.email !== 'string' || !value.email.includes('@')) {
+        return {
+          issues: [
+            {
+              message: 'Email must include @',
+              path: ['email'],
+            },
+          ],
+        };
+      }
+      return {
+        value: {
+          ...value,
+          email: value.email.trim().toLowerCase(),
+        },
+      };
+    },
+    jsonSchema: {
+      output() {
+        return {
+          type: 'object',
+          required: ['email', 'firstName', 'lastName'],
+          properties: {
+            id: { type: 'string' },
+            email: { type: 'string', description: 'Email address used for sign-in.' },
+            firstName: { type: 'string' },
+            lastName: { type: 'string' },
+          },
+        };
+      },
+    },
+  },
+};
+
+export default collection({
+  idField: 'id',
+  validator: UserSchema,
+  fields: {
+    email: field.string({
+      required: true,
+      unique: true,
+      description: 'Normalized login email.',
+    }),
+    displayName: field.computed(field.string(), {
+      resolveMany({ records }) {
+        return new Map(records.map((record) => [
+          record.id,
+          `${record.firstName} ${record.lastName}`,
+        ]));
+      },
+    }),
+  },
+  seed: [
+    {
+      id: 'u_1',
+      email: ' ADA@EXAMPLE.COM ',
+      firstName: 'Ada',
+      lastName: 'Lovelace',
+    },
+  ],
+});

examples/standard-schema/example.json

@@ -0,0 +1,5 @@
+{
+  "title": "Standard Schema",
+  "description": "Use any Standard Schema-compatible validator as the resource contract, then layer Async DB metadata and computed fields on top.",
+  "tags": ["schema", "validation", "computed"]
+}