@vibeorm/runtime 1.3.0 → 2.0.0-alpha.2

package/dist/model-meta.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Runtime model metadata: the pre-resolved view of the Schema IR the query
+ * builder and client run on.
+ *
+ * Built once per client (`buildRuntimeMeta`), then read-only. Everything the
+ * hot path needs is precomputed here — column names, field lookup maps, primary
+ * keys — so no query ever walks the IR. Relations are carried verbatim: the P2
+ * core slice does not load them, P3 does.
+ *
+ * Also the home of app-side default generation (uuid/cuid/nanoid/ulid/now),
+ * which is dialect-free by design: the id exists before the INSERT, which is
+ * what lets dialects without RETURNING re-select the row they just wrote.
+ */
+import type { ComputedConfig, DefaultValueIR, FieldType, RelationIR, ScalarType, SchemaIR } from "@vibeorm/schema";
+import type { SqlExpr } from "@vibeorm/sql";
+/** Where a field's default value is produced. */
+export type DefaultOrigin = "app" | "database" | "none";
+/** A scalar or enum column, resolved for the runtime. */
+export type FieldMeta = {
+    /** Client-facing field name. */
+    readonly name: string;
+    /** Database column name (`dbName ?? name`). */
+    readonly columnName: string;
+    readonly type: FieldType;
+    /** The scalar type, or `null` when the field is an enum reference. */
+    readonly scalarType: ScalarType | null;
+    /** The enum name, or `null` when the field is a scalar. */
+    readonly enumName: string | null;
+    readonly isList: boolean;
+    readonly isOptional: boolean;
+    readonly isId: boolean;
+    readonly isUnique: boolean;
+    readonly isUpdatedAt: boolean;
+    readonly default: DefaultValueIR | null;
+    /**
+     * `"app"` — the runtime generates the value and sends it (uuid/cuid/nanoid/
+     * ulid/now). `"database"` — the column's DEFAULT clause applies and the field
+     * is omitted from INSERTs (autoincrement, dbgenerated, literal, enum value).
+     */
+    readonly defaultOrigin: DefaultOrigin;
+};
+/** One computed field, resolved for the runtime (config-declared, see @vibeorm/schema computed.ts). */
+export type ComputedFieldMeta = {
+    readonly name: string;
+    /** The declared TypeScript type (informational at runtime; the generator wrote it into the .d.ts). */
+    readonly type: string;
+    /** Scalar fields the compute reads — fetched with the computed field, stripped unless selected. */
+    readonly needs: readonly string[];
+    readonly compute: (row: Record<string, unknown>) => unknown;
+};
+/** A model, resolved for the runtime. */
+export type ModelMeta = {
+    /** IR model name, e.g. `"User"`. */
+    readonly name: string;
+    /** Delegate key on the client, e.g. `"user"`. */
+    readonly clientName: string;
+    /** Table name (`dbName ?? name`). */
+    readonly tableName: string;
+    readonly fields: readonly FieldMeta[];
+    readonly fieldByName: ReadonlyMap<string, FieldMeta>;
+    /** Reverse map for row materialization (driver rows are keyed by column). */
+    readonly fieldByColumn: ReadonlyMap<string, FieldMeta>;
+    /** Primary-key fields: the single `@id` field, or the `@@id` fields in order. */
+    readonly primaryKey: readonly FieldMeta[];
+    /** Fields that identify a row on their own (`@id` or `@unique`). */
+    readonly uniqueFields: readonly FieldMeta[];
+    /**
+     * COMPOSITE ways to address one row, keyed exactly like the generated
+     * `…WhereUniqueInput` property — member field names joined with `_`
+     * (`projectId_userId`). The composite `@@id` comes first, then every
+     * multi-field `@@unique`, in schema order. Empty for models without one.
+     */
+    readonly compoundUniques: ReadonlyMap<string, readonly FieldMeta[]>;
+    /** Carried verbatim from the IR — consumed by relation loading in P3. */
+    readonly relations: readonly RelationIR[];
+    readonly relationByName: ReadonlyMap<string, RelationIR>;
+    readonly isView: boolean;
+    /** Computed fields configured for this model, or `null` (the common case). */
+    readonly computed: ReadonlyMap<string, ComputedFieldMeta> | null;
+};
+/**
+ * A pre-bound extension where-operator: compiles one use (`{ similarTo: … }`)
+ * into a SqlExpr fragment. Built by `buildExtensionOperatorMap` in
+ * extensions.ts with dialect/provider/options already curried in.
+ */
+export type ExtensionOperatorFn = (params: {
+    /** Identifier path of the column (qualified when inside a subquery). */
+    readonly column: readonly string[];
+    readonly operand: unknown;
+    readonly model: string;
+    readonly field: string;
+}) => SqlExpr;
+/** All runtime metadata for one schema. */
+export type RuntimeMeta = {
+    readonly models: readonly ModelMeta[];
+    /** Keyed by BOTH camelCase client name (`user`) and model name (`User`). */
+    readonly modelByName: ReadonlyMap<string, ModelMeta>;
+    /** Enum name → its values, for validation and codec decisions. */
+    readonly enums: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Extension where-operators (extension sql plane), keyed by operator name.
+     * Rides on the meta so the WHERE compiler reaches it at every site without
+     * threading a parameter through the hot path.
+     */
+    readonly extensionOperators?: ReadonlyMap<string, ExtensionOperatorFn>;
+};
+/**
+ * Delegate key for a model name: the first character lowercased, nothing else
+ * (the Prisma convention — `User` → `user`, `URLMap` → `uRLMap`). Keeping the
+ * rest untouched makes the mapping unambiguous and reversible.
+ */
+export declare function toClientName(params: {
+    name: string;
+}): string;
+/** RFC 4122 v4 UUID. */
+export declare function generateUuid(): string;
+/**
+ * Collision-resistant, sortable-ish id in the CUID spirit: `"c"` + a base-36
+ * millisecond timestamp + 16 random base-36 characters. Starts with a letter so
+ * it is safe as an HTML id and in every database identifier context.
+ */
+export declare function generateCuid(): string;
+/** 21-character NanoID over the standard URL-safe alphabet (64 chars, unbiased 6-bit mask). */
+export declare function generateNanoid(): string;
+/**
+ * ULID: 10 characters of millisecond timestamp + 16 of randomness, Crockford
+ * base32, lexicographically sortable by creation time. 256 % 32 === 0, so the
+ * byte-to-symbol fold is unbiased.
+ */
+export declare function generateUlid(): string;
+/**
+ * The value the runtime sends for an app-side default, or `undefined` when the
+ * database owns it (autoincrement, dbgenerated, literal, enum value — those
+ * ride the column's DEFAULT clause so the database stays the single source of
+ * truth for them).
+ */
+export declare function generateDefaultValue(params: {
+    spec: DefaultValueIR;
+}): unknown;
+/** Resolve a whole schema into the runtime's read-only metadata. */
+export declare function buildRuntimeMeta(params: {
+    schema: SchemaIR;
+    computed?: ComputedConfig;
+}): RuntimeMeta;
+/** Look a model up by client name or model name; unknown names are a caller error. */
+export declare function getModelMeta(params: {
+    meta: RuntimeMeta;
+    model: string;
+}): ModelMeta;
+/** Look a field up on a model; unknown names are a caller error naming the field. */
+export declare function getFieldMeta(params: {
+    model: ModelMeta;
+    field: string;
+    context: string;
+}): FieldMeta;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

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

