@vibeorm/runtime 1.0.0

package/src/types.ts

@@ -0,0 +1,290 @@
+/**
+ * Runtime types used by the generated client and the query builder.
+ */
+
+import type { DatabaseAdapter } from "./adapter.ts";
+
+export type VibeClientOptions = {
+  /** Database adapter instance (required). */
+  adapter: DatabaseAdapter;
+  /** Log SQL queries for debugging */
+  log?: boolean | "query" | "info" | "warn" | "error";
+  /**
+   * Default relation loading strategy for all queries.
+   * - "query" (default): Separate batched WHERE IN queries per relation
+   * - "join": Single query with PostgreSQL LATERAL JOINs
+   */
+  relationStrategy?: "query" | "join";
+  /**
+   * Strategy for building COUNT queries.
+   * - "direct" (default): `SELECT COUNT(*) FROM "Table" WHERE ...`
+   *   Uses PostgreSQL parallel workers when available. Best for standard
+   *   PostgreSQL deployments (self-hosted, RDS, Cloud SQL, Docker).
+   *
+   * - "subquery": `SELECT COUNT(*) FROM (SELECT "id" FROM "Table" WHERE ... OFFSET 0) AS "sub"`
+   *   Wraps the count in a subquery with OFFSET 0, which can produce better
+   *   query plans on some serverless/proxy PostgreSQL providers (e.g. Neon,
+   *   PlanetScale, Supabase pooler) but disables parallel workers on standard
+   *   PostgreSQL. Use this if count queries are consistently slow on your
+   *   remote database.
+   */
+  countStrategy?: "direct" | "subquery";
+  /**
+   * Eagerly establish database connections on client creation.
+   * When true, the connection pool is warmed up immediately instead of
+   * waiting for the first query, eliminating cold-start latency (~300ms).
+   * Defaults to false (lazy connection).
+   */
+  eager?: boolean;
+  /**
+   * Enable Zod validation of inputs and/or outputs using the generated schemas.
+   * - false (default): no validation — zero runtime overhead
+   * - true / "all": validate both mutation inputs and query outputs
+   * - "input": validate mutation inputs only (create/update data)
+   * - "output": validate query result rows only
+   *
+   * Requires the generated schemas to be wired into the client (automatic
+   * when using the generated VibeClient() factory).
+   */
+  validate?: boolean | "input" | "output" | "all";
+  /**
+   * Custom ID generator function. Called when a field with @default(uuid/cuid/nanoid/ulid)
+   * is not provided in create data. Overrides the built-in generators.
+   *
+   * @example
+   * ```ts
+   * VibeClient({
+   *   adapter: bunAdapter({ url: "postgres://..." }),
+   *   idGenerator: ({ model, field, defaultKind }) => {
+   *     return `${model.toLowerCase().slice(0, 3)}_${crypto.randomUUID()}`;
+   *   }
+   * })
+   * ```
+   */
+  idGenerator?: (params: { model: string; field: string; defaultKind: string }) => string;
+  /**
+   * Enable per-query profiling with detailed timing breakdowns.
+   * - false (default): no profiling — zero runtime overhead
+   * - true: logs a structured timing breakdown to console after each query
+   * - A callback function: receives a QueryProfile object for custom handling
+   *
+   * Shows where time is spent: query building, SQL execution, relation loading,
+   * with per-relation breakdown including SQL text, exec time, and row counts.
+   *
+   * @example
+   * ```ts
+   * // Log to console
+   * VibeClient({ adapter, debug: true })
+   *
+   * // Collect profiles programmatically
+   * const profiles: QueryProfile[] = [];
+   * VibeClient({ adapter, debug: (p) => profiles.push(p) })
+   * ```
+   */
+  debug?: boolean | ((params: { profile: QueryProfile }) => void);
+};
+
+// ─── Query Profiling Types ─────────────────────────────────────────
+
+/**
+ * Per-relation timing breakdown emitted during profiled queries.
+ * Shows how long each relation's SQL execution took and how many rows were returned.
+ */
+export type RelationProfile = {
+  readonly relation: string;
+  readonly sqlExecMs: number;
+  readonly rowCount: number;
+  readonly sql: string;
+};
+
+/**
+ * Detailed per-query timing profile emitted when `debug` is enabled.
+ * Breaks down total wall-clock time into query building, SQL execution,
+ * relation loading (with per-relation details), and type coercion phases.
+ */
+export type QueryProfile = {
+  readonly model: string;
+  readonly operation: string;
+  readonly totalMs: number;
+  readonly queryBuildMs: number;
+  readonly sqlExecMs: number;
+  readonly rowCount: number;
+  readonly relationLoadMs: number;
+  readonly relationProfiles: readonly RelationProfile[];
+  readonly sql: string;
+  /** Time spent mapping raw DB rows to JS objects (scalar copy + JSON parse). */
+  readonly resultMapMs: number;
+  /** Approximate size of the result set in bytes (JSON-encoded). */
+  readonly resultSizeBytes: number;
+  /** SQL parameter values (for raw driver comparison). */
+  readonly sqlValues?: readonly unknown[];
+};
+
+/**
+ * Mutable profiling context threaded through relation loading.
+ * Accumulates per-relation timings as each relation query executes.
+ * @internal — not part of the public API.
+ */
+export type ProfilingContext = {
+  relationProfiles: RelationProfile[];
+  /** Populated by executeLateralJoinQuery with per-phase timings. */
+  queryBuildMs?: number;
+  sqlExecMs?: number;
+  resultMapMs?: number;
+  sql?: string;
+  sqlValues?: unknown[];
+  rowCount?: number;
+};
+
+// ─── Validation Schema Types ──────────────────────────────────────
+
+/**
+ * Duck-typed schema interface — works with any Zod schema without
+ * importing Zod directly. The runtime only calls safeParse() on these.
+ */
+export type ValidationSchema = {
+  safeParse(data: unknown): { success: true; data: unknown } | { success: false; error: unknown };
+};
+
+/**
+ * Validation schemas for a single model, keyed by operation type.
+ * Generated by the schemas.ts file and optionally wired into the client.
+ */
+export type ModelSchemas = {
+  model?: ValidationSchema;
+  createInput?: ValidationSchema;
+  updateInput?: ValidationSchema;
+  whereInput?: ValidationSchema;
+};
+
+// ─── Model Metadata ───────────────────────────────────────────────
+
+export type ScalarFieldMeta = {
+  readonly name: string;
+  readonly dbName: string;
+  readonly kind: "scalar" | "enum";
+  readonly isUpdatedAt?: boolean;
+  /** Prisma type for runtime coercion (e.g., BigInt values from the DB driver) */
+  readonly type?: string;
+  /**
+   * Default value kind for application-level generation.
+   * - "uuid" | "cuid" | "nanoid" | "ulid": runtime generates the value if not provided
+   * - true: DB handles the default (autoincrement, now, literal)
+   */
+  readonly hasDefault?: "uuid" | "cuid" | "nanoid" | "ulid" | true;
+  /** ID prefix to prepend to generated values (from /// @vibeorm.idPrefix("...")) */
+  readonly idPrefix?: string;
+};
+
+export type RelationFieldMeta = {
+  readonly name: string;
+  readonly kind: "relation";
+  readonly relatedModel: string;
+  readonly type: "oneToOne" | "oneToMany" | "manyToOne" | "manyToMany";
+  readonly isList: boolean;
+  readonly isForeignKey: boolean;
+  readonly fields: readonly string[];
+  readonly references: readonly string[];
+  readonly relationName?: string;
+  readonly joinTable?: string;
+};
+
+export type ModelMeta = {
+  readonly name: string;
+  readonly dbName: string;
+  readonly primaryKey: readonly string[];
+  readonly uniqueFields: readonly string[];
+  readonly scalarFields: readonly ScalarFieldMeta[];
+  readonly relationFields: readonly RelationFieldMeta[];
+};
+
+export type ModelMetaMap = Record<string, ModelMeta>;
+
+// ─── Query Operation Descriptor ───────────────────────────────────
+
+export type Operation =
+  | "findMany"
+  | "findFirst"
+  | "findUnique"
+  | "findUniqueOrThrow"
+  | "findFirstOrThrow"
+  | "create"
+  | "createMany"
+  | "createManyAndReturn"
+  | "update"
+  | "upsert"
+  | "delete"
+  | "deleteMany"
+  | "updateMany"
+  | "count"
+  | "aggregate"
+  | "groupBy";
+
+export type QueryDescriptor = {
+  model: string;
+  operation: Operation;
+  args: Record<string, unknown>;
+};
+
+// ─── SQL Builder Output ───────────────────────────────────────────
+
+export type SqlQuery = {
+  text: string;
+  values: unknown[];
+};
+
+// ─── Runtime Helpers (O(1) field/model lookups) ───────────────────
+
+const _sfMapCache = new WeakMap<
+  readonly ScalarFieldMeta[],
+  Map<string, ScalarFieldMeta>
+>();
+const _modelNameCache = new WeakMap<object, Map<string, ModelMeta>>();
+
+/**
+ * Get or build a Map<fieldName, ScalarFieldMeta> for O(1) lookups.
+ * Lazily builds and caches the Map per scalarFields array reference.
+ */
+export function getScalarFieldMap(params: {
+  scalarFields: readonly ScalarFieldMeta[];
+}): ReadonlyMap<string, ScalarFieldMeta> {
+  const { scalarFields } = params;
+  let map = _sfMapCache.get(scalarFields);
+  if (!map) {
+    map = new Map(scalarFields.map((f) => [f.name, f]));
+    _sfMapCache.set(scalarFields, map);
+  }
+  return map;
+}
+
+/**
+ * Get or build a Map<modelName, ModelMeta> for O(1) lookups by PascalCase model name.
+ * Lazily builds and caches the Map per allModelsMeta reference.
+ */
+export function getModelByNameMap(params: {
+  allModelsMeta: ModelMetaMap;
+}): ReadonlyMap<string, ModelMeta> {
+  const { allModelsMeta } = params;
+  let map = _modelNameCache.get(allModelsMeta);
+  if (!map) {
+    map = new Map(
+      Object.values(allModelsMeta).map((m) => [m.name, m])
+    );
+    _modelNameCache.set(allModelsMeta, map);
+  }
+  return map;
+}
+
+// ─── PostgreSQL Array Parameter Wrapper ───────────────────────────
+
+/**
+ * Wrapper to tag a JS array as a PostgreSQL array parameter for = ANY($N).
+ * Distinguishes from regular JS arrays (JSON values, scalar list ops)
+ * so that the adapter can convert only these to the appropriate format.
+ *
+ * - bun:sql adapter: converts to PG array literal string `{val1,val2,...}`
+ * - pg adapter: returns the raw JS array (pg handles native array serialization)
+ */
+export class PgArray {
+  constructor(public readonly values: unknown[]) {}
+}