@lunora/values 0.0.0 → 1.0.0-alpha.1

package/dist/index.d.mts

@@ -0,0 +1,417 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+type ValidationPath = ReadonlyArray<number | string>;
+/**
+* Thrown by `validator.parse` (or returned inside `safeParse`) when input does
+* not match the validator's shape. `path` walks from the root to the offending
+* value, e.g. `["users", 0, "email"]`.
+*/
+declare class ValidationError extends Error {
+  readonly path: ValidationPath;
+  readonly expected: string;
+  readonly received: string;
+  constructor(message: string, options: {
+    expected: string;
+    path: ValidationPath;
+    received: string;
+  });
+}
+/**
+* Render a short, diagnostic description of a runtime value for the `received`
+* field of a {@link ValidationError}. Primitives carry their concrete (length-
+* capped) literal so messages distinguish `string "7"` from `number 7`;
+* non-plain objects carry their constructor name (e.g. `Date`) so a class
+* instance is not flattened to a bare `"object"`.
+*/
+declare const describeValue: (value: unknown) => string;
+declare const formatPath: (path: ValidationPath) => string;
+/** Branded id type, e.g. `Id&lt;"users">`. */
+type Id<TableName extends string> = string & {
+  readonly __table: TableName;
+};
+/**
+* A JSON Schema fragment (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally
+* a loose bag — a `.check()`/`.meta()` caller contributes keywords like
+* `minLength`/`pattern`/`minimum` that `toJsonSchema` shallow-merges onto the
+* node for the enclosing validator. Mirrors the `JsonSchema` shape exported by
+* `./to-json-schema`; kept structurally identical and local so `v.ts` never
+* imports the converter and the two files stay decoupled.
+*/
+interface JsonSchemaFragment {
+  [keyword: string]: unknown;
+}
+/**
+* Options for a {@link Validator.check} refinement. Lets a predicate carry both
+* a human-facing `message` and an introspectable JSON Schema `schema` fragment
+* (e.g. `{ minLength: 1 }`) so the constraint flows into `toJsonSchema`. The
+* legacy `.check(pred, "message")` string form remains supported.
+*/
+interface CheckOptions {
+  /** Failure message thrown on the `ValidationError` (default `"value matching refinement"`). */
+  message?: string;
+  /** JSON Schema fragment merged onto this validator's node by `toJsonSchema`. */
+  schema?: JsonSchemaFragment;
+}
+/**
+* Options for {@link Validator.meta} — pure metadata with no runtime parsing
+* effect, used to enrich the emitted JSON Schema node (description + constraint
+* keywords) without attaching a predicate.
+*/
+interface MetaOptions {
+  /** A human description merged onto this validator's JSON Schema node. */
+  description?: string;
+  /** JSON Schema fragment merged onto this validator's node by `toJsonSchema`. */
+  schema?: JsonSchemaFragment;
+}
+/**
+* Runtime "kind" tag attached to every validator. Codegen and reflective tools
+* use this to inspect the shape without crawling the closure.
+*/
+type ValidatorKind = "any" | "array" | "bigint" | "boolean" | "bytes" | "date" | "from" | "id" | "literal" | "null" | "number" | "object" | "optional" | "record" | "storage" | "string" | "timestamp" | "union";
+interface Validator<T = unknown> extends StandardSchemaV1<T, T> {
+  readonly __type: T;
+  /**
+  * Attach a refinement predicate. The returned validator parses with the
+  * original rules first; if the result satisfies `predicate` it passes
+  * through, otherwise it throws a {@link ValidationError} carrying
+  * `message` (default: `"value matching refinement"`). Multiple `.check()`
+  * calls chain — every predicate must return true.
+  *
+  * The second argument may be a plain message string (legacy form) or a
+  * {@link CheckOptions} object that additionally carries a JSON Schema
+  * `schema` fragment (e.g. `{ minLength: 1 }`) reflected by `toJsonSchema`.
+  *
+  * Works in any context — argument validators, column validators, or
+  * standalone — so it can encode invariants like
+  * `v.number().check(n => n >= 0)` or
+  * `v.string().check(s => s.length > 0, { message: "non-empty", schema: { minLength: 1 } })`.
+  */
+  check: (predicate: (value: T) => boolean, options?: CheckOptions | string) => Validator<T>;
+  readonly kind: ValidatorKind;
+  /**
+  * Attach pure metadata (description + JSON Schema constraint fragment) with
+  * no effect on runtime parsing. The fragment is shallow-merged onto this
+  * validator's emitted JSON Schema node, composing with any `.check()`
+  * `schema` fragments (later wins on conflicting keys).
+  */
+  meta: (options: MetaOptions) => Validator<T>;
+  parse: (value: unknown) => T;
+  safeParse: (value: unknown) => {
+    error: ValidationError;
+    ok: false;
+  } | {
+    ok: true;
+    value: T;
+  };
+}
+/** Extract the TS type a validator describes (the **select** type). */
+type Infer<V> = V extends Validator<infer T> ? T : never;
+/**
+* Column constraints/defaults collected from the `v.*` modifier chain used
+* inside `defineTable`. Inert in argument position. Persisted on the
+* validator's internal `_meta.column` and mirrored into codegen IR.
+*/
+interface ColumnMeta {
+  /** `.$defaultFn(fn)` — default factory; field is optional on insert. */
+  defaultFn?: () => unknown;
+  /** `.default(value)` — literal default; field is optional on insert. */
+  defaultValue?: unknown;
+  /** Default `true`; `.nullable()` flips it to `false`. */
+  notNull: boolean;
+  /** `.$onUpdateFn(fn)` — recomputed on every patch/replace. */
+  onUpdateFn?: () => unknown;
+  /**
+  * `.serverDefault(fn)` — a SERVER-trusted value factory. Unlike
+  * `.$defaultFn` (which only fills an absent field), this runs on every
+  * insert/update and SILENTLY OVERWRITES any client-supplied value with
+  * `fn({ auth })`, so the column is never client-controllable (e.g.
+  * `ownerId`/`tenantId` stamped from `auth.userId`). Field is optional on
+  * insert. The factory runs server-side with the resolved request auth.
+  */
+  serverDefault?: (context: ServerDefaultContext) => unknown;
+  /** `.unique()` — synthesizes a UNIQUE index. */
+  unique?: boolean;
+}
+/**
+* Context handed to a `.serverDefault(fn)` factory at write time. Carries the
+* resolved request identity so a column can be stamped from the caller
+* (`auth.userId`) rather than trusted from the client. Structurally mirrors the
+* `auth` slice of the server's procedure context without depending on
+* `@lunora/server`.
+*/
+interface ServerDefaultContext {
+  readonly auth: {
+    /** The raw identity claims, or `null` for the anonymous/no-resolver case. */
+    readonly identity: Record<string, unknown> | null;
+    /** The resolved caller id, or `null` when unauthenticated. */
+    readonly userId: null | string;
+  };
+}
+/**
+* Phantom carrier of a column's select/insert types. Never present at runtime;
+* `defineTable` reads it to derive `$inferSelect` / `$inferInsert`.
+*/
+interface Column<TSelect, TInsert> {
+  /** Phantom carrier — type-only, never present at runtime. */
+  readonly __column: {
+    insert: TInsert;
+    select: TSelect;
+  };
+}
+/**
+* A {@link Validator} carrying the chainable column-modifier API. The factories
+* (`v.string()`, …) return this so modifiers are available inside `defineTable`.
+* `TSelect` is the read type; `TInsert` is the write type (modifiers may make it
+* `| undefined`, marking the field optional on insert).
+*/
+interface ColumnValidator<TSelect, TInsert> extends Column<TSelect, TInsert>, Validator<TSelect> {
+  /** Default factory applied in the write layer; field becomes optional on insert. */
+  $defaultFn: (function_: () => TSelect) => ColumnValidator<TSelect, TInsert | undefined>;
+  /** Recompute the field on every patch/replace when not explicitly provided. */
+  $onUpdateFn: (function_: () => TSelect) => ColumnValidator<TSelect, TInsert>;
+  /** Override the inferred select/insert type without changing runtime parsing (e.g. `v.string().$type&lt;Id&lt;"users">>()`). */
+  $type: <TOverride>() => ColumnValidator<TOverride, TOverride>;
+  /** Refinement predicate run after parsing — see {@link Validator.check}. Chainable; preserves column modifiers. */
+  check: (predicate: (value: TSelect) => boolean, options?: CheckOptions | string) => ColumnValidator<TSelect, TInsert>;
+  /** Literal default applied in the write layer; field becomes optional on insert. */
+  default: (value: TSelect) => ColumnValidator<TSelect, TInsert | undefined>;
+  /** Attach JSON Schema metadata — see {@link Validator.meta}. Chainable; preserves column modifiers. */
+  meta: (options: MetaOptions) => ColumnValidator<TSelect, TInsert>;
+  /** Allow SQL NULL — widens the select type to `T | null`. */
+  nullable: () => ColumnValidator<null | TSelect, null | TInsert>;
+  /**
+  * Stamp this column SERVER-side from the request auth on every write,
+  * overwriting any client-supplied value. The field becomes optional on
+  * insert (the server fills it). Use for owner/tenant columns that must never
+  * be client-controllable — e.g. `v.string().serverDefault(({ auth }) => auth.userId)`.
+  */
+  serverDefault: (function_: (context: ServerDefaultContext) => TSelect) => ColumnValidator<TSelect, TInsert | undefined>;
+  /** Enforce a UNIQUE constraint (synthesizes a unique index). */
+  unique: () => ColumnValidator<TSelect, TInsert>;
+}
+/**
+* A time-valued {@link ColumnValidator} (epoch milliseconds). Adds
+* {@link TimestampColumnValidator.defaultNow} so the field can default to the
+* insert-time clock.
+*/
+interface TimestampColumnValidator extends ColumnValidator<number, number> {
+  /** Default to the current epoch-ms (`Date.now()`) at insert time; field becomes optional on insert. */
+  defaultNow: () => ColumnValidator<number, number | undefined>;
+}
+/** The type a validator/column presents on **select** (reads). */
+type InferSelect<V> = V extends Validator<infer T> ? T : never;
+/** The type a validator/column accepts on **insert** (writes). */
+type InferInsert<V> = V extends Column<unknown, infer I> ? I : V extends Validator<infer T> ? T : never;
+/** Derive the read shape of a table's column map. */
+type SelectShape<S extends Record<string, Validator>> = { [K in keyof S]: InferSelect<S[K]> };
+/**
+* Derive the write shape of a table's column map. Columns whose insert type
+* includes `undefined` (via `.default()` / `.$defaultFn()` / `v.optional`)
+* become optional keys.
+*/
+type InsertShape<S extends Record<string, Validator>> = { [K in keyof S as undefined extends InferInsert<S[K]> ? K : never]?: Exclude<InferInsert<S[K]>, undefined> } & { [K in keyof S as undefined extends InferInsert<S[K]> ? never : K]: InferInsert<S[K]> };
+declare const string: () => ColumnValidator<string, string>;
+declare const number: () => ColumnValidator<number, number>;
+/** Epoch-millisecond timestamp (`number`). Pair with `.defaultNow()` for an insert-time clock. */
+declare const timestamp: () => TimestampColumnValidator;
+/** Calendar date stored as an epoch-millisecond `number`. Pair with `.defaultNow()` for an insert-time clock. */
+declare const date: () => TimestampColumnValidator;
+declare const boolean: () => ColumnValidator<boolean, boolean>;
+declare const bigintValidator: () => ColumnValidator<bigint, bigint>;
+declare const nullValidator: () => ColumnValidator<null, null>;
+declare const bytes: () => ColumnValidator<ArrayBuffer, ArrayBuffer>;
+declare const id: <TableName extends string>(tableName: TableName) => ColumnValidator<Id<TableName>, Id<TableName>>;
+/**
+* A reference to a stored R2 object: the column holds the object's **key** (a
+* string), the same key `@lunora/storage` puts/gets by. Functionally it parses
+* like `v.string()`, but the distinct `"storage"` kind lets codegen and the
+* studio join the data model to R2 — the file browser uses it to show which
+* record owns a file and to flag orphaned objects no row references. The
+* optional `bucket` names the typed bucket the key lives in (for app-context
+* signed URLs); omit it for the app's default bucket.
+*/
+declare const storage: (bucket?: string) => ColumnValidator<string, string>;
+declare const literal: <T extends bigint | boolean | number | string | null>(literalValue: T) => ColumnValidator<T, T>;
+declare const array: <V extends Validator>(inner: V) => ColumnValidator<Infer<V>[], Infer<V>[]>;
+type ObjectShape = Record<string, Validator>;
+type ObjectShapeType<S extends ObjectShape> = { [K in keyof S as undefined extends Infer<S[K]> ? K : never]?: Infer<S[K]> } & { [K in keyof S as undefined extends Infer<S[K]> ? never : K]: Infer<S[K]> };
+declare const objectValidator: <S extends ObjectShape>(shape: S) => ColumnValidator<ObjectShapeType<S>, ObjectShapeType<S>>;
+declare const record: <K extends Validator<string>, V extends Validator>(keyValidator: K, valueValidator: V) => ColumnValidator<Record<Infer<K>, Infer<V>>, Record<Infer<K>, Infer<V>>>;
+declare const union: <Vs extends ReadonlyArray<Validator>>(...members: Vs) => ColumnValidator<Infer<Vs[number]>, Infer<Vs[number]>>;
+declare const optional: <V extends Validator>(inner: V) => ColumnValidator<Infer<V> | undefined, Infer<V> | undefined>;
+declare const any: () => ColumnValidator<unknown, unknown>;
+/**
+* Infer the output type of a Standard Schema v1 object. When the schema omits
+* `~standard.types` (it is optional in the spec), falls back to `unknown` so
+* callers always get a usable type rather than `never`.
+*/
+type InferStandardOutput<S extends StandardSchemaV1> = S["~standard"]["types"] extends {
+  output: infer O;
+} ? O : unknown;
+/**
+* Wrap any Standard Schema v1 validator (`zod`, `valibot`, `arktype`, …) so it
+* can be used as an **args** validator in `query`/`mutation`/`action`. The
+* wrapped validator's output type is inferred from `~standard.types.output`
+* when declared; falls back to `unknown` when the schema omits the types field.
+*
+* **Args-only.** `v.from(...)` validators must not be used as table columns —
+* `defineTable` checks the `kind` and throws a clear error if you try.
+*
+* **Sync-only.** Standard Schema allows async `validate`; Lunora args
+* validation is synchronous and throws when a Promise is returned.
+*/
+declare const from: <S extends StandardSchemaV1>(schema: S) => ColumnValidator<InferStandardOutput<S>, InferStandardOutput<S>>;
+/**
+* True when `validator` is `v.from(...)` or structurally wraps one through
+* `v.optional` / `v.array` / `v.object` / `v.record` / `v.union`. `defineTable`
+* uses it to reject Standard-Schema-backed validators anywhere in a column —
+* not just at the top level — since they are args-only and have no SQL column
+* type. The nested children live on the validator's `_meta` (`inner`, `shape`,
+* `members`, `keyValidator`/`valueValidator`) and are themselves validators.
+*/
+declare const isOrWrapsFromValidator: (validator: Validator) => boolean;
+/**
+* The inner validator wrapped by `v.optional(inner)`, or `undefined` for any
+* other validator. The nested child lives on the validator's internal `_meta`
+* bag; this accessor keeps that knowledge inside `@lunora/values` (the package
+* that owns validator internals) so consumers don't reach into `_meta`
+* themselves. Used by `@lunora/server`'s `defineEnv` to coerce through a leading
+* `v.optional(...)`.
+* @returns The inner validator if `v.optional(...)`, otherwise `undefined`.
+*/
+declare const optionalInner: (validator: Validator) => Validator | undefined;
+/**
+* Validator/codec namespace. Each factory returns a {@link Validator} with a
+* runtime `parse`/`safeParse` plus a phantom `__type` field for inference.
+*/
+declare const v: {
+  any: typeof any;
+  array: typeof array;
+  bigint: typeof bigintValidator;
+  boolean: typeof boolean;
+  bytes: typeof bytes;
+  date: typeof date;
+  from: typeof from;
+  id: typeof id;
+  literal: typeof literal;
+  null: typeof nullValidator;
+  number: typeof number;
+  object: typeof objectValidator;
+  optional: typeof optional;
+  record: typeof record;
+  storage: typeof storage;
+  string: typeof string;
+  timestamp: typeof timestamp;
+  union: typeof union;
+};
+/**
+* A JSON Schema node (Draft 2020-12 / OpenAPI 3.1 compatible). Intentionally a
+* loose bag — Lunora only emits a known subset, but consumers (OpenAPI/OpenRPC
+* builders, Swagger UI, form generators) treat it as an opaque schema object.
+*/
+interface JsonSchema {
+  [keyword: string]: unknown;
+}
+/**
+* Structural reader over a validator-like node. The shared mapping algorithm
+* ({@link jsonSchemaFromNode}) is parameterized by this interface so the same
+* switch/recursion serves both inputs Lunora maps to JSON Schema: the runtime
+* `@lunora/values` validator (children + metadata live on `_meta`), and the
+* build-time validator IR consumed by codegen (children are plain fields, with
+* no runtime metadata — so `constraints`/`isNullable` may be inert there).
+*
+* A reader normalizes a `TNode` to the small set of children/leaves the mapper
+* recurses over. Composite accessors (`inner`/`shape`/`members`/`valueChild`)
+* return the same `TNode` type so the mapper can recurse uniformly; leaf concerns
+* that differ between the two sources — how a literal's `const` is computed,
+* whether a `.check()`/`.meta()` constraint fragment exists, whether `.nullable()`
+* was applied — are delegated wholesale to the reader.
+*/
+interface SchemaNodeReader<TNode> {
+  /**
+  * The `.check()`/`.meta()` JSON Schema fragment to shallow-merge onto the
+  * node, or `undefined` when none (the IR side never carries one). Constraint
+  * keys win over the base on conflict so a refinement can tighten — never
+  * silently weaken — the schema.
+  */
+  constraints: (node: TNode) => JsonSchema | undefined;
+  /** Inner child of an `array`/`optional` node. May be absent on the IR side. */
+  inner: (node: TNode) => TNode | undefined;
+  /** Whether `.nullable()` was applied (runtime: `_meta.column.notNull === false`). */
+  isNullable: (node: TNode) => boolean;
+  /** Discriminating validator kind. */
+  kind: (node: TNode) => ValidatorKind;
+  /**
+  * The JSON Schema `const` fragment for a `literal` node. Computed differently
+  * per source — runtime reads the live `_meta.value`; the IR parses verbatim
+  * source text — so the reader owns it entirely.
+  */
+  literalSchema: (node: TNode) => JsonSchema;
+  /** Member nodes of a `union`. */
+  members: (node: TNode) => ReadonlyArray<TNode>;
+  /** Property nodes of an `object`, keyed by property name. */
+  shape: (node: TNode) => Record<string, TNode>;
+  /** Target table name of an `id` node. */
+  tableName: (node: TNode) => unknown;
+  /** Value-child of a `record` node. May be absent on the IR side. */
+  valueChild: (node: TNode) => TNode | undefined;
+}
+/**
+* The single validator→JSON-Schema mapping algorithm, shared by the runtime
+* `toJsonSchema` (over `@lunora/values` validators) and codegen's IR-backed
+* mapper. It walks a node recursively via the supplied {@link SchemaNodeReader},
+* so nested objects/arrays/unions/records are fully expanded (never collapsed to
+* one level).
+*
+* `date`/`timestamp` are epoch-millisecond numbers in Lunora (not ISO strings),
+* so they schema as integers; `bigint` schemas as an int64 (JSON has no bigint
+* type, so `format: int64` is the conventional OpenAPI carrier); `bytes` is an
+* `ArrayBuffer`, surfaced as base64 per JSON Schema 2020-12 content encoding.
+*
+* A `.check()`/`.meta()` JSON Schema fragment (when the reader exposes one) is
+* shallow-merged onto the node — constraint keys win on conflict. A `.nullable()`
+* node widens to also accept `null`; constraints describe the underlying value,
+* so they ride inside the non-null branch rather than on the wrapping `anyOf`.
+*/
+declare const jsonSchemaFromNode: <TNode>(node: TNode, reader: SchemaNodeReader<TNode>) => JsonSchema;
+/**
+* Build `{ type: "object", properties, required, additionalProperties: false }`
+* from a node shape. A `v.optional(...)` property is the only thing that drops
+* out of `required`; every other property is required.
+*/
+declare const objectSchemaFromNodes: <TNode>(shape: Record<string, TNode>, reader: SchemaNodeReader<TNode>) => JsonSchema;
+/**
+* Convert a single `@lunora/values` validator to a JSON Schema node (Draft
+* 2020-12 / OpenAPI 3.1). A thin wrapper over the shared {@link jsonSchemaFromNode}
+* core with the runtime {@link validatorReader}; see that core for the full
+* kind→schema mapping (date/timestamp → epoch-ms integer, bigint → int64, bytes →
+* base64, id → annotated string, literal → `const`, optionality via the parent
+* `required` list, `.nullable()` widening, `.check()`/`.meta()` constraint merge).
+*/
+declare const toJsonSchema: (validator: Validator) => JsonSchema;
+/**
+* Convert a function's argument validators (a name-to-validator map) into a
+* single JSON Schema object. Non-`optional` arguments are `required`; the result
+* is the request `params`/`args` schema an OpenAPI operation or OpenRPC method
+* advertises. An empty arg map yields an empty (but valid) object schema.
+*/
+declare const argsToJsonSchema: (args: Record<string, Validator>) => JsonSchema;
+/** Map of validators describing a record of named fields (a function's args, a step's args, an HTTP query/body/params). */
+type ValidatorMap = Record<string, Validator>;
+/** Infer the object type from a {@link ValidatorMap} — optional validators (`v.optional`) become optional keys. */
+type InferValidatorMap<A extends ValidatorMap> = { [K in keyof A as undefined extends Infer<A[K]> ? K : never]?: Infer<A[K]> } & { [K in keyof A as undefined extends Infer<A[K]> ? never : K]: Infer<A[K]> };
+/**
+* Validate each declared field of `source` through its validator, re-wrapping
+* any {@link ValidationError} with a `label.&lt;key>:` prefix and the rebuilt path
+* `[key, ...error.path]` so the failure points at the offending field. Optional
+* fields absent from the source are skipped (so `v.optional` passes and a
+* required validator fails on `undefined`).
+*
+* The single arg-/field-parsing implementation shared across the framework — the
+* procedure builder (label `args`), the HTTP route builder (`searchParams` /
+* `body` / `params`), and `@lunora/workflow`'s reusable steps (`step args`) — so
+* the error-prefixing and optional-skip semantics can't drift apart. The `label`
+* is the only thing each caller varies.
+*/
+declare const parseValidatorMap: (validators: ValidatorMap, source: Record<string, unknown>, label: string) => Record<string, unknown>;
+declare const VERSION = "0.0.0";
+export { type CheckOptions, type Column, type ColumnMeta, type ColumnValidator, type Id, type Infer, type InferInsert, type InferSelect, type InferStandardOutput, type InferValidatorMap, type InsertShape, type JsonSchema, type JsonSchemaFragment, type MetaOptions, type SchemaNodeReader, type SelectShape, type ServerDefaultContext, type TimestampColumnValidator, VERSION, ValidationError, type ValidationPath, type Validator, type ValidatorKind, type ValidatorMap, argsToJsonSchema, describeValue, formatPath, isOrWrapsFromValidator, jsonSchemaFromNode, objectSchemaFromNodes, optionalInner, parseValidatorMap, toJsonSchema, v };