@vibeorm/runtime 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/runtime",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Driver-agnostic query engine and client runtime for VibeORM",
   "license": "MIT",
   "keywords": [

package/src/coerce.ts

@@ -41,6 +41,85 @@ function getBigIntFieldNames(modelMeta: ModelMeta): readonly string[] {
   return names;
 }
 
+/**
+ * Per-model cache of enum-array field names. Same WeakMap shape and
+ * lifetime guarantees as `_bigintFieldsCache`.
+ *
+ * Enum-array columns need post-processing because neither `bun:sql` nor
+ * `node-postgres` knows the user-defined enum's array type OID, so the
+ * driver returns the raw PG array literal as a string (e.g. `"{ADMIN,USER}"`)
+ * instead of a JS array. Built-in scalar arrays (`text[]`, `int4[]`, …) ARE
+ * parsed by both drivers because their OIDs are well-known.
+ */
+const _enumListFieldsCache = new WeakMap<
+  readonly ScalarFieldMeta[],
+  readonly string[]
+>();
+
+function getEnumListFieldNames(modelMeta: ModelMeta): readonly string[] {
+  const sf = modelMeta.scalarFields;
+  let names = _enumListFieldsCache.get(sf);
+  if (names) return names;
+  const arr: string[] = [];
+  for (const f of sf) {
+    if (f.kind === "enum" && f.isList === true) arr.push(f.name);
+  }
+  names = arr;
+  _enumListFieldsCache.set(sf, names);
+  return names;
+}
+
+/**
+ * Parse a PostgreSQL array literal string into a JS array of strings.
+ *
+ * Format: `{val1,val2,"quoted,val",NULL,...}` with `""` quoting only when an
+ * element contains commas, double-quotes, backslashes, or is the literal
+ * `NULL`. PG uses backslash-escaping inside quoted elements.
+ *
+ * Returns `[]` for `{}`. Returns the input unchanged if it doesn't look like
+ * an array literal (defensive — should never happen for an enum-array column).
+ */
+function parsePgArrayLiteral(literal: string): string[] | string {
+  if (literal.length < 2 || literal.charCodeAt(0) !== 123 /* { */) return literal;
+  if (literal === "{}") return [];
+
+  const out: string[] = [];
+  const inner = literal.slice(1, -1);
+  let i = 0;
+  const len = inner.length;
+  while (i < len) {
+    if (inner.charCodeAt(i) === 34 /* " */) {
+      // Quoted element — read until matching close-quote, honouring \\ and \"
+      let s = "";
+      i++;
+      while (i < len) {
+        const ch = inner.charCodeAt(i);
+        if (ch === 92 /* \ */) {
+          s += inner[i + 1] ?? "";
+          i += 2;
+        } else if (ch === 34) {
+          i++;
+          break;
+        } else {
+          s += inner[i];
+          i++;
+        }
+      }
+      out.push(s);
+    } else {
+      // Unquoted element — read until next comma or end
+      let s = "";
+      while (i < len && inner.charCodeAt(i) !== 44 /* , */) {
+        s += inner[i];
+        i++;
+      }
+      out.push(s);
+    }
+    if (i < len && inner.charCodeAt(i) === 44 /* , */) i++;
+  }
+  return out;
+}
+
 /**
  * Coerce scalar field values on the given records to their JS-native types.
  *
@@ -59,7 +138,8 @@ export function coerceFieldTypes(params: {
   if (records.length === 0) return;
 
   const bigintNames = getBigIntFieldNames(modelMeta);
-  if (bigintNames.length === 0) return;
+  const enumListNames = getEnumListFieldNames(modelMeta);
+  if (bigintNames.length === 0 && enumListNames.length === 0) return;
 
   for (const record of records) {
     for (const name of bigintNames) {
@@ -70,6 +150,16 @@ export function coerceFieldTypes(params: {
         record[name] = BigInt(val);
       }
     }
+    // Enum-array fields arrive as raw PG array literal strings from both
+    // bun:sql and node-postgres (the driver doesn't know the user-defined
+    // enum's array OID). Parse them into JS string arrays. Bug 2 + Bug 3.
+    for (const name of enumListNames) {
+      const val = record[name];
+      if (typeof val === "string") {
+        const parsed = parsePgArrayLiteral(val);
+        if (Array.isArray(parsed)) record[name] = parsed;
+      }
+    }
   }
 }
 
@@ -82,3 +172,13 @@ export function coerceFieldTypes(params: {
 export function modelHasBigInt(modelMeta: ModelMeta): boolean {
   return getBigIntFieldNames(modelMeta).length > 0;
 }
+
+/**
+ * True iff the model has any fields that need post-driver coercion
+ * (BigInt OR enum-array). Use this in place of `modelHasBigInt` whenever
+ * the fast-path skip would otherwise miss enum-array fields (Bug 2).
+ */
+export function modelNeedsCoercion(modelMeta: ModelMeta): boolean {
+  return getBigIntFieldNames(modelMeta).length > 0
+    || getEnumListFieldNames(modelMeta).length > 0;
+}

package/src/errors.ts

@@ -51,6 +51,7 @@ export type VibeRequestErrorCode =
   | "FOREIGN_KEY_VIOLATION"
   | "NOT_NULL_VIOLATION"
   | "CHECK_CONSTRAINT"
+  | "VALUE_OUT_OF_RANGE"
   | "NOT_FOUND"
   | "VALIDATION_ERROR"
   | "UNKNOWN_REQUEST_ERROR";
@@ -238,6 +239,16 @@ const CONSTRAINT_CODE_MAP: Record<string, VibeRequestErrorCode> = {
   "23514": "CHECK_CONSTRAINT",
 };
 
+/**
+ * SQLSTATE Class 22 — data exception. We map the specific codes we want to
+ * surface as actionable errors. 22003 is the canonical "value out of range
+ * for type" code; the most common way users hit it is inserting a `BigInt`
+ * value larger than 2^63-1 into a `bigint` column (Bug 9).
+ */
+const DATA_EXCEPTION_CODE_MAP: Record<string, VibeRequestErrorCode> = {
+  "22003": "VALUE_OUT_OF_RANGE",
+};
+
 /**
  * Extract a field name from a PostgreSQL detail string.
  *
@@ -410,6 +421,27 @@ export function normalizeError(params: {
       });
     }
 
+    // Data exception (Class 22): e.g. value out of range for the column type.
+    // Specifically: 22003 is what users see when a BigInt value overflows the
+    // signed-int64 limit on a `bigint` column. We surface a targeted hint for
+    // that case because the raw PG message ("value out of range for type
+    // bigint") is easy to misread as a driver bug. Bug 9.
+    const dataExceptionCode = DATA_EXCEPTION_CODE_MAP[pgCode];
+    if (dataExceptionCode) {
+      const isBigIntRange =
+        dataExceptionCode === "VALUE_OUT_OF_RANGE" &&
+        /out of range for type bigint/i.test(pgErr.message);
+      const message = isBigIntRange
+        ? `${pgErr.message} (PostgreSQL bigint is signed int64, max 0x7fffffffffffffff = 2^63-1. For unsigned 64-bit values, store as String or Decimal.)`
+        : pgErr.message;
+      return new VibeRequestError({
+        code: dataExceptionCode,
+        message,
+        meta,
+        cause,
+      });
+    }
+
     // Check transient by SQLSTATE class prefix
     if (pgCode.startsWith("08") || pgCode.startsWith("40")) {
       return new VibeTransientError({

package/src/index.ts

@@ -24,6 +24,7 @@ export { withRetry } from "./retry.ts";
 export { ViewResult, createView } from "./view.ts";
 export type { ViewDefinition } from "./view.ts";
 export type { RetryOptions } from "./retry.ts";
+export { PgArray } from "./types.ts";
 
 export type {
   DatabaseAdapter,

package/src/lateral-join-builder.ts

@@ -49,7 +49,7 @@ import { buildWhereClause } from "./where-builder.ts";
 import { sanitizeDirection } from "./query-builder.ts";
 import { loadRelations, resolveRelationsToLoad, hasNestedRelations } from "./relation-loader.ts";
 import type { RelationToLoad } from "./relation-loader.ts";
-import { coerceFieldTypes, modelHasBigInt } from "./coerce.ts";
+import { coerceFieldTypes, modelNeedsCoercion } from "./coerce.ts";
 import { resolveCountSpec, loadRelationCounts } from "./count-loader.ts";
 
 type SqlExecutor = (params: {
@@ -677,15 +677,15 @@ export async function executeLateralJoinQuery(params: {
   // lateral-join strategy bypasses both, so we do the equivalent work here
   // (Bug #6).
   //
-  // Performance: pre-compute which relation aliases actually need BigInt
-  // coercion (by looking at the related model's scalar fields). Wide schemas
-  // with many includes thus pay nothing extra for relations whose child model
-  // has no BigInt fields.
+  // Performance: pre-compute which relation aliases actually need coercion
+  // (BigInt or enum-array — see `modelNeedsCoercion`). Wide schemas with
+  // many includes thus pay nothing extra for relations whose child model
+  // has neither.
   const nestedModelMap = getModelByNameMap({ allModelsMeta });
   const relationCoerceMeta = relationAliases.map(({ relationMeta }) => {
     const relatedModelMeta = nestedModelMap.get(relationMeta.relatedModel);
     if (!relatedModelMeta) return null;
-    return modelHasBigInt(relatedModelMeta) ? relatedModelMeta : null;
+    return modelNeedsCoercion(relatedModelMeta) ? relatedModelMeta : null;
   });
 
   const results: Record<string, unknown>[] = [];