@drzl/analyzer 1.17.0 → 1.17.2

package/README.md

@@ -51,7 +51,7 @@ Per column, beyond the type: `nullable`, `hasDefault`, `defaultValue` (literal d
 `isGenerated`, `enumValues`, `maxLength` (characters), `maxBytes` (MySQL's TEXT family is a byte
 budget, which is a different measurement on the same kind of column), `min`/`max`,
 `arrayDimensions`, `format`, and `shape` for values that are not scalars (json, buffer, tuple,
-vector, bitstring, customType).
+numberObject, vector, bitstring, customType).
 
 `DRZL_ANL_UNKNOWN_COLUMN` is reported for any column whose validator would accept anything, which
 is the shape a missing type mapping takes: nothing throws, and every row passes.

package/dist/index.cjs

@@ -63,13 +63,18 @@ var PG_FLOAT4_INPUT_MAX = "340282356779733661637539395458142568448";
 var PG_FLOAT4_RANGE = [`-${PG_FLOAT4_INPUT_MAX}`, PG_FLOAT4_INPUT_MAX];
 var MYSQL_FLOAT_RANGE = [`-${FLOAT32_MAX}`, FLOAT32_MAX];
 var JS_SAFE_INTEGER_BOUNDS = ["-9007199254740991", "9007199254740991"];
