@better-schemic/core 0.1.0-alpha.1

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,40 @@
+# @better-schemic/core
+
+The dialect-neutral engine behind [Better-schemic](https://github.com/NONSTANDARDCODE/better-schemic) — schema-as-code
+for SurrealDB. It defines the **driver contract**, the **portable schema IR**, and the
+**diff / migration / snapshot** engine that the CLI runs over the SurrealDB driver.
+
+`@better-schemic/core` has **no authoring surface of its own** — you don't write schemas with it directly.
+The SurrealDB driver provides that:
+
+- [`@better-schemic/surrealdb`](../../drivers/surrealdb#readme) gives you the `s.*` authoring API and emits SurrealQL DDL.
+- [`@better-schemic/cli`](../cli#readme) gives you the `better-schemic` / `sc` commands.
+
+The CLI loads the driver from `better-schemic.config.ts` and orchestrates this engine generically — author →
+diff → generate → migrate.
+
+## When you touch it directly
+
+Most projects depend on `@better-schemic/core` only transitively, through the CLI and a driver. The one
+piece you import from it is the config helper:
+
+```ts
+import { defineConfig } from "@better-schemic/core/config";
+// pair it with a connection factory from the driver
+// (e.g. surrealConnection from @better-schemic/surrealdb)
+```
+
+With bun, npm, or yarn, `@better-schemic/core` is pulled in transitively (it's a dependency of the CLI and
+every driver) — you don't install it directly. Under pnpm's strict `node_modules` the transitive copy
+isn't reachable from your `better-schemic.config.ts`, so add it explicitly: `pnpm add @better-schemic/core`.
+
+See your driver's README for the full `defineConfig({ connections: { … } })` setup.
+
+## Docs
+
+Guides, concepts, and reference live at [docs](https://github.com/NONSTANDARDCODE/better-schemic). This package is part of
+the [Better-schemic](https://github.com/NONSTANDARDCODE/better-schemic) toolkit.
+
+## License
+
+[MIT](./LICENSE) © Vertio Solutions

package/lib/authoring.d.ts

@@ -0,0 +1,114 @@
+import * as z from 'zod';
+export { S as SecretProvider, a as SecretRef, e as env, i as isSecretRef, s as secret } from './secrets-BETi5p8g.js';
+
+/** 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);
+    /**
+     * Standard Schema interface (https://standardschema.dev), forwarded from the wrapped Zod schema so a
+     * Better-schemic field IS a drop-in Standard Schema — it slots straight into any consumer (tRPC, TanStack
+     * Form/Router, …) without unwrapping. `validate` runs the DECODE direction (wire -> app), matching
+     * `decode`/`parse`. We wrap Zod by composition (not subclassing), so this getter is what carries the
+     * `~standard` contract across the wrapper; without it only `field.schema` would be compliant.
+     */
+    get ["~standard"](): S["~standard"];
+    /** 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>>>;
+    /** Zod's `.spa` alias for {@link safeParseAsync} (drop-in). */
+    spa(value: unknown): Promise<z.ZodSafeParseResult<z.core.output<S>>>;
+    /** Does this field accept `undefined`? (Zod reflection.) */
+    isOptional(): boolean;
+    /** Does this field accept `null`? (Zod reflection.) */
+    isNullable(): boolean;
+    /** Read back the description set via {@link describe} / {@link meta}. */
+    get description(): string | undefined;
+    /** JSON Schema for this field's wire shape (delegates to `z.toJSONSchema`). */
+    toJSONSchema(): z.core.ZodStandardJSONSchemaPayload<S>;
+    /** Register the wrapped schema in a Zod registry for metadata interop; returns the field. */
+    register(...args: Parameters<S["register"]>): this;
+    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 `.nonoptional()` — require a value (strips an `.optional()`). */
+    nonoptional(): SFieldBase<z.ZodNonOptional<S>, Flags, N>;
+    /** Zod `.exactOptional()` — optional that rejects an explicit `undefined`. */
+    exactOptional(): SFieldBase<z.ZodExactOptional<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,242 @@
+import {
+  env,
+  isSecretRef,
+  secret
+} from "./chunk-26D7WX7Q.js";
+
+// 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;
+  }
+  schema;
+  native;
+  /**
+   * Standard Schema interface (https://standardschema.dev), forwarded from the wrapped Zod schema so a
+   * Better-schemic field IS a drop-in Standard Schema — it slots straight into any consumer (tRPC, TanStack
+   * Form/Router, …) without unwrapping. `validate` runs the DECODE direction (wire -> app), matching
+   * `decode`/`parse`. We wrap Zod by composition (not subclassing), so this getter is what carries the
+   * `~standard` contract across the wrapper; without it only `field.schema` would be compliant.
+   */
+  get ["~standard"]() {
+    return this.schema["~standard"];
+  }
+  // --- 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's `.spa` alias for {@link safeParseAsync} (drop-in). */
+  spa(value) {
+    return this.safeParseAsync(value);
+  }
+  // --- Zod reflection + interop (drop-in for `z.*`), delegated to the inner schema ---
+  /** Does this field accept `undefined`? (Zod reflection.) */
+  isOptional() {
+    return this.schema.isOptional();
+  }
+  /** Does this field accept `null`? (Zod reflection.) */
+  isNullable() {
+    return this.schema.isNullable();
+  }
+  /** Read back the description set via {@link describe} / {@link meta}. */
+  get description() {
+    return this.schema.description;
+  }
+  /** JSON Schema for this field's wire shape (delegates to `z.toJSONSchema`). */
+  toJSONSchema() {
+    return z.toJSONSchema(this.schema);
+  }
+  /** Register the wrapped schema in a Zod registry for metadata interop; returns the field. */
+  register(...args) {
+    Reflect.apply(this.schema.register, this.schema, args);
+    return this;
+  }
+  // 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 `.nonoptional()` — require a value (strips an `.optional()`). */
+  nonoptional() {
+    return this.rebuild(this.schema.nonoptional(), this.native);
+  }
+  /** Zod `.exactOptional()` — optional that rejects an explicit `undefined`. */
+  exactOptional() {
+    return this.rebuild(this.schema.exactOptional(), 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,
+  env,
+  isSecretRef,
+  objectFieldsRegistry,
+  secret,
+  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  /**\n   * Standard Schema interface (https://standardschema.dev), forwarded from the wrapped Zod schema so a\n   * Better-schemic field IS a drop-in Standard Schema — it slots straight into any consumer (tRPC, TanStack\n   * Form/Router, …) without unwrapping. `validate` runs the DECODE direction (wire -> app), matching\n   * `decode`/`parse`. We wrap Zod by composition (not subclassing), so this getter is what carries the\n   * `~standard` contract across the wrapper; without it only `field.schema` would be compliant.\n   */\n  get [\"~standard\"](): S[\"~standard\"] {\n    return this.schema[\"~standard\"];\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  /** Zod's `.spa` alias for {@link safeParseAsync} (drop-in). */\n  spa(value: unknown) {\n    return this.safeParseAsync(value);\n  }\n\n  // --- Zod reflection + interop (drop-in for `z.*`), delegated to the inner schema ---\n  /** Does this field accept `undefined`? (Zod reflection.) */\n  isOptional(): boolean {\n    return this.schema.isOptional();\n  }\n  /** Does this field accept `null`? (Zod reflection.) */\n  isNullable(): boolean {\n    return this.schema.isNullable();\n  }\n  /** Read back the description set via {@link describe} / {@link meta}. */\n  get description(): string | undefined {\n    return this.schema.description;\n  }\n  /** JSON Schema for this field's wire shape (delegates to `z.toJSONSchema`). */\n  toJSONSchema() {\n    return z.toJSONSchema(this.schema);\n  }\n  /** Register the wrapped schema in a Zod registry for metadata interop; returns the field. */\n  register(...args: Parameters<S[\"register\"]>): this {\n    Reflect.apply(this.schema.register, this.schema, args);\n    return this;\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 `.nonoptional()` — require a value (strips an `.optional()`). */\n  nonoptional(): SFieldBase<z.ZodNonOptional<S>, Flags, N> {\n    return this.rebuild(this.schema.nonoptional(), this.native);\n  }\n  /** Zod `.exactOptional()` — optional that rejects an explicit `undefined`. */\n  exactOptional(): SFieldBase<z.ZodExactOptional<S>, Flags, N> {\n    return this.rebuild(this.schema.exactOptional(), 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\n// Secret-ref authoring helpers (env/secret) live here on the SIDE-EFFECT-FREE authoring subpath, so a\n// driver's authoring index can re-export them without dragging the engine. (Also on the main index.)\nexport {\n  env,\n  isSecretRef,\n  type SecretProvider,\n  type SecretRef,\n  secret,\n} from \"./secrets\";\n"],"mappings":"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","names":[]}

package/lib/chunk-26D7WX7Q.js

@@ -0,0 +1,31 @@
+// src/secrets.ts
+function env(name) {
+  return { kind: "env", name };
+}
+function secret(name) {
+  return { kind: "secret", name };
+}
+function isSecretRef(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return (r.kind === "env" || r.kind === "secret") && typeof r.name === "string";
+}
+var envSecretProvider = {
+  resolve(ref) {
+    const value = process.env[ref.name];
+    if (value === void 0) {
+      throw new Error(
+        `better-schemic: secret ${ref.kind}(${JSON.stringify(ref.name)}) is not set in the environment`
+      );
+    }
+    return value;
+  }
+};
+
+export {
+  env,
+  secret,
+  isSecretRef,
+  envSecretProvider
+};
+//# sourceMappingURL=chunk-26D7WX7Q.js.map

package/lib/chunk-26D7WX7Q.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/secrets.ts"],"sourcesContent":["// Secret references for secret-bearing DDL (e.g. SurrealDB `DEFINE ACCESS` keys). A `SecretRef` is an\n// authoring-time PLACEHOLDER — it never carries the secret value. The value is resolved at APPLY time by\n// the CLI through a `SecretProvider` and handed to the database as a BOUND PARAMETER (never spliced into\n// the DDL string), so secrets stay out of the schema source, the snapshot, and the migration files.\n//\n//   key: env(\"JWT_SECRET\")            // resolved from process.env at apply\n//   key: secret(\"jwt/signing-key\")    // resolved from the configured SecretProvider at apply\n//\n// The clause carrying a `SecretRef` is marked `writeOnly` in the IR (diff-excluded + snapshot-omitted),\n// so a redacted secret never reads as drift; because the diff can't see the value, rotation is the\n// explicit `apply --rotate-keys` (it can't be auto-detected).\n\n/** An author-time reference to a secret, resolved to its value at apply time — never the value itself. */\nexport interface SecretRef {\n  /** `env` → resolved from `process.env`; `secret` → resolved from the configured {@link SecretProvider}. */\n  readonly kind: \"env\" | \"secret\";\n  /** The environment-variable / secret name to resolve at apply. */\n  readonly name: string;\n}\n\n/** Bind a value to an environment variable, resolved at apply from `process.env[name]`. */\nexport function env(name: string): SecretRef {\n  return { kind: \"env\", name };\n}\n\n/** Bind a value to a named secret, resolved at apply from the configured {@link SecretProvider}. */\nexport function secret(name: string): SecretRef {\n  return { kind: \"secret\", name };\n}\n\n/** Runtime guard: is `v` a {@link SecretRef} (vs a raw `string` literal key)? */\nexport function isSecretRef(v: unknown): v is SecretRef {\n  if (typeof v !== \"object\" || v === null) return false;\n  const r = v as Partial<SecretRef>;\n  return (\n    (r.kind === \"env\" || r.kind === \"secret\") && typeof r.name === \"string\"\n  );\n}\n\n/**\n * Resolves {@link SecretRef}s to their values at apply time. Pluggable: the default\n * {@link envSecretProvider} reads every ref from `process.env`; swap it for a vault / file source by\n * passing a custom provider to the apply layer. The resolved value is handed to the DB as a BOUND\n * PARAMETER — never string-spliced into the DDL.\n */\nexport interface SecretProvider {\n  resolve(ref: SecretRef): string | Promise<string>;\n}\n\n/** Default provider: resolves every {@link SecretRef} from `process.env[ref.name]`; throws if unset. */\nexport const envSecretProvider: SecretProvider = {\n  resolve(ref: SecretRef): string {\n    const value = process.env[ref.name];\n    if (value === undefined) {\n      throw new Error(\n        `better-schemic: secret ${ref.kind}(${JSON.stringify(ref.name)}) is not set in the environment`,\n      );\n    }\n    return value;\n  },\n};\n"],"mappings":";AAqBO,SAAS,IAAI,MAAyB;AAC3C,SAAO,EAAE,MAAM,OAAO,KAAK;AAC7B;AAGO,SAAS,OAAO,MAAyB;AAC9C,SAAO,EAAE,MAAM,UAAU,KAAK;AAChC;AAGO,SAAS,YAAY,GAA4B;AACtD,MAAI,OAAO,MAAM,YAAY,MAAM,KAAM,QAAO;AAChD,QAAM,IAAI;AACV,UACG,EAAE,SAAS,SAAS,EAAE,SAAS,aAAa,OAAO,EAAE,SAAS;AAEnE;AAaO,IAAM,oBAAoC;AAAA,EAC/C,QAAQ,KAAwB;AAC9B,UAAM,QAAQ,QAAQ,IAAI,IAAI,IAAI;AAClC,QAAI,UAAU,QAAW;AACvB,YAAM,IAAI;AAAA,QACR,0BAA0B,IAAI,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC;AAAA,MAChE;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACF;","names":[]}