@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/dist/bulk-upsert.d.ts

@@ -0,0 +1,282 @@
+/**
+ * EPIC 10 — batched upsert for ingestion (`upsertMany`).
+ *
+ * The whole logical input is validated HERE, before the query builder assembles
+ * a single statement, so a malformed feed never reaches the database as a
+ * partial write. Everything in this module is a pure function over the runtime
+ * metadata and the already-compiled rows: the rows themselves are compiled by
+ * the query builder's existing `compileCreateRows`, so validators, string-enum
+ * membership checks, app-side defaults and `@updatedAt` stamping all come from
+ * the one write path (constitution rule 6 — no second coercion path).
+ *
+ * The two decisions this file exists to keep honest:
+ *
+ * 1. **Duplicate conflict keys are refused, not resolved — and "duplicate"
+ *    means what the DATABASE means.** A batch is accepted only when its
+ *    conflict keys are provably distinct under the database's own equality.
+ *    Two routes get there, and {@link assertConflictKeysAreComparable} picks
+ *    one per call:
+ *
+ *      - **Route 1 — the ORM's own check, which spans parameter chunks.**
+ *        {@link assertNoDuplicateConflictKeys} compares the encoded values of
+ *        every row in the batch, in input order, before it is split into
+ *        statements. That answer is the database's answer only where the
+ *        column's equality IS byte equality, so route 1 is available only when
+ *        {@link conflictKeyComparisonOf} says so for every target column: no
+ *        folding collation, no folding scalar, and no `@db.*` native type
+ *        outside the measured {@link BYTE_EXACT_NATIVE_TYPES}.
+ *      - **Route 2 — the engine's own comparison, inside ONE statement.**
+ *        Postgres refuses a doubled key with SQLSTATE 21000 under the real
+ *        column, which catches every fold the ORM cannot see: a `char(n)` pad,
+ *        a `uuid` case difference, `numeric` scale, `timestamp(0)` and `date`
+ *        truncation, `real` narrowing, `citext`, a nondeterministic collation.
+ *        It ends at the statement boundary. Rows in two statements are never
+ *        compared, and the second statement silently updates what the first
+ *        inserted.
+ *
+ *    Neither route available means the batch is refused before a statement is
+ *    built. Mysql's default `utf8mb4_0900_ai_ci` and a sqlite `COLLATE NOCASE`
+ *    column both fold keys and both keep the LAST row without an error, so
+ *    those calls now refuse instead of guessing.
+ *
+ *    **The strength of that guarantee, stated exactly.** Route 2 is the
+ *    database's own answer and carries no condition. Route 1 is only as true
+ *    as the schema: it reads `@collation` and `@db.*` and never asks the live
+ *    database what the column really is. Where the physical column disagrees
+ *    with what the schema declares — a table or database default, an ALTER
+ *    applied outside migrations, a restored dump, a column created before the
+ *    annotation — route 1 can accept a batch the database then folds. Nothing
+ *    in this module detects that, and nothing here claims to.
+ * 2. **The affected count is not the driver's number.** Mysql's ON DUPLICATE
+ *    KEY convention counts an insert 1, a changed update 2 and an unchanged
+ *    update 0 — measured 3 for a four-row batch on 8.4.11. That is not a row
+ *    count and is never presented as one.
+ */
+import type { SqlDialect } from "@vibeorm/sql";
+import type { FieldMeta, ModelMeta } from "./model-meta.ts";
+/** What `upsertMany` resolves to. */
+export type UpsertManyResult = {
+    /**
+     * Rows the database was asked to insert-or-update: one per input row, after
+     * duplicate-conflict-key validation. Every one of them was either inserted or
+     * updated — the statement carries no DO NOTHING arm and the whole operation
+     * is atomic. NOT a count of rows whose values changed, and it does not
+     * distinguish inserts from updates.
+     */
+    readonly count: number;
+    /**
+     * The driver's raw affected-row number, and only where that number IS a row
+     * count ({@link affectedRowsAreRowCounts}). `null` on mysql.
+     */
+    readonly affectedRows: number | null;
+};
+/**
+ * Does this dialect's affected-row number mean "rows written"?
+ *
+ * Postgres/pglite/sqlite: yes — a four-row `ON CONFLICT DO UPDATE` batch of
+ * 2 unchanged + 1 changed + 1 insert reports 4. Mysql: no — the same batch
+ * reports 3, because ON DUPLICATE KEY scores an insert 1, a changed update 2
+ * and an unchanged update 0. Both measured, see notes-epic10.md.
+ */
+export declare function affectedRowsAreRowCounts(params: {
+    dialect: SqlDialect;
+}): boolean;
+/** The arbiter an `upsertMany` call selected. */
+export type UpsertConflictTarget = {
+    readonly kind: "columns";
+    readonly fields: readonly FieldMeta[];
+} | {
+    readonly kind: "constraint";
+    readonly constraint: string;
+};
+/**
+ * Every distinct way this model can address one row, as a column-set signature.
+ * Used to check that a conflict target names a REAL unique group, and to decide
+ * whether mysql's untargetable ON DUPLICATE KEY could fire on something else.
+ */
+export declare function uniqueGroupSignatures(params: {
+    model: ModelMeta;
+}): ReadonlySet<string>;
+/**
+ * `conflictTarget` → the arbiter. A field-name array must name a DECLARED
+ * unique group: a target the database has no unique index for cannot arbitrate
+ * anything, and postgres would refuse it at execution time anyway ("there is no
+ * unique or exclusion constraint matching the ON CONFLICT specification") —
+ * refusing at build time is the same answer, earlier and typed.
+ */
+export declare function resolveUpsertConflictTarget(params: {
+    model: ModelMeta;
+    target: unknown;
+}): UpsertConflictTarget;
+/**
+ * Mysql's `ON DUPLICATE KEY UPDATE` fires on ANY unique index, so a selected
+ * conflict target is not enforceable there. With exactly one unique group there
+ * is nothing else it could fire on and the contract holds; with more, the call
+ * is refused unless the caller acknowledges the widening. This EPIC never
+ * claims mysql enforces the target.
+ */
+export declare function assertConflictTargetIsEnforceable(params: {
+    dialect: SqlDialect;
+    model: ModelMeta;
+    allowAnyUniqueConflict: boolean;
+}): void;
+/**
+ * `update` → the fields the conflict arm overwrites from the incoming row.
+ *
+ * Refused: a conflict-target column (the arbiter is not a mutable field) and
+ * the `@@policy` tenant field (tenant identity is not a mutable field). The
+ * list is explicit by design — a "everything else" default would rewrite
+ * columns a caller never mentioned.
+ */
+export declare function resolveUpsertUpdateFields(params: {
+    model: ModelMeta;
+    update: unknown;
+    targetColumns: ReadonlySet<string>;
+    skipUpdatedAt: boolean;
+}): readonly FieldMeta[];
+/**
+ * Every row must BIND every conflict-target column and every updated column.
+ *
+ * The target columns are the B1 rule batched: a row that does not bind the
+ * arbiter can never conflict on the row the caller meant. The update columns
+ * are the destructive case — `SET col = <incoming row>.col` on a row that
+ * omitted the column would write the column DEFAULT (or NULL) over a live
+ * value. Columns that are neither may still be omitted per row: they take the
+ * column default on insert and keep their stored value on conflict.
+ */
+export declare function assertUpsertRowsBindColumns(params: {
+    model: ModelMeta;
+    compiled: readonly Readonly<Record<string, unknown>>[];
+    targetColumns: readonly string[];
+    updateFields: readonly FieldMeta[];
+}): void;
+/**
+ * Refuse a batch that proposes the same conflict key twice, BYTE-wise.
+ *
+ * Not a `firstWins`/`lastWins` resolution, because the engines disagree about
+ * what such a batch even means (postgres: SQLSTATE 21000; mysql and sqlite:
+ * silent last-wins). Byte equality is a SUBSET of every collation's equality —
+ * no collation can call two identical byte strings different — so this check
+ * never refuses a batch the database would have accepted, and it covers the
+ * whole batch, parameter chunks included. Where it is not the WHOLE answer,
+ * {@link assertConflictKeysAreComparable} refuses rather than guessing.
+ */
+export declare function assertNoDuplicateConflictKeys(params: {
+    model: ModelMeta;
+    compiled: readonly Readonly<Record<string, unknown>>[];
+    targetColumns: readonly string[];
+}): void;
+/**
+ * Refuse a batch that doubles a unique group the arbiter does NOT name, on a
+ * dialect whose upsert has no arbiter at all.
+ *
+ * `ON DUPLICATE KEY UPDATE` resolves through whichever unique index the
+ * incoming row happens to match, so two rows carrying one `email` — distinct
+ * `id`s, an untouched conflict target — are not two rows: the second UPDATES
+ * the first and one of them silently disappears, with `ROW_COUNT()` reporting
+ * a number that hides it. Postgres and sqlite arbitrate on the named target
+ * only, so the second row violates the other index and the whole batch fails
+ * loudly; nothing is refused for them here.
+ *
+ * `allowAnyUniqueConflict` does NOT authorise this. That flag acknowledges
+ * that a SINGLE incoming row may be resolved through an index other than the
+ * one named — a widening of which stored row is replaced. It was never an
+ * acceptance of two submitted rows collapsing into one, which is a row the
+ * caller sent and the database does not have.
+ *
+ * Comparison is byte equality, deliberately: byte-identical values are equal
+ * under every collation and every native type, so this can only refuse a batch
+ * the database would itself have folded. Values a collation might fold while
+ * their bytes differ are the opaque case, and
+ * {@link assertConflictKeysAreComparable} already governs it.
+ *
+ * Rows that leave any of the group's columns unbound or NULL are skipped: an
+ * unbound column takes a default this layer cannot know, and mysql's unique
+ * indexes never collide on NULL.
+ */
+export declare function assertNoDuplicateSecondaryUniques(params: {
+    dialect: SqlDialect;
+    model: ModelMeta;
+    compiled: readonly Readonly<Record<string, unknown>>[];
+    targetColumns: readonly string[];
+}): void;
+/** How a single conflict-target column's equality can be established. */
+export type ConflictKeyComparison = 
+/** The encoded JavaScript values compare exactly as the column does. */
+"byte"
+/** Only the database knows: a collation, a scale or a precision decides. */
+ | "database";
+/**
+ * Which comparison decides whether two rows address the same stored row
+ * through this column.
+ *
+ * A declared `@db.*` native type is read FIRST and outranks everything the
+ * scalar implies, because the physical column pads, rounds, narrows or
+ * case-folds before a collation is ever consulted — and no annotation
+ * elsewhere can undo that. Only the measured types in
+ * {@link BYTE_EXACT_NATIVE_TYPES} pass; anything else is opaque, including a
+ * type this project has never run.
+ *
+ * Text (and enum members, which live in a text column on sqlite and mysql)
+ * then follows the column's collation: a declared `@collation` is believed on
+ * every dialect, because it is the schema's own statement about the column,
+ * and an undeclared one falls back to the dialect's default. Other scalars
+ * follow the dialect's folding list — `Decimal` is there on postgres and mysql
+ * because `numeric`/`DECIMAL` equality ignores trailing zeros while the
+ * encoded value is the string the caller wrote.
+ *
+ * Everything here reads the SCHEMA. It is a claim about what the column was
+ * declared to be, never a reading of what it is.
+ */
+export declare function conflictKeyComparisonOf(params: {
+    dialect: SqlDialect;
+    field: FieldMeta;
+}): ConflictKeyComparison;
+/**
+ * Refuse a batch whose conflict keys neither side can compare.
+ *
+ * Runs after {@link assertNoDuplicateConflictKeys} and before any statement is
+ * executed. Two things make a batch safe, and one of them has to hold:
+ *
+ * 1. **Every target column compares BYTES.** Then the whole-batch JavaScript
+ *    check already saw every pair, across parameter chunks, and is the same
+ *    answer the database would give.
+ * 2. **The engine compares the pairs itself, in ONE statement.** Postgres does
+ *    (SQLSTATE 21000) and it does so under the real collation, scale and
+ *    precision — including the ones the ORM cannot see, such as a `@db.Char`
+ *    pad or a `uuid` column's case folding. A SECOND statement breaks it: rows
+ *    in different statements are never compared, and the second one quietly
+ *    updates what the first inserted.
+ *
+ * A named-constraint arbiter hides its column list, so route 1 is unavailable
+ * by construction and route 2 is the only one left.
+ *
+ * **What route 1 does NOT establish.** It reads the SCHEMA. `@collation` and
+ * `@db.*` are what the schema intends the column to be, and nothing here reads
+ * the live database to confirm either. A table or database default, an ALTER
+ * applied outside migrations, a restored dump, or a column created before the
+ * annotation was added all leave the physical column carrying something else.
+ * On mysql that gap is the normal case rather than the exception for a
+ * collation: the differ compares a column's type, nullability and default,
+ * never its collation, so adding `@collation` to an existing column generates
+ * no migration step at all. Where the schema and the column disagree, route
+ * 1's guarantee is the schema's, not the database's.
+ *
+ * **What route 1 now also refuses.** A conflict-target column carrying a
+ * `@db.*` native type is opaque unless that exact type was measured to leave
+ * equality alone ({@link BYTE_EXACT_NATIVE_TYPES}). This closes the case where
+ * a `@db.Char(10)` or `@db.Uuid` key classified as byte-comparable, took route
+ * 1, and let a chunked batch through: measured on postgres, `'pad'` and
+ * `'pad '` submitted as two statements against a `char(10)` key stored ONE row
+ * and kept the last, with no error, while the same pair inside one statement
+ * raised 21000.
+ */
+export declare function assertConflictKeysAreComparable(params: {
+    dialect: SqlDialect;
+    model: ModelMeta;
+    target: UpsertConflictTarget;
+    /** Statements this batch will run; more than one means uncompared pairs. */
+    statementCount: number;
+    compiled: readonly Readonly<Record<string, unknown>>[];
+}): void;
+//# sourceMappingURL=bulk-upsert.d.ts.map

