prisma-ltree 0.5.0 → 0.7.0

package/src/core/codecs.ts

@@ -1,54 +1,24 @@
-import type { JsonValue } from "@prisma/orm-framework/contract/types";
 import {
+  type AnyCodecDescriptor,
   type CodecCallContext,
   CodecImpl,
   type CodecInstanceContext,
   type ColumnHelperFor,
   type ColumnHelperForStrict,
   column,
+  type DataTypeValue,
 } from "@prisma/orm-framework/components/codec";
 import type { ExtractCodecTypes, ProjectionExpr } from "@prisma/orm-family-sql/relational-core/ast";
+import { CastExpr } from "@prisma/orm-family-sql/relational-core/ast";
 import {
   definePostgresCodecs,
   PostgresCodecDescriptor,
 } from "@prisma/orm-target-postgres/target/codec-descriptor";
-import {
-  LTREE_ARRAY_CODEC_ID,
-  LTREE_CODEC_ID,
-  LTREE_MAX_LABEL_LENGTH,
-  LTREE_MAX_LABELS,
-} from "./constants";
+import { assertValidLtree } from "./codecs-validation";
+import { LTREE_ARRAY_CODEC_ID, LTREE_CODEC_ID } from "./constants";
 import { ltreeArrayDataType, ltreeDataType } from "./data-types";
 
-const LABEL_PATTERN = /^[A-Za-z0-9_-]+$/;
-
-export function assertValidLtree(value: unknown): asserts value is string {
-  if (typeof value !== "string") {
-    throw new Error("ltree value must be a string");
-  }
-  if (value.length === 0) {
-    throw new Error("ltree value must not be empty");
-  }
-  const labels = value.split(".");
-  if (labels.length > LTREE_MAX_LABELS) {
-    throw new Error(`ltree path exceeds max labels: got ${labels.length}, max ${LTREE_MAX_LABELS}`);
-  }
-  for (const label of labels) {
-    if (label.length === 0) {
-      throw new Error(`ltree label must not be empty in path "${value}"`);
-    }
-    if (label.length > LTREE_MAX_LABEL_LENGTH) {
-      throw new Error(
-        `ltree label exceeds max length: got ${label.length}, max ${LTREE_MAX_LABEL_LENGTH}`,
-      );
-    }
-    if (!LABEL_PATTERN.test(label)) {
-      throw new Error(
-        `ltree label "${label}" contains invalid characters; allowed: alphanumeric, underscore, hyphen`,
-      );
-    }
-  }
-}
+export { assertValidLtree } from "./codecs-validation";
 
 export class LtreeCodec extends CodecImpl<
   typeof LTREE_CODEC_ID,
