@schemic/core 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vertio Solutions
+
+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

@@ -0,0 +1,212 @@
+# @schemic/core
+
+Author [SurrealDB](https://surrealdb.com) schemas with [Zod](https://zod.dev).
+
+- **`s.*`** — a drop-in for `z.*` that also carries SurrealQL metadata.
+- **`defineTable` / `defineField`** — generate `DEFINE TABLE` / `DEFINE FIELD` DDL from your schema.
+- **`decode` / `encode`** — map DB rows ⇄ app objects across Zod's two channels via codecs
+  (`DateTime`⇄`Date`, `Uuid`⇄`string`, `RecordId`, …).
+
+## Install
+
+```bash
+bun add @schemic/core surrealdb zod
+```
+
+`surrealdb` and `zod` are peer dependencies.
+
+## Quick start
+
+```ts
+import { s, table, relation, defineTable, type App } from "@schemic/core";
+import { surql } from "surrealdb";
+
+export const User = table("user", {
+  id: s.string(),                                  // -> record<user>
+  name: s.string(),
+  email: s.email(),
+  status: s.string().$default("pending"),          // DB-side DEFAULT
+  createdAt: s.datetime().$default(surql`time::now()`).$readonly(),
+});
+
+export const Friend = relation("friend", {
+  strength: s.number().$gte(0).$lte(1), // -> ASSERT $value >= 0 AND $value <= 1
+})
+  .from(User)
+  .to(User);
+
+// SurrealQL DDL:
+console.log(defineTable(User));
+// DEFINE TABLE user TYPE NORMAL SCHEMAFULL;
+// DEFINE FIELD name ON TABLE user TYPE string;
+// ...
+
+// Build a CREATE payload (DB-filled fields optional), then decode a row back:
+const payload = User.encode({ name: "Alice", email: "alice@example.com" });
+type AppUser = App<typeof User>; // id: RecordId, createdAt: Date, ...
+```
+
+### Reading & writing
+
+The whole JS ⇄ DB mapping rides on Zod's two codec channels:
+
+- **`decode`** (read, wire → app) turns a DB row into your app object (`DateTime` → `Date`,
+  `Uuid` → `string`, `RecordId`, …).
+- **`encode` / `encodePartial`** (write, app → wire) build a payload. They're **create/patch-
+  shaped**: DB-filled fields (`$default`, `id`) are *optional* (the DB fills them), absent keys
+  are omitted, and each provided value is validated. Use `encode` with `CONTENT` (create) and
+  `encodePartial` with `MERGE` (patch).
+- `parse*` are kept as **`@deprecated`** aliases of `decode*` (for `z`-API familiarity).
+
+`encode` / `encodePartial` return a typed `Partial<Wire<T>>` (codec fields are wire-typed —
+`createdAt` is a `DateTime`, not a `Date`). They **throw** a `ZodError` on invalid input. For
+the non-throwing form use `safeEncode` / `safeEncodePartial`, which return a Zod-style
+`{ success: true; data } | { success: false; error }` (all field errors aggregated into one
+`ZodError`). Each has an async twin (`encodeAsync` / `safeEncodeAsync` / …) for async
+refinements. `TableDef.system.{encode,safeEncode,…}` are the same over the full shape,
+including `$internal()` fields. If you ever need the **raw full-object codec** (no create-
+shaping), that's just `z.encode(table.object, app)`.
+
+Field-level codecs work the same way directly on a field:
+
+```ts
+s.datetime().decode(dbDateTime); // -> Date
+s.datetime().encode(new Date()); // -> DateTime
+s.uuid().encode("0190b6e0-…");   // -> Uuid
+```
+
+See [`examples/`](./examples) for a full schema, a live demo (`bun examples/demo.ts`),
+and a small CRUD server.
+
+## Nested objects
+
+`s.object({ ... })` builds a nested SurrealQL `object`, and @schemic/core looks *through* it so
+each nested field keeps its own DDL metadata and create-optionality:
+
+- A nested field with a DB `$default` (or `$value(..., { optional: true })`) is
+  **create-optional** in `encode` — omit it and the DB fills it — exactly like a top-level
+  defaulted field. So you can pass a *partial* nested object and let the DB complete it:
+
+  ```ts
+  const Project = table("project", {
+    name: s.string(),
+    settings: s.object({
+      isPublic: s.boolean().$default(surql`false`),
+      defaultView: s.enum(["list", "board"]).$default("list"),
+    }),
+  });
+
+  Project.encode({ name: "Launch", settings: { defaultView: "board" } });
+  // -> { name, settings: { defaultView: "board" } }   (the DB fills settings.isPublic)
+  ```
+
+- On the **decoded** side those nested fields stay **required** in `App<T>` — a stored row has
+  them — consistent with how top-level defaulted fields behave.
+
+### `encode` (CONTENT) vs `encodePartial` (MERGE)
+
+`encode` builds a **`CONTENT`** payload; `encodePartial` builds a **deep-partial `MERGE`**
+payload — every nested key is optional, mirroring SurrealDB's `MERGE`, which **recursively
+deep-merges** (siblings are preserved at every level):
+
+```ts
+Project.encodePartial({ settings: { defaultView: "board" } });
+// -> { settings: { defaultView: "board" } }   ->   UPDATE $id MERGE $payload
+```
+
+The library only **builds the payload** — you choose the statement. Pair `encode` with `CONTENT`
+and `encodePartial` with `MERGE`. **Warning:** sending a *partial* payload with `CONTENT`
+**replaces** the record (unsupplied fields are dropped); use `MERGE` for partial writes.
+
+### Atomic (object-level) validation
+
+Only objects built with `s.object` are flattened/recursed. A field that holds a **raw, refined
+`z.object`** is validated **atomically** — provide it whole, and its object-level `refine` runs:
+
+```ts
+import { z } from "zod";
+
+table("booking", {
+  // validated all-or-nothing; the refine runs on the whole object
+  range: z.object({ from: z.number(), to: z.number() }).refine((r) => r.from <= r.to),
+});
+```
+
+That's the built-in escape when you want all-or-nothing / object-level checks. For full manual
+control, build the payload yourself and pass it via `surql` — `encode`/`encodePartial` are just
+conveniences, not a requirement.
+
+## Permissions
+
+Author row-level `PERMISSIONS` with `TableDef.permissions(spec)` and `SField.$permissions(spec)`.
+A `spec` is `true` (FULL) / `false` (NONE) / a `surql` `WHERE` expr (shared by every op) / a
+per-op object. In a per-op object each op is `true`/`false`/a `surql` expr, or `` `same as <op>` ``
+to reuse another op's rule; ops with an identical resolved rule auto-merge into one `FOR a, b …`
+clause. Table permissions cover `select`/`create`/`update`/`delete`; **fields have no `delete`** op.
+
+```ts
+table("project", {
+  owner: User.record().$default(surql`$auth.id`).$readonly(),
+  // ...
+}).permissions({
+  select: surql`owner = $auth.id OR settings.isPublic = true`,
+  create: surql`owner = $auth.id`,
+  update: "same as create",
+  delete: "same as create",
+});
+```
+
+Table permissions fold into the single generated `DEFINE TABLE` (no separate `OVERWRITE`).
+**Omitted-op asymmetry** (it mirrors SurrealDB's own defaults): an omitted op defaults to
+**NONE** (deny) on a *table* but to **FULL** on a *field* — the table is the gate, so to lock a
+field op you must set it `false` explicitly.
+
+## Asserts / constraints
+
+A field can accumulate several `ASSERT` fragments that AND-combine into one `ASSERT`
+clause (deduped, order preserved). There are three sources:
+
+- **Format builders bake by default.** `s.email()` → `ASSERT string::is_email($value)`,
+  `s.url()` → `string::is_url`, and likewise `ulid` / `ipv4` / `ipv6` — i.e. every
+  builder whose `string::is_*` validator exists on the server. SurrealDB **3.x** uses the
+  underscore form (`string::is_email`, **not** `string::is::email`). Formats with no
+  server validator (`nanoid`, `cuid`/`cuid2`, `xid`, `ksuid`, `cidrv4`/`cidrv6`, `guid`,
+  `base64`/`base64url`, `e164`, `jwt`, `emoji`) stay assert-free — no fabricated regex.
+  `s.uuid()` is the native `uuid` type (no assert).
+- **`$`-constraints** apply the matching Zod check app-side **and** push a type-aware DB
+  fragment (string vs. number is read from the schema):
+  - `.$min(n)` / `.$max(n)` — string: `string::len($value) >= n` / `<= n`; number: `$value >= n` / `<= n`
+  - `.$length(n)` — string: `string::len($value) == n`
+  - `.$regex(/re/)` — string: `$value = /re/`
+  - `.$gt(n)` / `.$gte(n)` / `.$lt(n)` / `.$lte(n)` — number: `$value > / >= / < / <= n`
+- **`.$assert(...)`** — `.$assert(surql\`…\`)` pushes a custom fragment; `.$assert()` (no
+  args) derives fragments from the field's existing Zod checks (formats, length, regex,
+  number bounds), best-effort.
+
+```ts
+s.string().$min(1).$max(120);                 // string::len($value) >= 1 AND ... <= 120
+s.number().$gte(0).$lte(1);                    // $value >= 0 AND $value <= 1
+s.email().$assert(surql`$value != $forbidden`); // string::is_email($value) AND $value != $forbidden
+```
+
+## Live queries
+
+There's no special live API — a subscription payload is just a row, so decode it exactly like
+a query result:
+
+```ts
+await db.live("user", (action, value) => {
+  if (action === "CLOSE") return;
+  const user = User.decode(value); // decoded App<User> — RecordId, Date, …
+});
+```
+
+A typed query + live layer (results decoded automatically) is planned in `@schemic/core/orm`.
+
+## Develop
+
+```bash
+bun test          # unit + live (live skips when no SurrealDB is reachable)
+bun run typecheck
+bun run build     # -> lib/ (ESM + d.ts) via tsup
+```

package/lib/authoring.d.ts

@@ -0,0 +1,89 @@
+import * as z from 'zod';
+
+/** Any field of ANY dialect — the base type the helpers + wrappers accept. */
+type AnyField = SFieldBase<z.ZodType, string, any>;
+/** The Zod schema a field (or a raw Zod schema) carries. */
+type SchemaOf<F> = F extends SFieldBase<infer S, string, any> ? S : F extends z.ZodType ? F : never;
+/** The `Flags` channel a field carries (driver `$`-methods brand it; widens to `string` for `Shape`). */
+type FlagsOf<F> = F extends SFieldBase<z.ZodType, infer Fl, any> ? Fl : never;
+/** The schema one wrapper down — what `unwrap()` returns. */
+type InnerOf<S extends z.ZodType> = S extends z.ZodOptional<infer I extends z.ZodType> ? I : S extends z.ZodNullable<infer I extends z.ZodType> ? I : S extends z.ZodDefault<infer I extends z.ZodType> ? I : S extends z.ZodPrefault<infer I extends z.ZodType> ? I : S extends z.ZodCatch<infer I extends z.ZodType> ? I : S extends z.ZodReadonly<infer I extends z.ZodType> ? I : S extends z.ZodArray<infer I extends z.ZodType> ? I : S;
+/**
+ * Maps an object schema (built via a driver's `s.object`) to its original field shape, so nested
+ * fields keep their authoring metadata through generation. Kept on the schema, not the field, so it
+ * composes through `array()`/`optional()`/nesting.
+ */
+declare const objectFieldsRegistry: WeakMap<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>, Record<string, AnyField>>;
+/**
+ * The PORTABLE, dialect-agnostic field base. Holds the Zod schema, an opaque per-dialect `native`
+ * metadata slot, the field-level codecs, and the app-land Zod wrappers (which carry `native` forward
+ * via the `rebuild` hook so a chain keeps its concrete dialect type). Each dialect subclasses it to
+ * add native authoring (`$`-methods) and re-type the wrappers so a chain stays its own field type.
+ */
+declare abstract class SFieldBase<S extends z.ZodType = z.ZodType, Flags extends string = never, N = unknown> {
+    readonly schema: S;
+    readonly native: N;
+    constructor(schema: S, native: N);
+    /** Rebuild a sibling field of the SAME dialect with a new schema/flags. Each dialect overrides it. */
+    protected abstract rebuild<S2 extends z.ZodType, F2 extends string>(schema: S2, native: N): SFieldBase<S2, F2, N>;
+    /** A fresh, empty native-metadata bag (for wrappers like `or`/`and` that reset it). */
+    protected abstract blank(): N;
+    /** Decode a DB value to its app type (wire -> app). */
+    decode(value: unknown): z.output<S>;
+    /** Encode an app value to its DB wire type (app -> wire). */
+    encode(value: z.output<S>): z.input<S>;
+    decodeAsync(value: unknown): Promise<z.output<S>>;
+    encodeAsync(value: z.output<S>): Promise<z.input<S>>;
+    safeDecode(value: unknown): z.ZodSafeParseResult<z.core.output<S>>;
+    safeEncode(value: z.output<S>): z.ZodSafeParseResult<z.core.input<S>>;
+    safeDecodeAsync(value: unknown): Promise<z.ZodSafeParseResult<z.core.output<S>>>;
+    safeEncodeAsync(value: z.output<S>): Promise<z.ZodSafeParseResult<z.core.input<S>>>;
+    /** @deprecated `parse` decodes a value (wire -> app). Use {@link decode}. */
+    parse(value: unknown): z.output<S>;
+    /** @deprecated Use {@link safeDecode}. */
+    safeParse(value: unknown): z.ZodSafeParseResult<z.core.output<S>>;
+    /** @deprecated Use {@link decodeAsync}. */
+    parseAsync(value: unknown): Promise<z.output<S>>;
+    /** @deprecated Use {@link safeDecodeAsync}. */
+    safeParseAsync(value: unknown): Promise<z.ZodSafeParseResult<z.core.output<S>>>;
+    optional(): SFieldBase<z.ZodOptional<S>, Flags, N>;
+    nullable(): SFieldBase<z.ZodNullable<S>, Flags, N>;
+    default(value: z.input<S>): SFieldBase<z.ZodDefault<S>, Flags, N>;
+    /** Zod prefault: fill an absent value with `value`, then validate it (unlike `.default`). */
+    prefault(value: z.input<S>): SFieldBase<z.ZodPrefault<S>, Flags, N>;
+    /** Zod catch: fall back to `value` when parsing fails. */
+    catch(value: z.output<S>): SFieldBase<z.ZodCatch<S>, Flags, N>;
+    array(): SFieldBase<z.ZodArray<S>, Flags, N>;
+    nullish(): SFieldBase<z.ZodOptional<z.ZodNullable<S>>, Flags, N>;
+    /** Zod union — `a.or(b)` accepts either. Mirrors Zod's `.or()`. */
+    or<F extends AnyField | z.ZodType>(other: F): SFieldBase<z.ZodUnion<[S, SchemaOf<F>]>, never, N>;
+    /** Zod intersection — `a.and(b)`. Mirrors Zod's `.and()`. */
+    and<F extends AnyField | z.ZodType>(other: F): SFieldBase<z.ZodIntersection<S, SchemaOf<F>>, never, N>;
+    refine(check: (arg: z.output<S>) => unknown, params?: string | z.core.$ZodCustomParams): this;
+    superRefine(refinement: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => void): this;
+    check(...checks: (z.core.CheckFn<z.output<S>> | z.core.$ZodCheck<z.output<S>>)[]): this;
+    overwrite(fn: (x: z.output<S>) => z.output<S>): this;
+    brand<B extends PropertyKey = PropertyKey>(value?: B): this;
+    /** Zod's app-side metadata (JSON-schema/docs) — distinct from a driver's `$comment()`. */
+    describe(description: string): this;
+    meta(data: z.core.GlobalMeta): this;
+    /** Zod's app-side readonly (TS-immutable output) — distinct from a driver's `$readonly()`. */
+    readonly(): SFieldBase<z.ZodReadonly<S>, Flags, N>;
+    /** Zod transform — changes the decoded `App<>` value; the stored (wire) type is unchanged. */
+    transform<NewOut>(fn: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => NewOut): SFieldBase<z.ZodPipe<S, z.ZodTransform<Awaited<NewOut>, z.output<S>>>, Flags, N>;
+    /** Zod pipe — feed this field's output into `target`; the stored (wire) type stays `this`. */
+    pipe<T extends z.core.$ZodType<unknown, z.output<S>>>(target: T): SFieldBase<z.ZodPipe<S, T>, Flags, N>;
+    /** Peel one wrapper (optional/nullable/default/prefault/catch/readonly/array) off the field. */
+    unwrap(): SFieldBase<InnerOf<S>, Flags, N>;
+    /** Object-only: allow arbitrary extra keys — `FLEXIBLE` in DDL. Mirrors Zod's `.loose()`. */
+    loose(): this;
+    /** Object-only: reject unknown keys — the default. Mirrors Zod's `.strict()`. */
+    strict(): this;
+    /** Alias for {@link loose} — a `FLEXIBLE` object accepting arbitrary keys. */
+    flexible(): this;
+    private objectMode;
+}
+/** Unwrap a field to its Zod schema (raw Zod schemas pass through). */
+declare const toZod: (v: AnyField | z.ZodType) => z.ZodType;
+
+export { type AnyField, type FlagsOf, type InnerOf, SFieldBase, type SchemaOf, objectFieldsRegistry, toZod };

package/lib/authoring.js

@@ -0,0 +1,187 @@
+// src/authoring.ts
+import * as z from "zod";
+var objectFieldsRegistry = /* @__PURE__ */ new WeakMap();
+var SFieldBase = class {
+  constructor(schema, native) {
+    this.schema = schema;
+    this.native = native;
+  }
+  // --- Field-level codec (raw, on `this.schema`): `decode` reads (wire -> app), `encode` writes
+  // (app -> wire). Create-shaping is a table concept, so these are NOT create-shaped. ---
+  /** Decode a DB value to its app type (wire -> app). */
+  decode(value) {
+    return z.decode(this.schema, value);
+  }
+  /** Encode an app value to its DB wire type (app -> wire). */
+  encode(value) {
+    return z.encode(this.schema, value);
+  }
+  decodeAsync(value) {
+    return z.decodeAsync(this.schema, value);
+  }
+  encodeAsync(value) {
+    return z.encodeAsync(this.schema, value);
+  }
+  safeDecode(value) {
+    return z.safeDecode(this.schema, value);
+  }
+  safeEncode(value) {
+    return z.safeEncode(this.schema, value);
+  }
+  safeDecodeAsync(value) {
+    return z.safeDecodeAsync(this.schema, value);
+  }
+  safeEncodeAsync(value) {
+    return z.safeEncodeAsync(this.schema, value);
+  }
+  // Deprecated Zod-style aliases — `parse` runs the DECODE direction (wire -> app).
+  /** @deprecated `parse` decodes a value (wire -> app). Use {@link decode}. */
+  parse(value) {
+    return this.decode(value);
+  }
+  /** @deprecated Use {@link safeDecode}. */
+  safeParse(value) {
+    return this.safeDecode(value);
+  }
+  /** @deprecated Use {@link decodeAsync}. */
+  parseAsync(value) {
+    return this.decodeAsync(value);
+  }
+  /** @deprecated Use {@link safeDecodeAsync}. */
+  safeParseAsync(value) {
+    return this.safeDecodeAsync(value);
+  }
+  // Zod wrappers — delegate to the inner schema, carry native metadata + flags forward.
+  optional() {
+    return this.rebuild(this.schema.optional(), this.native);
+  }
+  nullable() {
+    return this.rebuild(this.schema.nullable(), this.native);
+  }
+  default(value) {
+    return this.rebuild(this.schema.default(value), this.native);
+  }
+  /** Zod prefault: fill an absent value with `value`, then validate it (unlike `.default`). */
+  prefault(value) {
+    return this.rebuild(z.prefault(this.schema, value), this.native);
+  }
+  /** Zod catch: fall back to `value` when parsing fails. */
+  catch(value) {
+    return this.rebuild(this.schema.catch(value), this.native);
+  }
+  array() {
+    return this.rebuild(z.array(this.schema), this.native);
+  }
+  nullish() {
+    return this.rebuild(this.schema.nullish(), this.native);
+  }
+  /** Zod union — `a.or(b)` accepts either. Mirrors Zod's `.or()`. */
+  or(other) {
+    return this.rebuild(
+      z.union([this.schema, toZod(other)]),
+      this.blank()
+    );
+  }
+  /** Zod intersection — `a.and(b)`. Mirrors Zod's `.and()`. */
+  and(other) {
+    return this.rebuild(
+      z.intersection(this.schema, toZod(other)),
+      this.blank()
+    );
+  }
+  // --- Native Zod passthrough (drop-in for `z.*`): app-side validation / transform / metadata,
+  // delegated to the inner schema. The dialect-DDL side stays under the driver's `$`-methods. ---
+  refine(check, params) {
+    return this.rebuild(
+      this.schema.refine(check, params),
+      this.native
+    );
+  }
+  superRefine(refinement) {
+    return this.rebuild(
+      this.schema.superRefine(refinement),
+      this.native
+    );
+  }
+  check(...checks) {
+    return this.rebuild(
+      this.schema.check(...checks),
+      this.native
+    );
+  }
+  overwrite(fn) {
+    return this.rebuild(
+      this.schema.overwrite(fn),
+      this.native
+    );
+  }
+  brand(value) {
+    return this.rebuild(
+      this.schema.brand(value),
+      this.native
+    );
+  }
+  /** Zod's app-side metadata (JSON-schema/docs) — distinct from a driver's `$comment()`. */
+  describe(description) {
+    return this.rebuild(
+      this.schema.describe(description),
+      this.native
+    );
+  }
+  meta(data) {
+    return this.rebuild(
+      this.schema.meta(data),
+      this.native
+    );
+  }
+  /** Zod's app-side readonly (TS-immutable output) — distinct from a driver's `$readonly()`. */
+  readonly() {
+    return this.rebuild(this.schema.readonly(), this.native);
+  }
+  /** Zod transform — changes the decoded `App<>` value; the stored (wire) type is unchanged. */
+  transform(fn) {
+    return this.rebuild(this.schema.transform(fn), this.native);
+  }
+  /** Zod pipe — feed this field's output into `target`; the stored (wire) type stays `this`. */
+  pipe(target) {
+    return this.rebuild(
+      this.schema.pipe(target),
+      this.native
+    );
+  }
+  /** Peel one wrapper (optional/nullable/default/prefault/catch/readonly/array) off the field. */
+  unwrap() {
+    const def = this.schema._zod.def;
+    const inner = def.innerType ?? def.element ?? this.schema;
+    return this.rebuild(inner, this.native);
+  }
+  /** Object-only: allow arbitrary extra keys — `FLEXIBLE` in DDL. Mirrors Zod's `.loose()`. */
+  loose() {
+    return this.objectMode("loose");
+  }
+  /** Object-only: reject unknown keys — the default. Mirrors Zod's `.strict()`. */
+  strict() {
+    return this.objectMode("strict");
+  }
+  /** Alias for {@link loose} — a `FLEXIBLE` object accepting arbitrary keys. */
+  flexible() {
+    return this.loose();
+  }
+  objectMode(mode) {
+    const obj = this.schema;
+    if (typeof obj.loose !== "function" || typeof obj.strict !== "function") {
+      return this;
+    }
+    const next = mode === "loose" ? obj.loose() : obj.strict();
+    const fields = objectFieldsRegistry.get(this.schema);
+    if (fields) objectFieldsRegistry.set(next, fields);
+    return this.rebuild(next, this.native);
+  }
+};
+var toZod = (v) => v instanceof SFieldBase ? v.schema : v;
+export {
+  SFieldBase,
+  objectFieldsRegistry,
+  toZod
+};
+//# sourceMappingURL=authoring.js.map

package/lib/authoring.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authoring.ts"],"sourcesContent":["// The NEUTRAL, dialect-agnostic AUTHORING BASE (docs/AUTHORING-SPLIT.md — \"base builder in core\").\n// Each driver package builds its `s.*` on this: `class <D>Field extends SFieldBase<S, Flags, <D>Meta>`\n// adds the dialect's native authoring (`$`-methods) and its `$<driver>(type, codec)` escape hatch for\n// types not representable on the wire; the base provides the Zod codec, the Zod wrappers, the full\n// `z.*` passthrough, and the `rebuild`/`blank` seam that carries native metadata through a chain.\n//\n// It references NOTHING dialect-specific — it's generic over the per-dialect native-metadata slot `N`.\n// It is also Zod-CLEAN: app-side behaviour delegates to the inner Zod schema (`z.decode`/`z.encode`/\n// the wrappers) via Zod's public API, with side-channel metadata kept on WeakMaps — never patching\n// Zod internals.\n\nimport * as z from \"zod\";\n\n// `SFieldBase` is INVARIANT in its native-metadata slot `N` (the protected `rebuild(native: N)` makes\n// N contravariant while `native`/`blank` make it covariant). So a dialect field — `SField` with\n// `N = SurrealMeta` — is NOT assignable to a fixed `N = unknown`, which would make `AnyField` reject\n// real dialect fields (e.g. `.or(s.int())`). At THIS cross-dialect boundary `N` is honestly \"any\n// dialect's metadata\": erase it to `any` (bivariant) so every driver's field is an `AnyField`. The\n// concrete `N` is preserved everywhere it matters — each driver's own field type keeps `N = <D>Meta`.\n\n/** Any field of ANY dialect — the base type the helpers + wrappers accept. */\n// biome-ignore lint/suspicious/noExplicitAny: cross-dialect erasure of the invariant native slot N.\nexport type AnyField = SFieldBase<z.ZodType, string, any>;\n\n/** The Zod schema a field (or a raw Zod schema) carries. */\nexport type SchemaOf<F> =\n  // biome-ignore lint/suspicious/noExplicitAny: match a field of any dialect (N is invariant).\n  F extends SFieldBase<infer S, string, any>\n    ? S\n    : F extends z.ZodType\n      ? F\n      : never;\n\n/** The `Flags` channel a field carries (driver `$`-methods brand it; widens to `string` for `Shape`). */\nexport type FlagsOf<F> =\n  // biome-ignore lint/suspicious/noExplicitAny: match a field of any dialect (N is invariant).\n  F extends SFieldBase<z.ZodType, infer Fl, any> ? Fl : never;\n\n/** The schema one wrapper down — what `unwrap()` returns. */\nexport type InnerOf<S extends z.ZodType> =\n  S extends z.ZodOptional<infer I extends z.ZodType>\n    ? I\n    : S extends z.ZodNullable<infer I extends z.ZodType>\n      ? I\n      : S extends z.ZodDefault<infer I extends z.ZodType>\n        ? I\n        : S extends z.ZodPrefault<infer I extends z.ZodType>\n          ? I\n          : S extends z.ZodCatch<infer I extends z.ZodType>\n            ? I\n            : S extends z.ZodReadonly<infer I extends z.ZodType>\n              ? I\n              : S extends z.ZodArray<infer I extends z.ZodType>\n                ? I\n                : S;\n\n/**\n * Maps an object schema (built via a driver's `s.object`) to its original field shape, so nested\n * fields keep their authoring metadata through generation. Kept on the schema, not the field, so it\n * composes through `array()`/`optional()`/nesting.\n */\nexport const objectFieldsRegistry = new WeakMap<\n  z.ZodType,\n  Record<string, AnyField>\n>();\n\n/**\n * The PORTABLE, dialect-agnostic field base. Holds the Zod schema, an opaque per-dialect `native`\n * metadata slot, the field-level codecs, and the app-land Zod wrappers (which carry `native` forward\n * via the `rebuild` hook so a chain keeps its concrete dialect type). Each dialect subclasses it to\n * add native authoring (`$`-methods) and re-type the wrappers so a chain stays its own field type.\n */\nexport abstract class SFieldBase<\n  S extends z.ZodType = z.ZodType,\n  Flags extends string = never,\n  N = unknown,\n> {\n  constructor(\n    readonly schema: S,\n    readonly native: N,\n  ) {}\n\n  /** Rebuild a sibling field of the SAME dialect with a new schema/flags. Each dialect overrides it. */\n  protected abstract rebuild<S2 extends z.ZodType, F2 extends string>(\n    schema: S2,\n    native: N,\n  ): SFieldBase<S2, F2, N>;\n  /** A fresh, empty native-metadata bag (for wrappers like `or`/`and` that reset it). */\n  protected abstract blank(): N;\n\n  // --- Field-level codec (raw, on `this.schema`): `decode` reads (wire -> app), `encode` writes\n  // (app -> wire). Create-shaping is a table concept, so these are NOT create-shaped. ---\n  /** Decode a DB value to its app type (wire -> app). */\n  decode(value: unknown): z.output<S> {\n    return z.decode(this.schema, value as never);\n  }\n  /** Encode an app value to its DB wire type (app -> wire). */\n  encode(value: z.output<S>): z.input<S> {\n    return z.encode(this.schema, value);\n  }\n  decodeAsync(value: unknown): Promise<z.output<S>> {\n    return z.decodeAsync(this.schema, value as never);\n  }\n  encodeAsync(value: z.output<S>): Promise<z.input<S>> {\n    return z.encodeAsync(this.schema, value);\n  }\n  safeDecode(value: unknown) {\n    return z.safeDecode(this.schema, value as never);\n  }\n  safeEncode(value: z.output<S>) {\n    return z.safeEncode(this.schema, value);\n  }\n  safeDecodeAsync(value: unknown) {\n    return z.safeDecodeAsync(this.schema, value as never);\n  }\n  safeEncodeAsync(value: z.output<S>) {\n    return z.safeEncodeAsync(this.schema, value);\n  }\n  // Deprecated Zod-style aliases — `parse` runs the DECODE direction (wire -> app).\n  /** @deprecated `parse` decodes a value (wire -> app). Use {@link decode}. */\n  parse(value: unknown): z.output<S> {\n    return this.decode(value);\n  }\n  /** @deprecated Use {@link safeDecode}. */\n  safeParse(value: unknown) {\n    return this.safeDecode(value);\n  }\n  /** @deprecated Use {@link decodeAsync}. */\n  parseAsync(value: unknown): Promise<z.output<S>> {\n    return this.decodeAsync(value);\n  }\n  /** @deprecated Use {@link safeDecodeAsync}. */\n  safeParseAsync(value: unknown) {\n    return this.safeDecodeAsync(value);\n  }\n\n  // Zod wrappers — delegate to the inner schema, carry native metadata + flags forward.\n  optional(): SFieldBase<z.ZodOptional<S>, Flags, N> {\n    return this.rebuild(this.schema.optional(), this.native);\n  }\n  nullable(): SFieldBase<z.ZodNullable<S>, Flags, N> {\n    return this.rebuild(this.schema.nullable(), this.native);\n  }\n  default(value: z.input<S>): SFieldBase<z.ZodDefault<S>, Flags, N> {\n    return this.rebuild(this.schema.default(value as never), this.native);\n  }\n  /** Zod prefault: fill an absent value with `value`, then validate it (unlike `.default`). */\n  prefault(value: z.input<S>): SFieldBase<z.ZodPrefault<S>, Flags, N> {\n    return this.rebuild(z.prefault(this.schema, value as never), this.native);\n  }\n  /** Zod catch: fall back to `value` when parsing fails. */\n  catch(value: z.output<S>): SFieldBase<z.ZodCatch<S>, Flags, N> {\n    return this.rebuild(this.schema.catch(value as never), this.native);\n  }\n  array(): SFieldBase<z.ZodArray<S>, Flags, N> {\n    return this.rebuild(z.array(this.schema), this.native);\n  }\n  nullish(): SFieldBase<z.ZodOptional<z.ZodNullable<S>>, Flags, N> {\n    return this.rebuild(this.schema.nullish(), this.native);\n  }\n  /** Zod union — `a.or(b)` accepts either. Mirrors Zod's `.or()`. */\n  or<F extends AnyField | z.ZodType>(\n    other: F,\n  ): SFieldBase<z.ZodUnion<[S, SchemaOf<F>]>, never, N> {\n    return this.rebuild<z.ZodUnion<[S, SchemaOf<F>]>, never>(\n      z.union([this.schema, toZod(other)]) as z.ZodUnion<[S, SchemaOf<F>]>,\n      this.blank(),\n    );\n  }\n  /** Zod intersection — `a.and(b)`. Mirrors Zod's `.and()`. */\n  and<F extends AnyField | z.ZodType>(\n    other: F,\n  ): SFieldBase<z.ZodIntersection<S, SchemaOf<F>>, never, N> {\n    return this.rebuild<z.ZodIntersection<S, SchemaOf<F>>, never>(\n      z.intersection(this.schema, toZod(other) as SchemaOf<F>),\n      this.blank(),\n    );\n  }\n\n  // --- Native Zod passthrough (drop-in for `z.*`): app-side validation / transform / metadata,\n  // delegated to the inner schema. The dialect-DDL side stays under the driver's `$`-methods. ---\n  refine(\n    check: (arg: z.output<S>) => unknown,\n    params?: string | z.core.$ZodCustomParams,\n  ): this {\n    return this.rebuild(\n      this.schema.refine(check, params) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  superRefine(\n    refinement: (\n      arg: z.output<S>,\n      ctx: z.core.$RefinementCtx<z.output<S>>,\n    ) => void,\n  ): this {\n    return this.rebuild(\n      this.schema.superRefine(refinement) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  check(\n    ...checks: (z.core.CheckFn<z.output<S>> | z.core.$ZodCheck<z.output<S>>)[]\n  ): this {\n    return this.rebuild(\n      this.schema.check(...checks) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  overwrite(fn: (x: z.output<S>) => z.output<S>): this {\n    return this.rebuild(\n      this.schema.overwrite(fn) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  brand<B extends PropertyKey = PropertyKey>(value?: B): this {\n    return this.rebuild(\n      this.schema.brand(value) as unknown as S,\n      this.native,\n    ) as unknown as this;\n  }\n  /** Zod's app-side metadata (JSON-schema/docs) — distinct from a driver's `$comment()`. */\n  describe(description: string): this {\n    return this.rebuild(\n      this.schema.describe(description) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  meta(data: z.core.GlobalMeta): this {\n    return this.rebuild(\n      this.schema.meta(data) as S,\n      this.native,\n    ) as unknown as this;\n  }\n  /** Zod's app-side readonly (TS-immutable output) — distinct from a driver's `$readonly()`. */\n  readonly(): SFieldBase<z.ZodReadonly<S>, Flags, N> {\n    return this.rebuild(this.schema.readonly(), this.native);\n  }\n  /** Zod transform — changes the decoded `App<>` value; the stored (wire) type is unchanged. */\n  transform<NewOut>(\n    fn: (arg: z.output<S>, ctx: z.core.$RefinementCtx<z.output<S>>) => NewOut,\n  ): SFieldBase<\n    z.ZodPipe<S, z.ZodTransform<Awaited<NewOut>, z.output<S>>>,\n    Flags,\n    N\n  > {\n    return this.rebuild(this.schema.transform(fn), this.native);\n  }\n  /** Zod pipe — feed this field's output into `target`; the stored (wire) type stays `this`. */\n  pipe<T extends z.core.$ZodType<unknown, z.output<S>>>(\n    target: T,\n  ): SFieldBase<z.ZodPipe<S, T>, Flags, N> {\n    return this.rebuild(\n      this.schema.pipe(target) as z.ZodPipe<S, T>,\n      this.native,\n    );\n  }\n  /** Peel one wrapper (optional/nullable/default/prefault/catch/readonly/array) off the field. */\n  unwrap(): SFieldBase<InnerOf<S>, Flags, N> {\n    const def = this.schema._zod.def as {\n      innerType?: z.ZodType;\n      element?: z.ZodType;\n    };\n    const inner = def.innerType ?? def.element ?? this.schema;\n    return this.rebuild(inner, this.native) as unknown as SFieldBase<\n      InnerOf<S>,\n      Flags,\n      N\n    >;\n  }\n\n  /** Object-only: allow arbitrary extra keys — `FLEXIBLE` in DDL. Mirrors Zod's `.loose()`. */\n  loose(): this {\n    return this.objectMode(\"loose\");\n  }\n  /** Object-only: reject unknown keys — the default. Mirrors Zod's `.strict()`. */\n  strict(): this {\n    return this.objectMode(\"strict\");\n  }\n  /** Alias for {@link loose} — a `FLEXIBLE` object accepting arbitrary keys. */\n  flexible(): this {\n    return this.loose();\n  }\n  private objectMode(mode: \"loose\" | \"strict\"): this {\n    const obj = this.schema as unknown as {\n      loose?: () => z.ZodType;\n      strict?: () => z.ZodType;\n    };\n    if (typeof obj.loose !== \"function\" || typeof obj.strict !== \"function\") {\n      return this; // not an object schema — no-op\n    }\n    const next = (mode === \"loose\"\n      ? obj.loose()\n      : obj.strict()) as unknown as S;\n    // Carry the nested-field registry forward so DDL/create-shaping still see the subfields.\n    const fields = objectFieldsRegistry.get(this.schema);\n    if (fields) objectFieldsRegistry.set(next, fields);\n    return this.rebuild(next, this.native) as unknown as this;\n  }\n}\n\n/** Unwrap a field to its Zod schema (raw Zod schemas pass through). */\nexport const toZod = (v: AnyField | z.ZodType): z.ZodType =>\n  v instanceof SFieldBase ? v.schema : v;\n"],"mappings":"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","names":[]}

package/lib/chunk-C4D6JWSE.js

@@ -0,0 +1,54 @@
+// src/connection.ts
+function connectionEntry(driver, input) {
+  return {
+    __schemic: "connection",
+    driver,
+    async resolve(ctx) {
+      const out = typeof input === "function" ? await input(ctx) : input;
+      return Array.isArray(out) ? out : [out];
+    }
+  };
+}
+function isConnectionEntry(v) {
+  return typeof v === "object" && v !== null && v.__schemic === "connection";
+}
+
+// src/driver/portable.ts
+var scalar = (name) => ({
+  t: "scalar",
+  name
+});
+var literal = (value) => ({
+  t: "literal",
+  value
+});
+var option = (inner) => inner.t === "scalar" && inner.name === "any" ? inner : { t: "option", inner };
+var nullable = (inner) => {
+  if (inner.t === "scalar" && inner.name === "any") return inner;
+  if (inner.t === "option")
+    return { t: "option", inner: nullable(inner.inner) };
+  return { t: "nullable", inner };
+};
+var array = (elem, size) => ({
+  t: "array",
+  elem,
+  ...size !== void 0 ? { size } : {}
+});
+var union = (members) => members.length === 1 ? members[0] : { t: "union", members };
+var record = (tables) => ({
+  t: "record",
+  tables
+});
+
+export {
+  connectionEntry,
+  isConnectionEntry,
+  scalar,
+  literal,
+  option,
+  nullable,
+  array,
+  union,
+  record
+};
+//# sourceMappingURL=chunk-C4D6JWSE.js.map

package/lib/chunk-C4D6JWSE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connection.ts","../src/driver/portable.ts"],"sourcesContent":["// The neutral MULTI-CONNECTION contract (design: docs/MULTI-CONNECTION.md). A project's config maps\n// names to CONNECTIONS; each is produced by a per-driver `<driver>Connection(...)` factory that wraps\n// {@link connectionEntry} with its own typed connection shape. Everything here is dialect-free — the\n// CLI reads only these neutral fields; driver-specific connection params ride on the driver's own\n// config type. The resolution engine (lazy DAG, fan-out, addressing) lives in the CLI layer.\n\ntype MaybePromise<T> = T | Promise<T>;\n\n/** The dialect-neutral fields the orchestration reads off every connection config. */\nexport interface ConnectionConfigBase {\n  /** Schema dir (the desired state + its migration files/snapshot). Shared dir = shared schema. */\n  schema: string;\n  /** Address within a COLLECTION (array-returning resolver) — `<name>:<key>`. Required on array entries. */\n  key?: string;\n  /** Migrations dir override; defaults relative to `schema`. */\n  migrations?: string;\n}\n\n/** A live, queryable handle to ANOTHER (already-resolved) connection, for use inside a resolver. */\nexport interface ResolvedConnectionHandle {\n  query<T = unknown>(sql: string, vars?: Record<string, unknown>): Promise<T[]>;\n}\n\n/**\n * What a connection RESOLVER receives. `connections` is a LAZY proxy of the other connections —\n * touching one resolves + connects it on demand (so the dependency graph falls out of access; cycles\n * error). `args` are CLI `--arg k=v` values (so a resolver can yield a SUBSET without resolving all).\n */\nexport interface ResolveContext {\n  connections: Record<string, ResolvedConnectionHandle>;\n  args: Record<string, string>;\n  env: NodeJS.ProcessEnv;\n}\n\n/**\n * The opaque, branded output of a `<driver>Connection(...)` factory — the only thing `defineConfig`'s\n * `connections` map accepts. Never hand-authored. `driver` is the package the CLI dynamically loads;\n * `resolve` always normalizes to an ARRAY (a single connection -> one element, a collection -> many).\n */\nexport interface ConnectionEntry {\n  readonly __schemic: \"connection\";\n  readonly driver: string;\n  resolve(ctx: ResolveContext): Promise<ConnectionConfigBase[]>;\n}\n\n/** A connection factory's input: a static config, or a resolver yielding one config or a keyed collection. */\nexport type ConnectionInput<C extends ConnectionConfigBase> =\n  | C\n  | ((ctx: ResolveContext) => MaybePromise<C | (C & { key: string })[]>);\n\n/**\n * Build a {@link ConnectionEntry} from a driver tag + a static config or resolver — the primitive each\n * driver package wraps in its typed `<driver>Connection(...)` factory (which fixes `C` to the driver's\n * own connection shape and overloads the array form to require `key`). Returns a branded entry whose\n * `resolve` always yields an array.\n */\nexport function connectionEntry<C extends ConnectionConfigBase>(\n  driver: string,\n  input: ConnectionInput<C>,\n): ConnectionEntry {\n  return {\n    __schemic: \"connection\",\n    driver,\n    async resolve(ctx) {\n      const out = typeof input === \"function\" ? await input(ctx) : input;\n      return Array.isArray(out) ? out : [out];\n    },\n  };\n}\n\n/** Type guard: is a `connections` map value a real factory output (vs a stray object)? */\nexport function isConnectionEntry(v: unknown): v is ConnectionEntry {\n  return (\n    typeof v === \"object\" &&\n    v !== null &&\n    (v as { __schemic?: unknown }).__schemic === \"connection\"\n  );\n}\n","// The PORTABLE TYPE MODEL — the keystone of multi-DB support (see docs/MULTI-DB-SPIKE.md).\n//\n// Today the Struct-IR carries a field's type as a SurrealQL type-expression STRING\n// (`StructField.kind`, e.g. `option<int>`, `array<record<user>, 3>`). That string is a dialect leak:\n// equality and rendering both have to understand SurrealQL grammar. This module defines the\n// dialect-INDEPENDENT replacement — a structured type that every driver translates to/from.\n//\n// STATUS (Milestone 1): defined but NOT yet wired into `StructField`. Milestone 2 replaces\n// `kind: string` with `type: PortableType`, makes `inferField` (src/ddl.ts) produce it, and flips\n// diff equality to a structured deep-compare over the normalized IR. Until then this is the target\n// shape, kept in code so the Surreal driver's `emitType`/`parseType` can be built against it.\n\n/**\n * The portable scalar set — the common denominator every driver maps to a concrete column type and\n * back. A driver MAY reject scalars it cannot represent (and authoring can pin a richer DB-native\n * type via `{ t: \"native\" }`). Names are lowercase and dialect-neutral.\n */\nexport type ScalarName =\n  | \"any\"\n  | \"bool\"\n  | \"string\"\n  | \"int\"\n  | \"float\"\n  | \"decimal\"\n  | \"number\" // a numeric whose int/float/decimal-ness is unconstrained\n  | \"datetime\"\n  | \"duration\"\n  | \"uuid\"\n  | \"bytes\"\n  | \"null\"; // the unit type of SQL NULL / Surreal `null` (distinct from `option`'s absence)\n\n/**\n * A dialect-independent field type. Drivers translate this to their own type expression (`emitType`)\n * and parse their introspection back into it (`parseType`). `option` and `nullable` are ORTHOGONAL\n * and BOTH equality-relevant — see the note on `nullable` below; never collapse them.\n */\nexport type PortableType =\n  /** A primitive scalar. */\n  | { t: \"scalar\"; name: ScalarName }\n  /** A literal value type, e.g. the `'active'` in `'active' | 'archived'`. */\n  | { t: \"literal\"; value: string | number | boolean }\n  /**\n   * The field may be ABSENT / NONE (Surreal `option<T>`; SQL \"column omitted / has a DEFAULT\").\n   * Orthogonal to `nullable`.\n   */\n  | { t: \"option\"; inner: PortableType }\n  /**\n   * The field may be NULL (Surreal `T | null`; SQL `NULL` vs `NOT NULL`). Orthogonal to `option`:\n   * `option<T>`, `T | null`, and `option<T | null>` are THREE DISTINCT types. `normalize()` folds\n   * `nullable(option(X))` -> `option(nullable(X))` so `.optional().nullable()` ≡ `.nullish()`.\n   */\n  | { t: \"nullable\"; inner: PortableType }\n  /** An ordered, possibly length-bounded list. */\n  | { t: \"array\"; elem: PortableType; size?: number }\n  /** A set (distinct elements), possibly length-bounded. */\n  | { t: \"set\"; elem: PortableType; size?: number }\n  /** A discriminated/plain union. `normalize()` keeps `members` canonically sorted. */\n  | { t: \"union\"; members: PortableType[] }\n  /** A nested object/record literal. `flexible` allows undeclared keys (Surreal FLEXIBLE). */\n  | { t: \"object\"; fields: Record<string, PortableType>; flexible?: boolean }\n  /**\n   * A link to a row in one of `tables` (Surreal `record<a | b>`; SQL foreign key). The id-VALUE type\n   * is intentionally NOT modelled here — the DDL never encodes it; it lives App/Wire-side (TS-only).\n   */\n  | { t: \"record\"; tables: string[] }\n  /** A geometry type (Surreal-native; PostGIS or unsupported elsewhere). */\n  | { t: \"geometry\"; kind: GeometryKind }\n  /** The bottom type (no value). */\n  | { t: \"never\" }\n  /**\n   * An escape hatch for a DB-specific type with no portable meaning (PG `tsvector`, etc.). Carries\n   * the owning driver `db` so a schema authored for one DB can't silently typecheck against another.\n   * `params` carries the type's parameters for parameterized natives — `numeric(p,s)`, `varchar(n)`,\n   * `timestamp(p)` — so a driver round-trips `numeric(10,2)` exactly. Order matters; ignored when empty.\n   */\n  | { t: \"native\"; db: string; name: string; params?: (string | number)[] };\n\nexport type GeometryKind =\n  | \"feature\"\n  | \"point\"\n  | \"line\"\n  | \"polygon\"\n  | \"multipoint\"\n  | \"multiline\"\n  | \"multipolygon\"\n  | \"collection\";\n\n// --- Constructors (ergonomic, and a single place to enforce the fold invariants) ----------------\n\nexport const scalar = (name: ScalarName): PortableType => ({\n  t: \"scalar\",\n  name,\n});\nexport const literal = (value: string | number | boolean): PortableType => ({\n  t: \"literal\",\n  value,\n});\n\n/** `option<T>` — but `option<any>` collapses to `any` (any already admits NONE), matching ddl.ts. */\nexport const option = (inner: PortableType): PortableType =>\n  inner.t === \"scalar\" && inner.name === \"any\" ? inner : { t: \"option\", inner };\n\n/**\n * `T | null` — with the fold rule `nullable(option(X))` -> `option(nullable(X))` so\n * `.optional().nullable()` ≡ `.nullish()`, and `nullable(any)` collapses to `any`.\n */\nexport const nullable = (inner: PortableType): PortableType => {\n  if (inner.t === \"scalar\" && inner.name === \"any\") return inner;\n  if (inner.t === \"option\")\n    return { t: \"option\", inner: nullable(inner.inner) };\n  return { t: \"nullable\", inner };\n};\n\nexport const array = (elem: PortableType, size?: number): PortableType => ({\n  t: \"array\",\n  elem,\n  ...(size !== undefined ? { size } : {}),\n});\nexport const union = (members: PortableType[]): PortableType =>\n  members.length === 1 ? members[0] : { t: \"union\", members };\nexport const record = (tables: string[]): PortableType => ({\n  t: \"record\",\n  tables,\n});\n"],"mappings":";AAwDO,SAAS,gBACd,QACA,OACiB;AACjB,SAAO;AAAA,IACL,WAAW;AAAA,IACX;AAAA,IACA,MAAM,QAAQ,KAAK;AACjB,YAAM,MAAM,OAAO,UAAU,aAAa,MAAM,MAAM,GAAG,IAAI;AAC7D,aAAO,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,GAAG;AAAA,IACxC;AAAA,EACF;AACF;AAGO,SAAS,kBAAkB,GAAkC;AAClE,SACE,OAAO,MAAM,YACb,MAAM,QACL,EAA8B,cAAc;AAEjD;;;ACYO,IAAM,SAAS,CAAC,UAAoC;AAAA,EACzD,GAAG;AAAA,EACH;AACF;AACO,IAAM,UAAU,CAAC,WAAoD;AAAA,EAC1E,GAAG;AAAA,EACH;AACF;AAGO,IAAM,SAAS,CAAC,UACrB,MAAM,MAAM,YAAY,MAAM,SAAS,QAAQ,QAAQ,EAAE,GAAG,UAAU,MAAM;AAMvE,IAAM,WAAW,CAAC,UAAsC;AAC7D,MAAI,MAAM,MAAM,YAAY,MAAM,SAAS,MAAO,QAAO;AACzD,MAAI,MAAM,MAAM;AACd,WAAO,EAAE,GAAG,UAAU,OAAO,SAAS,MAAM,KAAK,EAAE;AACrD,SAAO,EAAE,GAAG,YAAY,MAAM;AAChC;AAEO,IAAM,QAAQ,CAAC,MAAoB,UAAiC;AAAA,EACzE,GAAG;AAAA,EACH;AAAA,EACA,GAAI,SAAS,SAAY,EAAE,KAAK,IAAI,CAAC;AACvC;AACO,IAAM,QAAQ,CAAC,YACpB,QAAQ,WAAW,IAAI,QAAQ,CAAC,IAAI,EAAE,GAAG,SAAS,QAAQ;AACrD,IAAM,SAAS,CAAC,YAAoC;AAAA,EACzD,GAAG;AAAA,EACH;AACF;","names":[]}