package/dist/nested-writes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Nested writes (Prisma-shaped, v1 parity plus implicit-M2M support):
+ *
+ *   create data:  relation: { create | connect | connectOrCreate }
+ *   update data:  … plus { update | updateMany | upsert | set | disconnect |
+ *                  delete | deleteMany }
+ *
+ * STATEMENT ORDER (deterministic, pinned by unit tests):
+ *   create:  [owner-side to-one resolutions: SELECT/INSERT per verb] →
+ *            parent INSERT → [list/M2M ops in data-key order, item order;
+ *            each M2M child op is followed immediately by its join-row INSERT].
+ *            PLAIN multi-item FK-side `create` lists collapse into ONE
+ *            multi-row INSERT (v1 parity — one fewer round-trip per item) when
+ *            no item carries nested ops of its own and all items write the
+ *            same columns (so no NULL-vs-database-default drift can appear).
+ *   update:  parent pre-SELECT (findUnique) → [owner-side to-one resolutions]
+ *            → parent UPDATE (scalars + FK changes, skipped when empty) →
+ *            [deferred owner-side child DELETEs] → [list/M2M ops in data-key
+ *            order] — the returned row is the UPDATE's result (or the
+ *            pre-SELECT when nothing on the parent changed).
+ *
+ * TRANSACTIONS: any nested write that produces more than one statement wraps
+ * in `adapter.transaction` automatically; inside an outer `$transaction` that
+ * nests as a savepoint (the adapter contract). A mid-write failure therefore
+ * rolls the whole write back.
+ *
+ * Implicit M2M goes through the ONE shared join-table rule (`implicitJoinTable`
+ * via relation-plan's link resolution); `connect` writes join rows with
+ * conflict-skip, so re-connecting an existing pair is a no-op.
+ *
+ * Unknown verbs are loud: VIBE_VALIDATION naming the verb (v1 silently
+ * ignored them — that was a bug class, not a feature).
+ */
+import type { SqlDialect, SqlStatement } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { QueryMethod } from "./query-builder.ts";
+export type ClientRowLike = Record<string, unknown>;
+/**
+ * Executes ORM statements against ONE adapter (plain or transactional).
+ * `single` runs a single-row mutation with the client's full RETURNING /
+ * re-select machinery (mysql-safe); `statement` runs a raw AST statement
+ * (join-table work has no model).
+ */
+export type StatementRunner = {
+    readonly single: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<ClientRowLike>;
+    readonly rows: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<ClientRowLike[]>;
+    readonly affected: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<number>;
+    readonly statement: (params: {
+        statement: SqlStatement;
+        model: string;
+        method: string;
+    }) => Promise<ClientRowLike[]>;
+};
+/** What the client hands the nested-write orchestrator. */
+export type WriteContext = {
+    readonly meta: RuntimeMeta;
+    readonly dialect: SqlDialect;
+    /** Runner on the client's current adapter (may already be transactional). */
+    readonly run: StatementRunner;
+    /** Runs `fn` with a runner bound to a (nested) transaction. */
+    readonly transactional: <T>(fn: (run: StatementRunner) => Promise<T>) => Promise<T>;
+};
+/** Does this `data` object carry nested relation operations? */
+export declare function hasNestedWrites(params: {
+    model: ModelMeta;
+    data: unknown;
+}): boolean;
+/**
+ * `create` with nested relation operations. Returns the parent row as the
+ * INSERT produced it (relation loading/projection are the client's follow-up).
+ */
+export declare function createWithNested(params: {
+    ctx: WriteContext;
+    model: ModelMeta;
+    data: Record<string, unknown>;
+}): Promise<ClientRowLike>;
+/**
+ * `update` with nested relation operations. Always transactional (the flow is
+ * multi-statement by construction). Returns the parent row after its UPDATE
+ * (or the pre-read row when only children changed).
+ */
+export declare function updateWithNested(params: {
+    ctx: WriteContext;
+    model: ModelMeta;
+    where: Record<string, unknown>;
+    data: Record<string, unknown>;
+}): Promise<ClientRowLike>;
+//# sourceMappingURL=nested-writes.d.ts.map

package/dist/nested-writes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-writes.d.ts","sourceRoot":"","sources":["../src/nested-writes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE;QAC3B,SAAS,EAAE,YAAY,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAChC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACrF,CAAC;AAmCF,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAQpF;AAgcD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,YAAY,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC,aAAa,CAAC,CAOzB;AAoeD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,YAAY,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC,aAAa,CAAC,CAoCzB"}

package/dist/query-builder.d.ts

@@ -0,0 +1,250 @@
+/**
+ * The query builder: `{ model, method, args }` → a SQL AST statement, purely.
+ *
+ * Nothing here touches a database, a clock-free input always produces the same
+ * statement, and every branch is reachable from the query catalog
+ * (`tests/query-catalog/`) — which pins the rendered SQL for all three dialects
+ * and exports it to the reviewable root `sql-catalog.md`.
+ *
+ * Division of labour:
+ *   - shapes and SQL text live in @vibeorm/sql (this file never writes SQL),
+ *   - value transport lives in codecs.ts (this file never coerces),
+ *   - dialect gaps become VIBE_UNSUPPORTED_CAPABILITY here, at build time,
+ *     which is the earliest knowable moment for a query-level feature,
+ *   - bad input becomes VIBE_VALIDATION naming the model, field and operator.
+ */
+import type { OrderByColumn, SqlDialect, SqlExpr, SqlStatement } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { RelationSelection, RelationTreeNode } from "./relation-plan.ts";
+/** Every ORM method the query builder builds SQL for. */
+export type QueryMethod = "findMany" | "findFirst" | "findUnique" | "create" | "createMany" | "createManyAndReturn" | "update" | "updateMany" | "upsert" | "delete" | "deleteMany" | "count" | "aggregate" | "groupBy";
+/** Client-level options that shape SQL (subset of ClientOptions the builder needs). */
+export type BuilderClientOptions = {
+    /** Append the primary key to ORDER BY when no explicit orderBy was given (default false). */
+    readonly defaultOrderByPk?: boolean;
+    /** Append the primary key as a `distinct` tie-breaker for determinism (default true). */
+    readonly distinctOrderByPk?: boolean;
+};
+/** The five aggregate selector keys, in the deterministic order they project. */
+export type AggregateKey = "_count" | "_avg" | "_sum" | "_min" | "_max";
+/**
+ * One projected aggregate. `field: null` is `_all` (COUNT(*)). The alias is the
+ * deterministic `<key>__<selector>` scheme (`_count___all`, `_avg__score`) —
+ * results are read back by construction from these aliases, never parsed.
+ */
+export type AggregateSelection = {
+    readonly key: AggregateKey;
+    readonly field: string | null;
+    readonly alias: string;
+};
+/** Everything the client needs to decode an aggregate/groupBy/count-select row. */
+export type AggregateSpec = {
+    readonly selections: readonly AggregateSelection[];
+    /** `_count: true` — the result's `_count` is a bare number, not an object. */
+    readonly countShorthand: boolean;
+};
+/** How included relations are fetched. */
+export type RelationStrategy = "query" | "join";
+/**
+ * A built query plus everything the client needs after execution. The plan is
+ * data only: the client decides how to run it.
+ */
+export type QueryPlan = {
+    readonly method: QueryMethod;
+    readonly model: ModelMeta;
+    readonly statement: SqlStatement;
+    /**
+     * Field names the statement projects, in order, or `null` when it projects
+     * every scalar field. Mutations RETURNING extra primary-key columns are
+     * narrowed back down to this list by the client.
+     */
+    readonly selectedFields: readonly string[] | null;
+    /**
+     * What the CALLER should see: the user's scalar select plus relation names
+     * and `_count`, or `null` for "all scalars (plus attached relations)".
+     * Differs from `selectedFields` when stitching keys were added to the SQL
+     * projection — the client narrows back down to this after relation loading.
+     */
+    readonly resultFields: readonly string[] | null;
+    /**
+     * Computed fields to attach to result rows (config-declared), resolved from
+     * select/omit — always a concrete name list, `null` when none apply. Their
+     * `needs` ride `selectedFields` like stitch keys and are narrowed away by
+     * `resultFields` unless selected themselves.
+     */
+    readonly computed: readonly string[] | null;
+    /** Relations to load after the base rows, or `null` when none were asked for. */
+    readonly relations: RelationSelection | null;
+    /**
+     * How relations load. With `"join"` on a find method the base statement IS
+     * the lateral statement (level-1 relations ride along as JSON columns);
+     * deeper levels always fall back to `"query"` batches (v1 semantics).
+     */
+    readonly relationStrategy: RelationStrategy;
+    /** True when `take` produced a LIMIT. */
+    readonly takeApplied: boolean;
+    /** Alias the COUNT(*) value is projected under (`count` only). */
+    readonly countAlias: string | null;
+    /**
+     * Unique WHERE identifying the affected row, for the re-select a dialect
+     * without RETURNING needs. `null` when the row cannot be identified before
+     * the write (an autoincrement key the database assigns).
+     */
+    readonly refetchWhere: Readonly<Record<string, unknown>> | null;
+    /**
+     * Upsert only: the unique where WITHOUT the update-arm overlay. The INSERT
+     * arm's row answers this key (its create row binds the conflict target — the
+     * B1 native-eligibility gate), so the mysql read-back tries the overlaid
+     * `refetchWhere` first, then this. `null` on every other method.
+     */
+    readonly refetchWhereBase: Readonly<Record<string, unknown>> | null;
+    /**
+     * createMany/createManyAndReturn only: when the call compiles to MORE than
+     * one statement (sqlite's heterogeneous column-set groups — M4 — or the M7
+     * parameter-budget chunks), every statement in order (`statement` is the
+     * first). The client executes them in ONE transaction, summing counts /
+     * concatenating returned rows. Absent for single-statement calls.
+     */
+    readonly batch?: readonly SqlStatement[];
+    /** The caller's `select`, replayed on that re-select. */
+    readonly selectArg: Readonly<Record<string, unknown>> | null;
+    /** How to decode aggregate/groupBy/count-select rows; `null` elsewhere. */
+    readonly aggregateSpec: AggregateSpec | null;
+    /** groupBy's `by` field names, for row assembly; `null` elsewhere. */
+    readonly groupByFields: readonly string[] | null;
+    /** Negative `take`: the SQL ordering was flipped; re-reverse rows after fetch. */
+    readonly reverseRows: boolean;
+    /**
+     * `distinct` + an explicit user orderBy (N1, board #22): the arrangement
+     * DISTINCT ON needs demotes the user's order behind the distinct fields, so
+     * the client re-sorts the FINAL rows by these keys — Prisma's presentation
+     * order, on every dialect. `nulls` is resolved at build time to the
+     * dialect's own NULL placement so the re-sort mirrors what the SQL order
+     * would have produced. `null` when no re-sort is needed.
+     */
+    readonly resortBy: readonly ResortKey[] | null;
+};
+/** One client-side re-sort key (see QueryPlan.resortBy). */
+export type ResortKey = {
+    readonly field: string;
+    readonly direction: "asc" | "desc";
+    readonly nulls: "first" | "last";
+    /** B4 mirror: Decimal ranks numerically — the SQL side ordered a number. */
+    readonly decimal: boolean;
+};
+/** Column alias for COUNT(*) — postgres and sqlite/mysql name it differently otherwise. */
+export declare const COUNT_ALIAS: string;
+/**
+ * Compile a Prisma-shaped where object; `undefined` when it constrains nothing.
+ *
+ * `qualify` table-qualifies every column reference (used inside lateral and
+ * EXISTS subqueries); `aliasSeq` threads the statement-wide subquery-alias
+ * counter so nested relation filters never collide.
+ */
+export declare function compileWhere(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    where: Record<string, unknown>;
+    qualify?: string;
+    aliasSeq?: {
+        n: number;
+    };
+}): SqlExpr | undefined;
+/** Compile `orderBy` (a single object or an array of them) into order terms. */
+export declare function compileOrderBy(params: {
+    model: ModelMeta;
+    orderBy: unknown;
+    qualify?: string;
+    /** When given, B4's sqlite Decimal ordering cast applies (`CAST … AS REAL`). */
+    dialect?: SqlDialect;
+}): OrderByColumn[];
+/**
+ * Compile `select` into scalar field names, projecting EXACTLY what was asked
+ * — the primary key is not smuggled in. Relation keys and `_count` are the
+ * relation resolver's business (`relation-plan.ts`) and are skipped here;
+ * `allowEmpty` permits a select of ONLY relations (the stitching key is added
+ * separately and stripped from the result).
+ */
+export declare function compileSelect(params: {
+    model: ModelMeta;
+    select: unknown;
+    allowEmpty?: boolean;
+}): string[];
+/**
+ * Whether `upsert({ where, create, update })` can ride ONE native
+ * `INSERT … ON CONFLICT`/`ON DUPLICATE KEY` statement — Prisma's own
+ * criterion: the create data must bind every conflict-target column with the
+ * SAME value the where names. Otherwise the conflict can never fire on the
+ * addressed row (postgres/sqlite would silently insert instead of update;
+ * mysql's ODKU could update an unrelated row — SQL review B1) and the client
+ * must run the transactional find-then-write fallback instead.
+ */
+/**
+ * Whether `upsert({ where, create, update })` can ride ONE native
+ * `INSERT … ON CONFLICT`/`ON DUPLICATE KEY` statement — Prisma's own
+ * criterion, two halves:
+ *   1. the create data binds every conflict-target column with the SAME value
+ *      the where names (otherwise the conflict can never fire on the
+ *      addressed row — postgres/sqlite would silently insert instead of
+ *      update; mysql's ODKU could update an unrelated row — SQL review B1);
+ *   2. the where carries NO fields beyond the conflict target (PG-2): a guard
+ *      field (`where: { email, active: true }`) is invisible to ON CONFLICT —
+ *      the update arm would fire even when the guard fails, where update()
+ *      honors the same guard.
+ * Ineligible shapes run the client's transactional find-then-write fallback,
+ * whose probe honors the FULL where.
+ */
+export declare function upsertUsesNativeStatement(params: {
+    model: ModelMeta;
+    args: Record<string, unknown>;
+}): boolean;
+/** The column a relation's JSON payload is exposed under in the outer row. */
+export declare function lateralColumnAlias(params: {
+    relation: string;
+}): string;
+/**
+ * PG-3 (SQL review round 2): order fields the lateral subselect must project
+ * HIDDEN — the aggregate's explicit `ORDER BY "__sub".…` (N2) can only
+ * reference projected columns, and a per-relation orderBy on a field outside
+ * the child select otherwise left the aggregate relying on "usually preserves
+ * subquery order". The loader deletes these after parsing (the stitch-key
+ * pattern). Empty when the projection is full or no orderBy was given.
+ */
+export declare function lateralHiddenOrderFields(params: {
+    node: RelationTreeNode;
+}): string[];
+/**
+ * The relation selection + caller-visible field list for one call, WITHOUT
+ * building a statement — the nested-write path orchestrates its own
+ * statements but still needs the validated result shape for relation loading
+ * and projection.
+ */
+export declare function resolveResultShape(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    method: QueryMethod;
+    args: Record<string, unknown>;
+}): {
+    relations: RelationSelection | null;
+    resultFields: readonly string[] | null;
+    computed: readonly string[] | null;
+};
+/**
+ * Build the SQL plan for one ORM call. Pure: same inputs, same statement —
+ * except for app-generated defaults (uuid/cuid/nanoid/ulid/now), which are by
+ * definition fresh per call.
+ *
+ * `defaultRelationStrategy` is the client-level option; a per-query
+ * `relationStrategy` argument (find methods only) overrides it.
+ */
+export declare function buildQuery(params: {
+    meta: RuntimeMeta;
+    dialect: SqlDialect;
+    model: string;
+    method: QueryMethod;
+    args?: Record<string, unknown>;
+    defaultRelationStrategy?: RelationStrategy;
+    clientOptions?: BuilderClientOptions;
+}): QueryPlan;
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/query-builder.d.ts.map

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