@@ -56,30 +26,34 @@ export class LtreeCodec extends CodecImpl<
   string,
   string
 > {
-  async encode(value: string, _ctx: CodecCallContext): Promise<string> {
+  constructor(descriptor: AnyCodecDescriptor) {
+    super(descriptor, ltreeDataType);
+  }
+
+  async toWire(value: string, _ctx: CodecCallContext): Promise<string> {
     assertValidLtree(value);
     return value;
   }
 
-  async decode(wire: string, _ctx: CodecCallContext): Promise<string> {
+  async fromWire(wire: string, _ctx: CodecCallContext): Promise<string> {
     return wire;
   }
 
-  encodeJson(value: string): JsonValue {
+  toDataTypeValue(value: string): DataTypeValue {
     assertValidLtree(value);
-    return value;
+    return this.dataTypeValueOf(value);
   }
 
-  decodeJson(json: JsonValue): string {
-    assertValidLtree(json);
-    return json;
+  fromDataTypeValue(value: DataTypeValue): string {
+    return value.value as string;
   }
 }
 
 export class LtreeDescriptor extends PostgresCodecDescriptor<void> {
+  override readonly jsonType = "string" as const;
   protected override jsonProjection(expression: ProjectionExpr): ProjectionExpr {
-    // ltree's text form is already its canonical JSON string.
-    return expression;
+    // JSON projections read through fromWire; cast so the wire value is text.
+    return CastExpr.as(expression, "text");
   }
   override readonly dataType = ltreeDataType.id;
   override readonly codecId = LTREE_CODEC_ID;
@@ -107,38 +81,41 @@ export class LtreeArrayCodec extends CodecImpl<
   readonly string[],
   readonly string[]
 > {
-  async encode(value: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
+  constructor(descriptor: AnyCodecDescriptor) {
+    super(descriptor, ltreeArrayDataType);
+  }
+
+  async toWire(value: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
     for (const entry of value) {
       assertValidLtree(entry);
     }
     return value;
   }
 
-  async decode(wire: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
+  async fromWire(wire: readonly string[], _ctx: CodecCallContext): Promise<readonly string[]> {
     return wire;
   }
 
-  encodeJson(value: readonly string[]): JsonValue {
+  toDataTypeValue(value: readonly string[]): DataTypeValue {
     for (const entry of value) {
       assertValidLtree(entry);
     }
-    return [...value];
+    return this.dataTypeValueOf([...value]);
   }
 
-  decodeJson(json: JsonValue): readonly string[] {
+  fromDataTypeValue(value: DataTypeValue): readonly string[] {
+    const json = value.value;
     if (!Array.isArray(json)) {
       return [];
     }
-    return json.map((entry) => {
-      assertValidLtree(entry);
-      return String(entry);
-    });
+    return json.map((entry) => String(entry));
   }
 }
 
 export class LtreeArrayDescriptor extends PostgresCodecDescriptor<void> {
+  override readonly jsonType = "array" as const;
   protected override jsonProjection(expression: ProjectionExpr): ProjectionExpr {
-    // ltree[] text form projects as a JSON string array already.
+    // ltree[] already projects as a JSON string array for fromWire.
     return expression;
   }
   override readonly dataType = ltreeArrayDataType.id;

package/src/core/contract-space-constants.ts

@@ -7,6 +7,17 @@ export const LTREE_ARRAY_STORAGE_TYPE = "ltreeArray" as const;
 
 export const LTREE_BASELINE_MIGRATION_NAME = "20260619T2142_install_ltree" as const;
 
+export const LTREE_DECLARE_EXTENSION_MIGRATION_NAME =
+  "20261111T1905_declare_ltree_extension" as const;
+
+export const LTREE_CREATE_EXTENSION_MIGRATION_NAME =
+  "20261111T1904_create_ltree_extension" as const;
+
+export const LTREE_SEARCH_PATH_MIGRATION_NAME = "20261111T1908_find_ltree_on_search_path" as const;
+
+export const LTREE_SEARCH_PATH_INSTALL_MIGRATION_NAME =
+  "20261111T1908_install_ltree_on_search_path" as const;
+
 export const LTREE_INVARIANTS = {
   installLtree: "ltree:install-ltree-v1",
 } as const;

package/src/core/data-types.ts

@@ -2,28 +2,62 @@
  * Data types this extension owns.
  *
  * `ltree` and `ltree[]` are PostgreSQL types the target does not register.
- * A path's canonical form is its label text. An array's canonical form is a
+ * A path's stored form is its label text. An array's stored form is a
  * JSON array of those texts. Both accept text the contract can already write.
  * The texts are what a migration writes and what the catalog reports.
  */
 
-import type { DataType } from "@prisma/orm-framework/components/codec";
+import type { DataType, DataTypeReader } from "@prisma/orm-framework/components/codec";
+import { refuseJsonValue } from "@prisma/orm-framework/components/codec";
 import { sqlDataType } from "@prisma/orm-family-sql/contract/data-type";
 import { pgText } from "@prisma/orm-target-postgres/target/data-types";
+import { assertValidLtree } from "./codecs-validation";
+
+const readLtree: DataTypeReader = (json) => {
+  if (typeof json !== "string") {
+    return refuseJsonValue("ltree/ltree", "an ltree path string", json);
+  }
+  try {
+    assertValidLtree(json);
+  } catch {
+    return refuseJsonValue("ltree/ltree", "a valid ltree path string", json);
+  }
+  return json;
+};
 
 export const ltreeDataType = sqlDataType("ltree/ltree", {
+  read: readLtree,
   texts: [{ text: "ltree", written: true, catalog: true }],
   casts: {
     [pgText.id]: (value) => value,
   },
 });
 
+const readLtreeArray: DataTypeReader = (json) => {
+  const expected = "an array of ltree path strings";
+  if (!Array.isArray(json)) {
+    return refuseJsonValue("ltree/ltree-array", expected, json);
+  }
+  for (const entry of json) {
+    if (typeof entry !== "string") {
+      return refuseJsonValue("ltree/ltree-array", expected, entry);
+    }
+    try {
+      assertValidLtree(entry);
+    } catch {
+      return refuseJsonValue("ltree/ltree-array", expected, entry);
+    }
+  }
+  return json;
+};
+
 /**
  * `sqlDataType` accepts parentheses in a type name and refuses square brackets.
  * PostgreSQL writes this type as `ltree[]`, and `format_type` reports `ltree[]`.
  * Declare the type first, then set that text so a migration and a catalog check use it.
  */
 const ltreeArrayDeclared = sqlDataType("ltree/ltree-array", {
+  read: readLtreeArray,
   listCast: {
     of: [pgText.id],
     cast: (elements) => [...elements],

package/src/core/descriptor-meta.ts

@@ -11,6 +11,7 @@ import type { QueryOperationTypes } from "../types/operation-types";
 import { ltreeAuthoringTypes } from "./authoring";
 import { LTREE_ARRAY_CODEC_ID, LTREE_CODEC_ID } from "./constants";
 import { ltreeDataTypes } from "./data-types";
+import { assertPatternArg } from "./pattern-validation";
 import { ltreeCodecRegistry } from "./registry";
 
 type CodecTypesBase = Record<string, { readonly input: unknown; readonly output: unknown }>;
@@ -57,8 +58,10 @@ export function ltreeQueryOperations<CT extends CodecTypesBase>(): QueryOperatio
   // Hierarchy operators compare two `ltree` values; the user argument shares the
   // column's `pg/ltree@1` codec. Pattern-match operators take a query/pattern
   // string (or `string[]`) that is NOT an ltree — it is bound as text and cast
-  // in-template to `lquery` / `lquery[]` / `ltxtquery` (the validated-string-param
-  // approach; verified executable under PGlite).
+  // in-template to `lquery` / `lquery[]` / `ltxtquery`. Literal string args get a
+  // lightweight structural check first (see `pattern-validation.ts`) so empty /
+  // obviously illegal patterns fail with a clear pack error instead of an opaque
+  // Postgres cast failure; Expression / ParamRef binds still defer to Postgres.
   const hierarchyOp = (
     method: string,
     operator: string,
@@ -80,11 +83,12 @@ export function ltreeQueryOperations<CT extends CodecTypesBase>(): QueryOperatio
   const patternOp = (
     method: string,
     operator: string,
-    castType: string,
+    castType: "lquery" | "ltxtquery" | "lquery[]",
     self: CodecExpression<typeof LTREE_CODEC_ID, boolean, CT>,
     arg: unknown,
     many = false,
   ): BoolReturn => {
+    assertPatternArg(castType, arg);
     const selfCodec = codecOf(self);
     return buildOperation({
       method,
@@ -118,6 +122,34 @@ export function ltreeQueryOperations<CT extends CodecTypesBase>(): QueryOperatio
       lowering: { targetFamily: "sql", template },
     });
 
+  // Boolean operators on an `ltree[]` receiver (ADR-007). Same bind/cast rules as
+  // `firstMatchOp`, but the result is `boolean`. These are the operators
+  // `gist__ltree_ops` indexes (`<@`, `~`, `@`, `?`), plus `@>` which PostgreSQL
+  // ships and the opclass does not index.
+  const arrayBoolOp = (
+    method: string,
+    operator: string,
+    self: CodecExpression<typeof LTREE_ARRAY_CODEC_ID, boolean, CT>,
+    arg: unknown,
+    argCodecId: typeof LTREE_CODEC_ID | typeof TEXT_CODEC_ID,
+    castType?: "lquery" | "ltxtquery" | "lquery[]",
+    many = false,
+  ): BoolReturn => {
+    if (castType) assertPatternArg(castType, arg);
+    const template = castType
+      ? `{{self}} ${operator} ({{arg0}})::${castType}`
+      : `{{self}} ${operator} {{arg0}}`;
+    return buildOperation({
+      method,
+      args: [
+        toExpr(self, codecOf(self)),
+        toExpr(arg, many ? { codecId: argCodecId, many: true } : { codecId: argCodecId }),
+      ],
+      returns: BOOL_RETURN,
+      lowering: { targetFamily: "sql", template },
+    });
+  };
+
   // Tier 3 — first-match operators on an `ltree[]` receiver (ADR-003).
   const firstMatchOp = (
     method: string,
@@ -125,8 +157,9 @@ export function ltreeQueryOperations<CT extends CodecTypesBase>(): QueryOperatio
     self: CodecExpression<typeof LTREE_ARRAY_CODEC_ID, boolean, CT>,
     arg: unknown,
     argCodecId: typeof LTREE_CODEC_ID | typeof TEXT_CODEC_ID,
-    castType?: string,
+    castType?: "lquery" | "ltxtquery",
   ): LtreeReturn => {
+    if (castType) assertPatternArg(castType, arg);
     const selfCodec = codecOf(self);
     const template = castType
       ? `{{self}} ${operator} ({{arg0}})::${castType}`
@@ -281,6 +314,33 @@ export function ltreeQueryOperations<CT extends CodecTypesBase>(): QueryOperatio
       impl: (self, query) =>
         firstMatchOp("firstMatchLtxtquery", "?@", self, query, TEXT_CODEC_ID, "ltxtquery"),
     },
+    // Boolean array operators (ADR-007). Distinct names from scalar methods because
+    // the operation registry keys by name only. `containsDescendantOf`,
+    // `matchesAnyLquery`, `matchesAnyLtxtquery`, and `matchesAnyLqueryArray` are
+    // in `gist__ltree_ops`; `containsAncestorOf` is not.
+    containsAncestorOf: {
+      self: { codecId: LTREE_ARRAY_CODEC_ID },
+      impl: (self, other) => arrayBoolOp("containsAncestorOf", "@>", self, other, LTREE_CODEC_ID),
+    },
+    containsDescendantOf: {
+      self: { codecId: LTREE_ARRAY_CODEC_ID },
+      impl: (self, other) => arrayBoolOp("containsDescendantOf", "<@", self, other, LTREE_CODEC_ID),
+    },
+    matchesAnyLquery: {
+      self: { codecId: LTREE_ARRAY_CODEC_ID },
+      impl: (self, pattern) =>
+        arrayBoolOp("matchesAnyLquery", "~", self, pattern, TEXT_CODEC_ID, "lquery"),
+    },
+    matchesAnyLqueryArray: {
+      self: { codecId: LTREE_ARRAY_CODEC_ID },
+      impl: (self, patterns) =>
+        arrayBoolOp("matchesAnyLqueryArray", "?", self, patterns, TEXT_CODEC_ID, "lquery[]", true),
+    },
+    matchesAnyLtxtquery: {
+      self: { codecId: LTREE_ARRAY_CODEC_ID },
+      impl: (self, query) =>
+        arrayBoolOp("matchesAnyLtxtquery", "@", self, query, TEXT_CODEC_ID, "ltxtquery"),
+    },
     // `lca(ltree[])` — array-receiver form (ADR-001, ADR-005). Named `lcaAll`
     // because prisma-next keys operations by name only (`createOperationRegistry`
     // throws on a duplicate); `lca` is already the variadic scalar method on

package/src/core/hierarchy-collection-methods.ts

@@ -0,0 +1,111 @@
+import type {
+  CollectionMethodBody,
+  CollectionMethodContribution,
+  CollectionMethodContributionId,
+  CollectionMethodContributionType,
+  CollectionMethodModelType,
+} from "@prisma/orm-family-sql/relational-core/collection-methods";
+import { blindCast } from "@prisma/orm-framework/utils/casts";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+import type { Ltree } from "../types/codec-types";
+import { LTREE_CODEC_ID } from "./constants";
+
+type LtreeFieldNames<Fields> = {
+  [Name in keyof Fields]: Fields[Name] extends { readonly many: object }
+    ? never
+    : Fields[Name] extends {
+          readonly type: { readonly codecId: typeof LTREE_CODEC_ID };
+        }
+      ? Name
+      : never;
+}[keyof Fields];
+
+type HierarchyMethodTable<Model extends CollectionMethodModelType> = {
+  readonly [Name in LtreeFieldNames<Model["fields"]> & string as `${Name}_descendants`]: {
+    readonly parameters: readonly [root: Ltree];
+    readonly filters: true;
+    readonly orders: false;
+  };
+} & {
+  readonly [Name in LtreeFieldNames<Model["fields"]> & string as `${Name}_ancestors`]: {
+    readonly parameters: readonly [leaf: Ltree];
+    readonly filters: true;
+    readonly orders: false;
+  };
+};
+
+/**
+ * One `{field}_descendants` / `{field}_ancestors` method per scalar `ltree`
+ * field. Descendants map to `isDescendantOf` (`<@`); ancestors map to
+ * `isAncestorOf` (`@>`). Both are inclusive of equality, matching PostgreSQL.
+ */
+export interface LtreeHierarchyMethods extends CollectionMethodContributionType {
+  readonly methods: HierarchyMethodTable<this["model"]>;
+}
+
+declare module "@prisma/orm-family-sql/relational-core/collection-methods" {
+  interface CollectionMethodRegistry {
+    readonly "ltree/hierarchy": LtreeHierarchyMethods;
+  }
+}
+
+interface HierarchyField {
+  isDescendantOf(root: Ltree): unknown;
+  isAncestorOf(leaf: Ltree): unknown;
+}
+
+type LtreeFields = Readonly<Record<string, HierarchyField>>;
+
+function fieldOf(model: unknown, field: string): HierarchyField {
+  const accessor = blindCast<
+    LtreeFields,
+    "an ltree field of the ORM model accessor has hierarchy operators"
+  >(model)[field];
+  if (accessor === undefined) {
+    throw new InternalError(`The model accessor has no ltree field "${field}".`);
+  }
+  return accessor;
+}
+
+function descendantsMethod(field: string): CollectionMethodBody {
+  return (collection, ...args) => {
+    const [root] = blindCast<readonly [Ltree], "the type half declares a root path">(args);
+    return collection.where((model) => fieldOf(model, field).isDescendantOf(root));
+  };
+}
+
+function ancestorsMethod(field: string): CollectionMethodBody {
+  return (collection, ...args) => {
+    const [leaf] = blindCast<readonly [Ltree], "the type half declares a leaf path">(args);
+    return collection.where((model) => fieldOf(model, field).isAncestorOf(leaf));
+  };
+}
+
+function isScalarLtreeField(field: unknown): boolean {
+  if (typeof field !== "object" || field === null) return false;
+  const record = field as {
+    readonly many?: unknown;
+    readonly type?: { readonly kind?: string; readonly codecId?: string };
+  };
+  return (
+    record.many === undefined &&
+    record.type?.kind === "scalar" &&
+    record.type.codecId === LTREE_CODEC_ID
+  );
+}
+
+/** The run-time half of `LtreeHierarchyMethods`. */
+export const ltreeHierarchyMethods: CollectionMethodContribution = {
+  id: "ltree/hierarchy" satisfies CollectionMethodContributionId,
+  methodsFor: (model) =>
+    Object.fromEntries(
+      Object.entries(model.fields).flatMap(([name, field]) =>
+        isScalarLtreeField(field)
+          ? [
+              [`${name}_descendants`, descendantsMethod(name)],
+              [`${name}_ancestors`, ancestorsMethod(name)],
+            ]
+          : [],
+      ),
+    ),
+};