-var TUPLE_CLASS_SHAPES = {
+var GEOMETRIC_CLASS_SHAPES = {
   // `line()` is the trap here: its `drizzle:entityKind` is `PgLine` while its constructor is
   // `PgLineTuple`, and this path matches on the constructor.
   PgPointTuple: { kind: "tuple", length: 2 },
-  PgLineTuple: { kind: "tuple", length: 3 }
+  PgLineTuple: { kind: "tuple", length: 3 },
+  // The object modes. `line({ mode: 'abc' })` is a `PgLineABC` and not a `PgLineObject`, and any
+  // mode but `'tuple'` builds the object class: `point({ mode: 'abc' })` is a `PgPointObject` too.
+  PgPointObject: { kind: "numberObject", fields: ["x", "y"] },
+  PgLineABC: { kind: "numberObject", fields: ["a", "b", "c"] }
 };
 var V1_ONLY_ENTITY_KINDS = /^(?:MsSql|Cockroach)/;
+var NUMBER_VECTOR_CLASSES = /* @__PURE__ */ new Set(["PgVector", "PgHalfVector"]);
 var BYTE_STRING_CLASSES = /* @__PURE__ */ new Set([
   "MySqlBinary",
   "MySqlVarBinary",
@@ -190,18 +195,38 @@ function describeV1Column(column) {
       };
       break;
     }
+    // Two modes per builder, and v1 states which in the JS half of the dataType it already
+    // carries: the tuple modes say `array point` / `array line` / `array geometry` and the object
+    // modes say `object point` / `object line` / `object geometry`. Read off real 1.0.0-rc.4
+    // columns rather than assumed. Both used to reach these arms and be called tuples, so a select
+    // schema for `point({ mode: 'xy' })` rejected every row the driver returned, on the major that
+    // describes the column outright.
+    //
+    // `js` rather than the codec, which also distinguishes them here (`point:tuple` against
+    // `point`): three dialects state a semantic with no codec at all on this release, so the codec
+    // is the weaker of the two signals and this file already prefers `js` elsewhere for the same
+    // reason.
     case "point":
     case "geometry":
-      out.tsType = "[number, number]";
+      out.tsType = js === "object" ? "{ x: number; y: number }" : "[number, number]";
       out.dbType = semantic.toUpperCase();
-      out.shape = { kind: "tuple", length: 2 };
+      out.shape = js === "object" ? { kind: "numberObject", fields: ["x", "y"] } : { kind: "tuple", length: 2 };
       break;
     case "line":
-      out.tsType = "[number, number, number]";
+      out.tsType = js === "object" ? "{ a: number; b: number; c: number }" : "[number, number, number]";
       out.dbType = "LINE";
-      out.shape = { kind: "tuple", length: 3 };
+      out.shape = js === "object" ? { kind: "numberObject", fields: ["a", "b", "c"] } : { kind: "tuple", length: 3 };
       break;
+    // `halfvec` beside `vector`, because they differ in storage width and in nothing a validator
+    // can see: `mapFromDriverValue` on both hands back `[1, 2, 3]`. It had no arm and came back
+    // `unknown` on this path too, which the fuzzer found.
+    //
+    // `sparsevec` is deliberately not here. Its name says vector and its value is the string
+    // `{1:1.5,3:2}/3`, so typing it `number[]` for symmetry would reject every row the database
+    // returns. Its codec already answers `string` on its own, which is the same conclusion reached
+    // without this arm.
     case "vector":
+    case "halfvec":
       out.tsType = "number[]";
       out.dbType = "VECTOR";
       out.shape = { kind: "numberVector", length: declaredLength(column) };
@@ -578,7 +603,37 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       // 0.4x gives an enum its own class, which had no arm here at all, so an enum column came
       // back `unknown` and every generator emitted a schema that accepted anything. The values
       // were on the column the whole time, in `enumValues`, waiting for a type to attach to.
+      //
+      // The MySQL and SingleStore classes were added later than the Postgres one, and their
+      // absence showed up somewhere unexpected: the emitted validator was already right, because
+      // every generator reads `enumValues` before it reads `tsType`, so the only thing wrong was
+      // the description. That description reached the user anyway, through the untyped-column
+      // warning, which said an enum column "will accept any value" while the emitted schema
+      // accepted exactly three. A warning that is wrong about the one thing it names is worse
+      // than no warning, because it teaches the reader to skip the true ones.
+      //
+      // v1 already answered `string` here, so this is also the two majors agreeing again rather
+      // than a new opinion; the cross-major diff carried the disagreement as a filed defect.
       case "PgEnumColumn":
+      case "MySqlEnumColumn":
+      case "SingleStoreEnumColumn":
+        return { tsType: "string", dbType: "TEXT" };
+      // The pgvector family, found by the analyzer fuzzer: all three came back `unknown` on this
+      // path, so their validators accepted anything. The answers are drizzle's own mappers rather
+      // than the type names, and the three do not agree with each other:
+      //
+      //   vector(3)     SELECT gives [1,2,3]          INSERT sends "[1,2,3]"
+      //   halfvec(3)    SELECT gives [1,2,3]          INSERT sends "[1,2,3]"
+      //   sparsevec(3)  SELECT gives "{1:1.5,3:2}/3"  INSERT sends "{1:1.5,3:2}/3"
+      //
+      // So the two dense ones are number arrays and the sparse one is a string. Typing `sparsevec`
+      // as a vector for symmetry would reject every row the database returns, which is the defect
+      // this family was filed under to begin with. The `shape` carries the dimension count where
+      // one is declared, as the codec path already did for `vector`.
+      case "PgVector":
+      case "PgHalfVector":
+        return { tsType: "number[]", dbType: "VECTOR" };
+      case "PgSparseVector":
         return { tsType: "string", dbType: "TEXT" };
       case "PgInteger":
       case "PgSmallInt":
@@ -645,6 +700,15 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         return { tsType: "[number, number]", dbType: "POINT" };
       case "PgLineTuple":
         return { tsType: "[number, number, number]", dbType: "LINE" };
+      // The object modes, which the same regex answered `string` for and which are not tuples
+      // either. `point({ mode: 'xy' })` returns `{ x, y }` and `line({ mode: 'abc' })` returns
+      // `{ a, b, c }`, read back from PGlite through drizzle 0.45.2; the same column refuses
+      // `[1, 2]` and `'1,2'`, both of which `mapToDriverValue` renders `(undefined,undefined)`.
+      // v1 says the same thing about the same two columns through `dataType: 'object point'`.
+      case "PgPointObject":
+        return { tsType: "{ x: number; y: number }", dbType: "POINT" };
+      case "PgLineABC":
+        return { tsType: "{ a: number; b: number; c: number }", dbType: "LINE" };
       case "PgJson":
       case "PgJsonb":
         return { tsType: "any", dbType: ctor === "PgJsonb" ? "JSONB" : "JSON" };
@@ -665,7 +729,6 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         if (/^Pg/.test(ctor)) {
           if (/Text|Varchar|Char|Uuid/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
           if (/Inet|Cidr|Macaddr8?|Uuid/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
-          if (/Point|Line/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
           if (/TimestampString|DateString/i.test(ctor))
             return { tsType: "string", dbType: "TIMESTAMP" };
           if (/Timestamptz/i.test(ctor)) return { tsType: "Date", dbType: "TIMESTAMPTZ" };
@@ -787,7 +850,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       const sqlType = sqlKind.startsWith("MySql") && typeof col?.getSQLType === "function" ? String(col.getSQLType()).toLowerCase() : void 0;
       const byteCap = sqlType ? MYSQL_TEXT_CAPS[sqlType] : void 0;
       const ctorName = String(col?.constructor?.name ?? "");
-      const fallbackShape = dbType === "JSON" || dbType === "JSONB" || col?.config?.mode === "json" ? { kind: "json" } : BYTE_STRING_CLASSES.has(ctorName) ? { kind: "byteString", length: declaredLength(col) } : TUPLE_CLASS_SHAPES[ctorName];
+      const fallbackShape = dbType === "JSON" || dbType === "JSONB" || col?.config?.mode === "json" ? { kind: "json" } : BYTE_STRING_CLASSES.has(ctorName) ? { kind: "byteString", length: declaredLength(col) } : NUMBER_VECTOR_CLASSES.has(ctorName) ? { kind: "numberVector", length: declaredLength(col) } : GEOMETRIC_CLASS_SHAPES[ctorName];
       if (fallbackShape?.kind === "byteString") delete constraints.maxLength;
       const shape = (v1?.shape ?? fallbackShape)?.kind;
       const finalTs = v1?.tsType ?? tsType;

package/dist/index.d.cts

@@ -121,11 +121,33 @@ type ColumnShape =
  | {
     kind: 'json';
 }
-/** `point`, `line`, `geometry`: a fixed-length tuple of numbers. */
+/** `point`, `line`, `geometry` in their tuple modes: a fixed-length tuple of numbers. */
  | {
     kind: 'tuple';
     length: number;
 }
+/**
+ * The same three columns in their object modes: an object of named number fields.
+ *
+ * `point({ mode: 'xy' })` hands back `{ x, y }`, `line({ mode: 'abc' })` hands back
+ * `{ a, b, c }`, and `geometry({ type: 'point', mode: 'xy' })` hands back `{ x, y }`. The names
+ * are carried rather than derived from a length, because the two arities have different keys and
+ * nothing else on the column states them.
+ *
+ * Not a tuple, on either major, and the difference is a value the database refuses. Asked of
+ * PGlite through drizzle 0.45.2 and again through 1.0.0-rc.4: `mapToDriverValue` reads `.x`/`.y`
+ * off whatever it is handed, so `[1, 2]` and `'1,2'` both become the literal
+ * `(undefined,undefined)` and Postgres answers `invalid input syntax for type point`, while
+ * `{ x: 1.5, y: -2.25 }` is stored as `(1.5,-2.25)` and read back unchanged.
+ *
+ * Every field is required and unlisted keys are ignored, both measured on the same server:
+ * `{ x: 1 }` renders `(1,undefined)` and is refused, and `{ x: 1, y: 2, z: 3 }` is accepted and
+ * stored as `(1,2)`.
+ */
+ | {
+    kind: 'numberObject';
+    fields: string[];
+}
 /** `vector`, `halfvec`: a numeric vector, with a fixed length where one is declared. */
  | {
     kind: 'numberVector';

package/dist/index.d.ts

@@ -121,11 +121,33 @@ type ColumnShape =
  | {
     kind: 'json';
 }
-/** `point`, `line`, `geometry`: a fixed-length tuple of numbers. */
+/** `point`, `line`, `geometry` in their tuple modes: a fixed-length tuple of numbers. */
  | {
     kind: 'tuple';
     length: number;
 }
+/**
+ * The same three columns in their object modes: an object of named number fields.
+ *
+ * `point({ mode: 'xy' })` hands back `{ x, y }`, `line({ mode: 'abc' })` hands back
+ * `{ a, b, c }`, and `geometry({ type: 'point', mode: 'xy' })` hands back `{ x, y }`. The names
+ * are carried rather than derived from a length, because the two arities have different keys and
+ * nothing else on the column states them.
+ *
+ * Not a tuple, on either major, and the difference is a value the database refuses. Asked of
+ * PGlite through drizzle 0.45.2 and again through 1.0.0-rc.4: `mapToDriverValue` reads `.x`/`.y`
+ * off whatever it is handed, so `[1, 2]` and `'1,2'` both become the literal
+ * `(undefined,undefined)` and Postgres answers `invalid input syntax for type point`, while
+ * `{ x: 1.5, y: -2.25 }` is stored as `(1.5,-2.25)` and read back unchanged.
+ *
+ * Every field is required and unlisted keys are ignored, both measured on the same server:
+ * `{ x: 1 }` renders `(1,undefined)` and is refused, and `{ x: 1, y: 2, z: 3 }` is accepted and
+ * stored as `(1,2)`.
+ */
+ | {
+    kind: 'numberObject';
+    fields: string[];
+}
 /** `vector`, `halfvec`: a numeric vector, with a fixed length where one is declared. */
  | {
     kind: 'numberVector';

package/dist/index.js

@@ -22,13 +22,18 @@ var PG_FLOAT4_INPUT_MAX = "340282356779733661637539395458142568448";
 var PG_FLOAT4_RANGE = [`-${PG_FLOAT4_INPUT_MAX}`, PG_FLOAT4_INPUT_MAX];
 var MYSQL_FLOAT_RANGE = [`-${FLOAT32_MAX}`, FLOAT32_MAX];
 var JS_SAFE_INTEGER_BOUNDS = ["-9007199254740991", "9007199254740991"];
-var TUPLE_CLASS_SHAPES = {
+var GEOMETRIC_CLASS_SHAPES = {
   // `line()` is the trap here: its `drizzle:entityKind` is `PgLine` while its constructor is
   // `PgLineTuple`, and this path matches on the constructor.
   PgPointTuple: { kind: "tuple", length: 2 },
-  PgLineTuple: { kind: "tuple", length: 3 }
+  PgLineTuple: { kind: "tuple", length: 3 },
+  // The object modes. `line({ mode: 'abc' })` is a `PgLineABC` and not a `PgLineObject`, and any
+  // mode but `'tuple'` builds the object class: `point({ mode: 'abc' })` is a `PgPointObject` too.
+  PgPointObject: { kind: "numberObject", fields: ["x", "y"] },
+  PgLineABC: { kind: "numberObject", fields: ["a", "b", "c"] }
 };
 var V1_ONLY_ENTITY_KINDS = /^(?:MsSql|Cockroach)/;
+var NUMBER_VECTOR_CLASSES = /* @__PURE__ */ new Set(["PgVector", "PgHalfVector"]);
 var BYTE_STRING_CLASSES = /* @__PURE__ */ new Set([
   "MySqlBinary",
   "MySqlVarBinary",
@@ -149,18 +154,38 @@ function describeV1Column(column) {
       };
       break;
     }
+    // Two modes per builder, and v1 states which in the JS half of the dataType it already
+    // carries: the tuple modes say `array point` / `array line` / `array geometry` and the object
+    // modes say `object point` / `object line` / `object geometry`. Read off real 1.0.0-rc.4
+    // columns rather than assumed. Both used to reach these arms and be called tuples, so a select
+    // schema for `point({ mode: 'xy' })` rejected every row the driver returned, on the major that
+    // describes the column outright.
+    //
+    // `js` rather than the codec, which also distinguishes them here (`point:tuple` against
+    // `point`): three dialects state a semantic with no codec at all on this release, so the codec
+    // is the weaker of the two signals and this file already prefers `js` elsewhere for the same
+    // reason.
     case "point":
     case "geometry":
-      out.tsType = "[number, number]";
+      out.tsType = js === "object" ? "{ x: number; y: number }" : "[number, number]";
       out.dbType = semantic.toUpperCase();
-      out.shape = { kind: "tuple", length: 2 };
+      out.shape = js === "object" ? { kind: "numberObject", fields: ["x", "y"] } : { kind: "tuple", length: 2 };
       break;
     case "line":
-      out.tsType = "[number, number, number]";
+      out.tsType = js === "object" ? "{ a: number; b: number; c: number }" : "[number, number, number]";
       out.dbType = "LINE";
-      out.shape = { kind: "tuple", length: 3 };
+      out.shape = js === "object" ? { kind: "numberObject", fields: ["a", "b", "c"] } : { kind: "tuple", length: 3 };
       break;
+    // `halfvec` beside `vector`, because they differ in storage width and in nothing a validator
+    // can see: `mapFromDriverValue` on both hands back `[1, 2, 3]`. It had no arm and came back
+    // `unknown` on this path too, which the fuzzer found.
+    //
+    // `sparsevec` is deliberately not here. Its name says vector and its value is the string
+    // `{1:1.5,3:2}/3`, so typing it `number[]` for symmetry would reject every row the database
+    // returns. Its codec already answers `string` on its own, which is the same conclusion reached
+    // without this arm.
     case "vector":
+    case "halfvec":
       out.tsType = "number[]";
       out.dbType = "VECTOR";
       out.shape = { kind: "numberVector", length: declaredLength(column) };
@@ -537,7 +562,37 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       // 0.4x gives an enum its own class, which had no arm here at all, so an enum column came
       // back `unknown` and every generator emitted a schema that accepted anything. The values
       // were on the column the whole time, in `enumValues`, waiting for a type to attach to.
+      //
+      // The MySQL and SingleStore classes were added later than the Postgres one, and their
+      // absence showed up somewhere unexpected: the emitted validator was already right, because
+      // every generator reads `enumValues` before it reads `tsType`, so the only thing wrong was
+      // the description. That description reached the user anyway, through the untyped-column
+      // warning, which said an enum column "will accept any value" while the emitted schema
+      // accepted exactly three. A warning that is wrong about the one thing it names is worse
+      // than no warning, because it teaches the reader to skip the true ones.
+      //
+      // v1 already answered `string` here, so this is also the two majors agreeing again rather
+      // than a new opinion; the cross-major diff carried the disagreement as a filed defect.
       case "PgEnumColumn":
+      case "MySqlEnumColumn":
+      case "SingleStoreEnumColumn":
+        return { tsType: "string", dbType: "TEXT" };
+      // The pgvector family, found by the analyzer fuzzer: all three came back `unknown` on this
+      // path, so their validators accepted anything. The answers are drizzle's own mappers rather
+      // than the type names, and the three do not agree with each other:
+      //
+      //   vector(3)     SELECT gives [1,2,3]          INSERT sends "[1,2,3]"
+      //   halfvec(3)    SELECT gives [1,2,3]          INSERT sends "[1,2,3]"
+      //   sparsevec(3)  SELECT gives "{1:1.5,3:2}/3"  INSERT sends "{1:1.5,3:2}/3"
+      //
+      // So the two dense ones are number arrays and the sparse one is a string. Typing `sparsevec`
+      // as a vector for symmetry would reject every row the database returns, which is the defect
+      // this family was filed under to begin with. The `shape` carries the dimension count where
+      // one is declared, as the codec path already did for `vector`.
+      case "PgVector":
+      case "PgHalfVector":
+        return { tsType: "number[]", dbType: "VECTOR" };
+      case "PgSparseVector":
         return { tsType: "string", dbType: "TEXT" };
       case "PgInteger":
       case "PgSmallInt":
@@ -604,6 +659,15 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         return { tsType: "[number, number]", dbType: "POINT" };
       case "PgLineTuple":
         return { tsType: "[number, number, number]", dbType: "LINE" };
+      // The object modes, which the same regex answered `string` for and which are not tuples
+      // either. `point({ mode: 'xy' })` returns `{ x, y }` and `line({ mode: 'abc' })` returns
+      // `{ a, b, c }`, read back from PGlite through drizzle 0.45.2; the same column refuses
+      // `[1, 2]` and `'1,2'`, both of which `mapToDriverValue` renders `(undefined,undefined)`.
+      // v1 says the same thing about the same two columns through `dataType: 'object point'`.
+      case "PgPointObject":
+        return { tsType: "{ x: number; y: number }", dbType: "POINT" };
+      case "PgLineABC":
+        return { tsType: "{ a: number; b: number; c: number }", dbType: "LINE" };
       case "PgJson":
       case "PgJsonb":
         return { tsType: "any", dbType: ctor === "PgJsonb" ? "JSONB" : "JSON" };
@@ -624,7 +688,6 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
         if (/^Pg/.test(ctor)) {
           if (/Text|Varchar|Char|Uuid/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
           if (/Inet|Cidr|Macaddr8?|Uuid/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
-          if (/Point|Line/i.test(ctor)) return { tsType: "string", dbType: "TEXT" };
           if (/TimestampString|DateString/i.test(ctor))
             return { tsType: "string", dbType: "TIMESTAMP" };
           if (/Timestamptz/i.test(ctor)) return { tsType: "Date", dbType: "TIMESTAMPTZ" };
@@ -746,7 +809,7 @@ var _SchemaAnalyzer = class _SchemaAnalyzer {
       const sqlType = sqlKind.startsWith("MySql") && typeof col?.getSQLType === "function" ? String(col.getSQLType()).toLowerCase() : void 0;
       const byteCap = sqlType ? MYSQL_TEXT_CAPS[sqlType] : void 0;
       const ctorName = String(col?.constructor?.name ?? "");
-      const fallbackShape = dbType === "JSON" || dbType === "JSONB" || col?.config?.mode === "json" ? { kind: "json" } : BYTE_STRING_CLASSES.has(ctorName) ? { kind: "byteString", length: declaredLength(col) } : TUPLE_CLASS_SHAPES[ctorName];
+      const fallbackShape = dbType === "JSON" || dbType === "JSONB" || col?.config?.mode === "json" ? { kind: "json" } : BYTE_STRING_CLASSES.has(ctorName) ? { kind: "byteString", length: declaredLength(col) } : NUMBER_VECTOR_CLASSES.has(ctorName) ? { kind: "numberVector", length: declaredLength(col) } : GEOMETRIC_CLASS_SHAPES[ctorName];
       if (fallbackShape?.kind === "byteString") delete constraints.maxLength;
       const shape = (v1?.shape ?? fallbackShape)?.kind;
       const finalTs = v1?.tsType ?? tsType;

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@drzl/analyzer",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -22,6 +28,7 @@
   },
   "devDependencies": {
     "drizzle-orm": "^0.45.2",
+    "drizzle-orm-v1": "npm:drizzle-orm@1.0.0-rc.4",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
@@ -45,6 +52,8 @@
   "scripts": {
     "build": "tsup src/index.ts --dts --format esm,cjs --clean",
     "lint": "eslint . --ext .ts",
-    "test": "vitest run --testTimeout=20000"
+    "test": "vitest run --testTimeout=20000",
+    "fuzz": "node test/fuzz/run.mjs",
+    "fuzz:gate": "node test/fuzz/run.mjs --gate"
   }
 }