package/dist/bulk-upsert.d.ts.map

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

package/dist/client.d.ts

@@ -0,0 +1,200 @@
+import type { SchemaIR } from "@vibeorm/schema";
+import type { DatabaseAdapter, TransactionOptions } from "./adapter.ts";
+import type { RelationStrategy } from "./query-builder.ts";
+import type { ClientComputedOptions } from "./computed.ts";
+import type { ClientExtensionsOptions } from "./extensions.ts";
+import type { DefineViewFn } from "./views.ts";
+import type { WriteValidators } from "./validators.ts";
+import type { PolicyContextValue } from "./policy.ts";
+import type { ScopedClientConfig } from "./scoped.ts";
+import type { UpsertManyResult } from "./bulk-upsert.ts";
+import type { TelemetryOptions } from "./telemetry/types.ts";
+/** One executed statement, reported to `ClientOptions.onQuery`. */
+export type QueryEvent = {
+    /** Model name, or `null` for raw queries. */
+    readonly model: string | null;
+    /** ORM method, or `"$queryRaw"` / `"$executeRaw"`. */
+    readonly method: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly durationMs: number;
+};
+export type ClientOptions = {
+    /** Trusted infrastructure configuration. PGlite requires a pre-existing restricted role;
+     * embedded role binding is not a security boundary against the host process.
+     * Desired policy deparse is probed once per backend generation (bounded cache);
+     * live expressions/privileges are still checked every transaction. Privileged
+     * dependency changes retaining identical deparse need a fresh client/doctor check. */
+    readonly nativeRls?: {
+        readonly runtimeRole?: string;
+    };
+    /** Called after every statement — logging, tracing, test assertions. */
+    readonly onQuery?: (event: QueryEvent) => void;
+    /**
+     * Default relation-loading strategy: `"query"` (batched WHERE-IN, portable,
+     * the default) or `"join"` (LATERAL + JSON aggregation, postgres/pglite
+     * only). A per-query `relationStrategy` argument overrides it.
+     */
+    readonly relationStrategy?: RelationStrategy;
+    /**
+     * Append the primary key to ORDER BY when a find has no explicit orderBy
+     * (default false) — deterministic row order at the cost of a sort. v1 parity.
+     */
+    readonly defaultOrderByPk?: boolean;
+    /**
+     * Append the primary key as a tie-breaker to `distinct` ordering (default
+     * TRUE) — without it, WHICH row represents each distinct key is unspecified.
+     * v1 parity.
+     */
+    readonly distinctOrderByPk?: boolean;
+    /**
+     * Opt-in write-boundary validators (Standard Schema, per model × field):
+     * `{ User: { settings: zodSchema } }`. Run on every write path (nested
+     * creates included) before encoding; failure throws VIBE_VALIDATION with
+     * the validator's issues in `meta`. Reads are never taxed.
+     */
+    readonly validate?: WriteValidators;
+    /**
+     * Opt-in operation tracing. One event per public ORM call, with the
+     * statements it ran; parameter values are redacted and raw SQL text is not
+     * captured unless separately asked for. The exporter is the host's — a throw
+     * from it can never change a database outcome, and `$disconnect()` flushes it
+     * but never shuts it down.
+     */
+    readonly telemetry?: TelemetryOptions;
+    /**
+     * Strict argument handling (EPIC 2), **on by default**: an explicit
+     * `undefined` anywhere in ORM argument syntax is refused BEFORE a statement
+     * is built, instead of silently dropping the property (which widens a filter
+     * or loses a write). `SKIP` (`@vibeorm/runtime`) omits a property
+     * deliberately.
+     *
+     * Set `false` to opt OUT and restore legacy/Prisma semantics, where an
+     * explicit `undefined` member simply vanishes. Only an explicit `false` does
+     * that: an options object that does not mention this stays strict.
+     */
+    readonly strictArguments?: boolean;
+};
+/** Rows are plain objects keyed by field name; the generated client narrows them. */
+export type ClientRow = Record<string, unknown>;
+/** Result of the count-returning batch methods. */
+export type BatchResult = {
+    readonly count: number;
+};
+/**
+ * A model's methods. Arguments and results are intentionally broad here — the
+ * generated `.d.ts` replaces this surface with precise per-model types, and
+ * keeping the runtime free of inference is what holds the type-cost budget
+ * (constitution rule 2).
+ */
+export type ModelDelegate = {
+    readonly findMany: (args?: ClientRow) => Promise<ClientRow[]>;
+    readonly findFirst: (args?: ClientRow) => Promise<ClientRow | null>;
+    readonly findFirstOrThrow: (args?: ClientRow) => Promise<ClientRow>;
+    readonly findUnique: (args: ClientRow) => Promise<ClientRow | null>;
+    readonly findUniqueOrThrow: (args: ClientRow) => Promise<ClientRow>;
+    readonly create: (args: ClientRow) => Promise<ClientRow | null>;
+    readonly createMany: (args: ClientRow) => Promise<BatchResult>;
+    readonly createManyAndReturn: (args: ClientRow) => Promise<ClientRow[]>;
+    readonly update: (args: ClientRow) => Promise<ClientRow>;
+    readonly updateMany: (args: ClientRow) => Promise<BatchResult>;
+    /**
+     * Bulk update that returns the rows it changed (dialects with RETURNING).
+     *
+     * OPTIONAL on purpose: the base client always provides it, but the rewriting
+     * handles (`$scoped`, `$withPolicy`) build explicit delegate literals and do
+     * not implement it yet, and a required member would make the type claim a
+     * method those handles do not have. See notes-epic2.md `## Hand-off`.
+     */
+    readonly updateManyAndReturn: (args: ClientRow) => Promise<ClientRow[]>;
+    readonly upsertMany: (args: ClientRow) => Promise<UpsertManyResult>;
+    readonly upsert: (args: ClientRow) => Promise<ClientRow>;
+    readonly delete: (args: ClientRow) => Promise<ClientRow>;
+    readonly deleteMany: (args?: ClientRow) => Promise<BatchResult>;
+    /** Plain form returns a number; `{ select: { _all, field } }` returns per-key counts. */
+    readonly count: (args?: ClientRow) => Promise<number | Record<string, number>>;
+    readonly aggregate: (args: ClientRow) => Promise<ClientRow>;
+    readonly groupBy: (args: ClientRow) => Promise<ClientRow[]>;
+};
+/**
+ * The client. Delegates are also attached as own properties under their
+ * camelCase names (`client.user.findMany()`); the type surfaces them through
+ * `$models` because a plain index signature would erase the `$`-methods.
+ * Model names can never collide with those: every reserved client name is
+ * `$`-prefixed (see `RESERVED_CLIENT_NAMES` in @vibeorm/schema).
+ */
+export type DynamicClient = {
+    /** Copy and freeze the required native-RLS identity without acquiring a connection. */
+    readonly $withContext?: (context: Readonly<Record<string, unknown>>) => DynamicClient;
+    /** Delegates keyed by BOTH camelCase client name and model name. */
+    readonly $models: Readonly<Record<string, ModelDelegate>>;
+    /**
+     * Subscribe to client events (`"query"` fires after every statement, with
+     * the same payload as `ClientOptions.onQuery` — both fire). Returns an
+     * unsubscribe function. Transaction clients share the parent's listeners.
+     */
+    readonly $on: (event: "query", listener: (event: QueryEvent) => void) => () => void;
+    /**
+     * Run work in ONE transaction. Callback form: `fn` receives a transaction
+     * client; everything it runs rides the same BEGIN/COMMIT and a throw rolls
+     * back. Array form (Prisma parity): UN-AWAITED delegate calls — delegate
+     * methods return LAZY query promises that only dispatch on await — run
+     * SEQUENTIALLY inside one transaction, results returned positionally.
+     */
+    readonly $transaction: {
+        <T>(fn: (tx: DynamicClient) => Promise<T>, options?: TransactionOptions): Promise<T>;
+        <T extends readonly unknown[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{
+            -readonly [K in keyof T]: Awaited<T[K]>;
+        }>;
+    };
+    /** Tagged template — interpolations become bound parameters, never text. */
+    readonly $queryRaw: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<ClientRow[]>;
+    /** Tagged template returning the affected-row count. */
+    readonly $executeRaw: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<number>;
+    readonly $queryRawUnsafe: (text: string, ...values: unknown[]) => Promise<ClientRow[]>;
+    readonly $executeRawUnsafe: (text: string, ...values: unknown[]) => Promise<number>;
+    readonly $connect: () => Promise<void>;
+    readonly $disconnect: () => Promise<void>;
+    /**
+     * Field-masking views (v1 `defineView` parity, board #11) — a read-only
+     * scoped client restricted to the definition's models and fields. Attached
+     * by `attachDefineView` after construction (hence optional in the type);
+     * it is always present on a built client, transaction clients included.
+     */
+    readonly $defineView?: DefineViewFn;
+    /**
+     * Row scoping (@@policy): bind a per-request context — the returned client
+     * AND-s the policy predicate into every query on policied models and forces
+     * it into creates. Attached only when the schema declares @@policy.
+     */
+    readonly $withPolicy?: (context: Readonly<Record<string, PolicyContextValue>>) => DynamicClient;
+    /** Deliberate, greppable full-access escape from policy scoping. */
+    readonly $bypassPolicy?: () => DynamicClient;
+    /**
+     * Tenant scoping (framework handoff): base client + total per-model tenancy
+     * map + scope value → a NEW handle whose every call is confined to that
+     * tenant (raw SQL refused). Always attached; refuses on @@policy schemas.
+     */
+    readonly $scoped?: (config: ScopedClientConfig) => DynamicClient;
+};
+/**
+ * Build a client for a schema over an adapter.
+ *
+ * The adapter chooses the dialect: the same IR runs on postgres, sqlite or
+ * mysql, and every dialect difference is resolved by `@vibeorm/sql` and the
+ * codec table rather than by branching here.
+ *
+ * @example
+ * const db = createClient({ schema, adapter });
+ * const users = await db.$models.user.findMany({ where: { active: true } });
+ */
+export declare function createClient(params: {
+    schema: SchemaIR;
+    adapter: DatabaseAdapter;
+    options?: ClientOptions;
+    /** Extension wiring — baked mounts + manifest from the generated client, live instances from the caller. */
+    extensions?: ClientExtensionsOptions;
+    /** Computed-field wiring — baked manifest from the generated client, live specs from the caller. */
+    computed?: ClientComputedOptions;
+}): DynamicClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/codecs.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The codec entry points — constitution rule 6.
+ *
+ * The PURE per-dialect tables (dialect × scalar type) live in @vibeorm/sql
+ * (`codecs.ts` there) and are re-exported here so consumers keep one import
+ * site. This module owns the FieldMeta-aware entry points: list handling,
+ * enum-to-String routing and row materialization.
+ *
+ * The two rules that make it work:
+ *   - EVERY parameter bound by the query builder passes through `encodeValue`.
+ *   - EVERY row materialized by the client passes through `decodeRow`/
+ *     `decodeRows` — including every relation-loaded child row, at every
+ *     materialization point (the v1 lesson: BigInt-as-string and enum-array
+ *     bugs came from children skipping coercion).
+ */
+import type { Dialect, FieldType } from "@vibeorm/schema";
+import type { ScalarCodec, WireFidelity } from "@vibeorm/sql";
+import type { FieldMeta, ModelMeta } from "./model-meta.ts";
+export { DIALECT_CODECS, MYSQL_CODECS, POSTGRES_CODECS, SQLITE_CODECS, decodeIsNoop, } from "@vibeorm/sql";
+export type { CodecTable, ScalarCodec, WireFidelity } from "@vibeorm/sql";
+/** The codec for a field type on a dialect. Enum references use the String codec. */
+export declare function getCodec(params: {
+    dialect: Dialect;
+    type: FieldType;
+}): ScalarCodec;
+/**
+ * Encode one value for parameter binding. `null`/`undefined` pass through
+ * untouched (SQL NULL). List fields encode element-wise; the adapter's
+ * `formatArrayParam` then owns the array's wire representation — except for
+ * postgres ENUM arrays, which become an array literal here (no driver can
+ * serialize them, see {@link isPostgresEnumList}).
+ */
+export declare function encodeValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Decode one driver value. List fields decode element-wise.
+ *
+ * postgres returns ENUM arrays as a raw array literal string, because no driver
+ * knows a user-defined enum's array OID (LEARNINGS.md) — that literal is parsed
+ * here, next to the other coercion rules.
+ */
+export declare function decodeValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Encode one COMPARISON operand (WHERE / cursor bounds). Identical to
+ * {@link encodeValue} everywhere except sqlite Decimal (SQL review B4):
+ * Decimal STORES as exact TEXT there, but text comparison is lexicographic —
+ * so every compare site casts the column (`CAST(col AS REAL)`) and binds the
+ * operand as a NUMBER. Comparison precision is float64-bounded on sqlite
+ * (docs/dialects.md); storage and read-back stay exact.
+ */
+export declare function encodeFilterValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Encode one AGGREGATE-predicate operand (HAVING). On sqlite an aggregate
+ * expression has NO column affinity, so a TEXT operand never converts and the
+ * predicate is constant-false (SQL review M5, live-proven) — operands bind in
+ * raw numeric form there: Decimal as a number (the aggregate is over
+ * `CAST(col AS REAL)`), BigInt as a bigint (bun:sqlite binds int64 natively).
+ * Other dialects keep the field codec's wire form.
+ */
+export declare function encodeAggregateOperand(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/** Decode one non-null driver value (list handling prebound). */
+type RowDecoder = (value: unknown) => unknown;
+/**
+ * The prebound encoder for one field on one dialect, or `null` when its codec
+ * encode is the identity. Mirrors `encodeValue` exactly (see `fieldDecoder`).
+ */
+export declare function fieldEncoder(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+}): RowDecoder | null;
+/**
+ * The prebound decoder for one field on one dialect, or `null` when its codec
+ * decode is the identity (nothing to do). Mirrors `decodeValue` exactly:
+ * elements of a list decode element-wise (null elements pass), a non-array
+ * value on a list field goes through the element decoder as-is.
+ *
+ * With a `wire` declaration (board #30 — the ADAPTER's promise about what its
+ * driver delivers), decoders that are provably no-ops for that wire are pruned
+ * too ({@link decodeIsNoop}): non-list DateTime/Json/Int/Float columns on
+ * drivers that already deliver native forms. Without a declaration the full
+ * idempotency-guarded decoder set applies — exactly the pre-#30 behaviour.
+ */
+export declare function fieldDecoder(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    wire?: WireFidelity;
+}): RowDecoder | null;
+/**
+ * Materialize one driver row: column names become field names, values pass
+ * through their codecs. Columns the model does not know (aggregate aliases, raw
+ * extras) are carried over verbatim.
+ */
+export declare function decodeRow(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    row: Record<string, unknown>;
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>;
+/** `decodeRow` over a result set. */
+export declare function decodeRows(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    rows: readonly Record<string, unknown>[];
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>[];
+/**
+ * `decodeRows` for rows the caller OWNS (fresh driver output): when no column
+ * is renamed the rows are decoded in place — only columns whose codec does
+ * something are touched — and the same array returns. With renames it falls
+ * back to rebuilding rows. Every decoder is idempotent (each checks its input
+ * type), so re-materializing an already-decoded row is harmless.
+ *
+ * Internal to the runtime (client + relation loader) — the exported
+ * `decodeRow`/`decodeRows` keep their copy semantics.
+ */
+export declare function materializeRows(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    rows: Record<string, unknown>[];
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>[];
+/**
+ * `materializeRows` for JSON-transport rows — the join strategy's child rows
+ * after `JSON.parse`. Postgres-only by construction (lateral joins are).
+ */
+export declare function materializeJsonRows(params: {
+    model: ModelMeta;
+    rows: Record<string, unknown>[];
+}): Record<string, unknown>[];
+/**
+ * Normalize one aggregate value — the contract, tested live on PGlite:
+ *
+ * | aggregate | field type      | JS result                     |
+ * |-----------|-----------------|-------------------------------|
+ * | `_count`  | any / `_all`    | `number` (0 over an empty set)|
+ * | `_avg`    | Int/BigInt/Float| `number` (pg numeric → Number)|
+ * | `_avg`    | Decimal         | `string` (no float rounding)  |
+ * | `_sum`    | Int / Float     | `number`                      |
+ * | `_sum`    | BigInt          | `bigint`                      |
+ * | `_sum`    | Decimal         | `string`                      |
+ * | `_min/_max`| any            | the field's own codec type    |
+ *
+ * Every non-`_count` aggregate over an empty set is `null` (SQL semantics,
+ * kept deliberately — 0 would be a lie for MIN/AVG).
+ */
+export declare function decodeAggregateValue(params: {
+    dialect: Dialect;
+    key: "_count" | "_avg" | "_sum" | "_min" | "_max";
+    field: FieldMeta | null;
+    value: unknown;
+}): unknown;
+//# sourceMappingURL=codecs.d.ts.map