package/dist/relation-loader.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Relation LOADING: attach included relations onto already-materialized rows.
+ *
+ * The portable "query" strategy (default, all dialects): one batched statement
+ * per relation per level (`WHERE childKey IN (parent keys)`), grouped and
+ * stitched in memory — never one query per parent. Implicit M2M loads in ONE
+ * statement per level (board #12, v1's shape): children INNER JOINed to their
+ * join-table membership rows, the join table's parent-key column projected
+ * under a reserved alias and decoded through the PARENT key's codec (rule 6).
+ * Deeper levels recurse over the level's loaded children.
+ *
+ * PER-PARENT take/skip MECHANISM (differs from v1's SQL, matches its
+ * semantics): v1 windowed with `ROW_NUMBER() OVER (PARTITION BY fk)`; v2 loads
+ * the batch fully ordered (the user's orderBy, or the child PK when paginating
+ * without one) and applies each parent's skip/take at stitch time. Same
+ * observable result for any deterministic ordering, no window functions in the
+ * AST. The trade-off — overfetching children that fall outside a page — is
+ * accepted for 2.0 and confined to this module.
+ *
+ * The "join" strategy's rows arrive with `__rel_<name>` JSON columns (built by
+ * the query builder's lateral statement); `attachLateralRelations` parses,
+ * DECODES (codecs on every child row — to_jsonb strings timestamps and drops
+ * BigInt-ness, LEARNINGS) and stitches them, then recurses deeper levels
+ * through the query strategy exactly like v1.
+ *
+ * Statements run SEQUENTIALLY in relation-declaration order, so the statement
+ * stream is deterministic (scripted-adapter tests pin it; real adapters get
+ * predictable logs).
+ */
+import type { SelectStatement, SqlDialect, WireFidelity } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { RelationSelection } from "./relation-plan.ts";
+/** A materialized row relations are stitched onto. */
+export type LoadedRow = Record<string, unknown>;
+/**
+ * Executes one SELECT and returns RAW driver rows — the loader decodes them
+ * itself (the child model's codecs, at every materialization point). The
+ * client provides this bound to its adapter + onQuery reporting.
+ */
+export type RelationExecutor = (params: {
+    statement: SelectStatement;
+    model: string;
+    method: string;
+}) => Promise<Record<string, unknown>[]>;
+/**
+ * "query"-strategy loading: batched statements per relation, in declaration
+ * order, recursively. Mutates `rows` in place (relations become properties).
+ */
+export declare function attachRelations(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    rows: LoadedRow[];
+    selection: RelationSelection;
+    execute: RelationExecutor;
+    /** The executing adapter's wire declaration (board #30). */
+    wire?: WireFidelity;
+}): Promise<void>;
+/**
+ * "join"-strategy post-processing: parse each row's `__rel_<name>` JSON
+ * column, decode the children through the child model's codecs, stitch, then
+ * recurse deeper levels through the query strategy (v1 semantics) and load
+ * `_count` separately.
+ */
+export declare function attachLateralRelations(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    rows: LoadedRow[];
+    selection: RelationSelection;
+    execute: RelationExecutor;
+    /** The executing adapter's wire declaration (board #30 — deeper levels recurse through the query strategy). */
+    wire?: WireFidelity;
+}): Promise<void>;
+//# sourceMappingURL=relation-loader.d.ts.map

package/dist/relation-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-loader.d.ts","sourceRoot":"","sources":["../src/relation-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAW,YAAY,EAAE,MAAM,cAAc,CAAC;AAGvF,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,KAAK,EAAgB,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AAI5F,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE;IACtC,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AA2czC;;;GAGG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,+GAA+G;IAC/G,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB"}