prisma-ltree 0.6.0 → 0.7.0

package/dist/runtime.d.mts

@@ -1,11 +1,45 @@
+import { i as LTREE_CODEC_ID, n as Ltree } from "./codec-types-B0DtEnU6.mjs";
 import { SqlRuntimeExtensionDescriptor } from "@prisma/orm-family-sql/runtime";
 import { CodecDescriptorRegistry } from "@prisma/orm-family-sql/relational-core/query-lane-context";
+import { CollectionMethodContributionType, CollectionMethodModelType } from "@prisma/orm-family-sql/relational-core/collection-methods";
 
 //#region src/core/registry.d.ts
 declare const ltreeCodecRegistry: CodecDescriptorRegistry;
 //#endregion
+//#region src/core/hierarchy-collection-methods.d.ts
+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.
+ */
+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;
+  }
+}
+/** The run-time half of `LtreeHierarchyMethods`. */
+//#endregion
 //#region src/exports/runtime.d.ts
 declare const ltreeRuntimeDescriptor: SqlRuntimeExtensionDescriptor<"postgres">;
 //#endregion
-export { ltreeRuntimeDescriptor as default, ltreeCodecRegistry };
+export { type LtreeHierarchyMethods, ltreeRuntimeDescriptor as default, ltreeCodecRegistry };
 //# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/core/registry.ts","../src/exports/runtime.ts"],"mappings":";;;;cAIa,kBAAA,EAAoB,uBACe;;;cCD1C,sBAAA,EAAwB,6BAA6B"}
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/core/registry.ts","../src/core/hierarchy-collection-methods.ts","../src/exports/runtime.ts"],"mappings":";;;;;;cAIa,kBAAA,EAAoB,uBACe;;;KCO3C,eAAA,4BACY,MAAA,GAAS,MAAA,CAAO,IAAA;EAAA,SAAyB,IAAA;AAAA,YAEpD,MAAA,CAAO,IAAA;EAAA,SACM,IAAA;IAAA,SAAiB,OAAA,SAAgB,cAAA;EAAA;AAAA,IAE5C,IAAA,iBAEA,MAAA;AAAA,KAEH,oBAAA,eAAmC,yBAAA,wBACpB,eAAA,CAAgB,KAAA,2BAAgC,IAAA;EAAA,SACvD,UAAA,YAAsB,IAAA,EAAM,KAAA;EAAA,SAC5B,OAAA;EAAA,SACA,MAAA;AAAA,0BAGO,eAAA,CAAgB,KAAA,2BAAgC,IAAA;EAAA,SACvD,UAAA,YAAsB,IAAA,EAAM,KAAA;EAAA,SAC5B,OAAA;EAAA,SACA,MAAA;AAAA;;;;;;UASI,qBAAA,SAA8B,gCAAgC;EAAA,SACpE,OAAA,EAAS,oBAAA;AAAA;AAAA;EAAA,UAIR,wBAAA;IAAA,SACC,iBAAA,EAAmB,qBAAqB;EAAA;AAAA;;;;cC1C/C,sBAAA,EAAwB,6BAA6B"}

package/dist/runtime.mjs

@@ -1,4 +1,36 @@
-import { n as ltreeQueryOperations, r as ltreeCodecRegistry, t as ltreePackMeta } from "./descriptor-meta-Cc6tmP54.mjs";
+import "./constants-Dfknw-h5.mjs";
+import { n as ltreeQueryOperations, r as ltreeCodecRegistry, t as ltreePackMeta } from "./descriptor-meta-DwbFei9y.mjs";
+import { blindCast } from "@prisma/orm-framework/utils/casts";
+import { InternalError } from "@prisma/orm-framework/utils/internal-error";
+//#region src/core/hierarchy-collection-methods.ts
+function fieldOf(model, field) {
+	const accessor = blindCast(model)[field];
+	if (accessor === void 0) throw new InternalError(`The model accessor has no ltree field "${field}".`);
+	return accessor;
+}
+function descendantsMethod(field) {
+	return (collection, ...args) => {
+		const [root] = blindCast(args);
+		return collection.where((model) => fieldOf(model, field).isDescendantOf(root));
+	};
+}
+function ancestorsMethod(field) {
+	return (collection, ...args) => {
+		const [leaf] = blindCast(args);
+		return collection.where((model) => fieldOf(model, field).isAncestorOf(leaf));
+	};
+}
+function isScalarLtreeField(field) {
+	if (typeof field !== "object" || field === null) return false;
+	const record = field;
+	return record.many === void 0 && record.type?.kind === "scalar" && record.type.codecId === "pg/ltree@1";
+}
+/** The run-time half of `LtreeHierarchyMethods`. */
+const ltreeHierarchyMethods = {
+	id: "ltree/hierarchy",
+	methodsFor: (model) => Object.fromEntries(Object.entries(model.fields).flatMap(([name, field]) => isScalarLtreeField(field) ? [[`${name}_descendants`, descendantsMethod(name)], [`${name}_ancestors`, ancestorsMethod(name)]] : []))
+};
+//#endregion
 //#region src/exports/runtime.ts
 const ltreeRuntimeDescriptor = {
 	kind: "extension",
@@ -10,6 +42,7 @@ const ltreeRuntimeDescriptor = {
 	types: { codecTypes: { codecDescriptors: Array.from(ltreeCodecRegistry.values()) } },
 	codecs: () => Array.from(ltreeCodecRegistry.values()),
 	queryOperations: () => ltreeQueryOperations(),
+	collectionMethods: () => [ltreeHierarchyMethods],
 	create() {
 		return {
 			familyId: "sql",

package/dist/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":[],"sources":["../src/exports/runtime.ts"],"sourcesContent":["import type { SqlRuntimeExtensionDescriptor } from \"@prisma/orm-family-sql/runtime\";\nimport { ltreePackMeta, ltreeQueryOperations } from \"../core/descriptor-meta\";\nimport { ltreeCodecRegistry } from \"../core/registry\";\n\nconst ltreeRuntimeDescriptor: SqlRuntimeExtensionDescriptor<\"postgres\"> = {\n  kind: \"extension\" as const,\n  id: ltreePackMeta.id,\n  version: ltreePackMeta.version,\n  dataTypes: ltreePackMeta.dataTypes,\n  familyId: \"sql\" as const,\n  targetId: \"postgres\" as const,\n  types: {\n    codecTypes: {\n      codecDescriptors: Array.from(ltreeCodecRegistry.values()),\n    },\n  },\n  codecs: () => Array.from(ltreeCodecRegistry.values()),\n  queryOperations: () => ltreeQueryOperations(),\n  create() {\n    return {\n      familyId: \"sql\" as const,\n      targetId: \"postgres\" as const,\n    };\n  },\n};\n\nexport { ltreeCodecRegistry };\nexport default ltreeRuntimeDescriptor;\n"],"mappings":";;AAIA,MAAM,yBAAoE;CACxE,MAAM;CACN,IAAI,cAAc;CAClB,SAAS,cAAc;CACvB,WAAW,cAAc;CACzB,UAAU;CACV,UAAU;CACV,OAAO,EACL,YAAY,EACV,kBAAkB,MAAM,KAAK,mBAAmB,OAAO,CAAC,EAC1D,EACF;CACA,cAAc,MAAM,KAAK,mBAAmB,OAAO,CAAC;CACpD,uBAAuB,qBAAqB;CAC5C,SAAS;EACP,OAAO;GACL,UAAU;GACV,UAAU;EACZ;CACF;AACF"}
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../src/core/hierarchy-collection-methods.ts","../src/exports/runtime.ts"],"sourcesContent":["import type {\n  CollectionMethodBody,\n  CollectionMethodContribution,\n  CollectionMethodContributionId,\n  CollectionMethodContributionType,\n  CollectionMethodModelType,\n} from \"@prisma/orm-family-sql/relational-core/collection-methods\";\nimport { blindCast } from \"@prisma/orm-framework/utils/casts\";\nimport { InternalError } from \"@prisma/orm-framework/utils/internal-error\";\nimport type { Ltree } from \"../types/codec-types\";\nimport { LTREE_CODEC_ID } from \"./constants\";\n\ntype LtreeFieldNames<Fields> = {\n  [Name in keyof Fields]: Fields[Name] extends { readonly many: object }\n    ? never\n    : Fields[Name] extends {\n          readonly type: { readonly codecId: typeof LTREE_CODEC_ID };\n        }\n      ? Name\n      : never;\n}[keyof Fields];\n\ntype HierarchyMethodTable<Model extends CollectionMethodModelType> = {\n  readonly [Name in LtreeFieldNames<Model[\"fields\"]> & string as `${Name}_descendants`]: {\n    readonly parameters: readonly [root: Ltree];\n    readonly filters: true;\n    readonly orders: false;\n  };\n} & {\n  readonly [Name in LtreeFieldNames<Model[\"fields\"]> & string as `${Name}_ancestors`]: {\n    readonly parameters: readonly [leaf: Ltree];\n    readonly filters: true;\n    readonly orders: false;\n  };\n};\n\n/**\n * One `{field}_descendants` / `{field}_ancestors` method per scalar `ltree`\n * field. Descendants map to `isDescendantOf` (`<@`); ancestors map to\n * `isAncestorOf` (`@>`). Both are inclusive of equality, matching PostgreSQL.\n */\nexport interface LtreeHierarchyMethods extends CollectionMethodContributionType {\n  readonly methods: HierarchyMethodTable<this[\"model\"]>;\n}\n\ndeclare module \"@prisma/orm-family-sql/relational-core/collection-methods\" {\n  interface CollectionMethodRegistry {\n    readonly \"ltree/hierarchy\": LtreeHierarchyMethods;\n  }\n}\n\ninterface HierarchyField {\n  isDescendantOf(root: Ltree): unknown;\n  isAncestorOf(leaf: Ltree): unknown;\n}\n\ntype LtreeFields = Readonly<Record<string, HierarchyField>>;\n\nfunction fieldOf(model: unknown, field: string): HierarchyField {\n  const accessor = blindCast<\n    LtreeFields,\n    \"an ltree field of the ORM model accessor has hierarchy operators\"\n  >(model)[field];\n  if (accessor === undefined) {\n    throw new InternalError(`The model accessor has no ltree field \"${field}\".`);\n  }\n  return accessor;\n}\n\nfunction descendantsMethod(field: string): CollectionMethodBody {\n  return (collection, ...args) => {\n    const [root] = blindCast<readonly [Ltree], \"the type half declares a root path\">(args);\n    return collection.where((model) => fieldOf(model, field).isDescendantOf(root));\n  };\n}\n\nfunction ancestorsMethod(field: string): CollectionMethodBody {\n  return (collection, ...args) => {\n    const [leaf] = blindCast<readonly [Ltree], \"the type half declares a leaf path\">(args);\n    return collection.where((model) => fieldOf(model, field).isAncestorOf(leaf));\n  };\n}\n\nfunction isScalarLtreeField(field: unknown): boolean {\n  if (typeof field !== \"object\" || field === null) return false;\n  const record = field as {\n    readonly many?: unknown;\n    readonly type?: { readonly kind?: string; readonly codecId?: string };\n  };\n  return (\n    record.many === undefined &&\n    record.type?.kind === \"scalar\" &&\n    record.type.codecId === LTREE_CODEC_ID\n  );\n}\n\n/** The run-time half of `LtreeHierarchyMethods`. */\nexport const ltreeHierarchyMethods: CollectionMethodContribution = {\n  id: \"ltree/hierarchy\" satisfies CollectionMethodContributionId,\n  methodsFor: (model) =>\n    Object.fromEntries(\n      Object.entries(model.fields).flatMap(([name, field]) =>\n        isScalarLtreeField(field)\n          ? [\n              [`${name}_descendants`, descendantsMethod(name)],\n              [`${name}_ancestors`, ancestorsMethod(name)],\n            ]\n          : [],\n      ),\n    ),\n};\n","import type { SqlRuntimeExtensionDescriptor } from \"@prisma/orm-family-sql/runtime\";\nimport { ltreePackMeta, ltreeQueryOperations } from \"../core/descriptor-meta\";\nimport { ltreeHierarchyMethods } from \"../core/hierarchy-collection-methods\";\nimport { ltreeCodecRegistry } from \"../core/registry\";\n\nconst ltreeRuntimeDescriptor: SqlRuntimeExtensionDescriptor<\"postgres\"> = {\n  kind: \"extension\" as const,\n  id: ltreePackMeta.id,\n  version: ltreePackMeta.version,\n  dataTypes: ltreePackMeta.dataTypes,\n  familyId: \"sql\" as const,\n  targetId: \"postgres\" as const,\n  types: {\n    codecTypes: {\n      codecDescriptors: Array.from(ltreeCodecRegistry.values()),\n    },\n  },\n  codecs: () => Array.from(ltreeCodecRegistry.values()),\n  queryOperations: () => ltreeQueryOperations(),\n  collectionMethods: () => [ltreeHierarchyMethods],\n  create() {\n    return {\n      familyId: \"sql\" as const,\n      targetId: \"postgres\" as const,\n    };\n  },\n};\n\nexport type { LtreeHierarchyMethods } from \"../core/hierarchy-collection-methods\";\nexport { ltreeCodecRegistry };\nexport default ltreeRuntimeDescriptor;\n"],"mappings":";;;;;AA0DA,SAAS,QAAQ,OAAgB,OAA+B;CAC9D,MAAM,WAAW,UAGf,KAAK,EAAE;CACT,IAAI,aAAa,KAAA,GACf,MAAM,IAAI,cAAc,0CAA0C,MAAM,GAAG;CAE7E,OAAO;AACT;AAEA,SAAS,kBAAkB,OAAqC;CAC9D,QAAQ,YAAY,GAAG,SAAS;EAC9B,MAAM,CAAC,QAAQ,UAAkE,IAAI;EACrF,OAAO,WAAW,OAAO,UAAU,QAAQ,OAAO,KAAK,EAAE,eAAe,IAAI,CAAC;CAC/E;AACF;AAEA,SAAS,gBAAgB,OAAqC;CAC5D,QAAQ,YAAY,GAAG,SAAS;EAC9B,MAAM,CAAC,QAAQ,UAAkE,IAAI;EACrF,OAAO,WAAW,OAAO,UAAU,QAAQ,OAAO,KAAK,EAAE,aAAa,IAAI,CAAC;CAC7E;AACF;AAEA,SAAS,mBAAmB,OAAyB;CACnD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,SAAS;CAIf,OACE,OAAO,SAAS,KAAA,KAChB,OAAO,MAAM,SAAS,YACtB,OAAO,KAAK,YAAA;AAEhB;;AAGA,MAAa,wBAAsD;CACjE,IAAI;CACJ,aAAa,UACX,OAAO,YACL,OAAO,QAAQ,MAAM,MAAM,EAAE,SAAS,CAAC,MAAM,WAC3C,mBAAmB,KAAK,IACpB,CACE,CAAC,GAAG,KAAK,eAAe,kBAAkB,IAAI,CAAC,GAC/C,CAAC,GAAG,KAAK,aAAa,gBAAgB,IAAI,CAAC,CAC7C,IACA,CAAC,CACP,CACF;AACJ;;;ACzGA,MAAM,yBAAoE;CACxE,MAAM;CACN,IAAI,cAAc;CAClB,SAAS,cAAc;CACvB,WAAW,cAAc;CACzB,UAAU;CACV,UAAU;CACV,OAAO,EACL,YAAY,EACV,kBAAkB,MAAM,KAAK,mBAAmB,OAAO,CAAC,EAC1D,EACF;CACA,cAAc,MAAM,KAAK,mBAAmB,OAAO,CAAC;CACpD,uBAAuB,qBAAqB;CAC5C,yBAAyB,CAAC,qBAAqB;CAC/C,SAAS;EACP,OAAO;GACL,UAAU;GACV,UAAU;EACZ;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-ltree",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Prisma 8 extension pack for PostgreSQL's ltree hierarchical tree data type.",
   "homepage": "https://prisma-ltree.procka.org",
   "license": "Apache-2.0",

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)],
+            ]
+          : [],
+      ),
+    ),
+};

package/src/core/pattern-validation.ts

@@ -0,0 +1,313 @@
+/**
+ * Lightweight structural checks for PostgreSQL `lquery` / `ltxtquery` pattern
+ * arguments. These catch empty values, empty path segments, unbalanced
+ * operators/parentheses, and obviously illegal syntax before the value is cast
+ * in SQL — without inventing framework PN-* error codes.
+ *
+ * Label bodies intentionally allow Unicode letters/numbers (`\p{L}` / `\p{N}`)
+ * plus `_` / `-` so locale-dependent labels that Postgres accepts are not
+ * rejected here. Full Postgres parsing still happens at the database.
+ */
+
+/** Word body chars: locale letters/digits, underscore, hyphen. */
+const WORD_CHAR = /[\p{L}\p{N}_-]/u;
+
+function isWordChar(ch: string): boolean {
+  return WORD_CHAR.test(ch);
+}
+
+function isDigit(ch: string): boolean {
+  return ch >= "0" && ch <= "9";
+}
+
+function fail(kind: "lquery" | "ltxtquery", message: string, value: string): never {
+  throw new Error(`${kind} ${message}: "${value}"`);
+}
+
+/**
+ * Parse an optional `{n}`, `{n,}`, `{,m}`, `{n,m}`, or `{,}` quantifier starting
+ * at `i`. Returns the index after the closing `}`, or `i` when no quantifier
+ * begins here. Throws on a malformed `{...}`.
+ */
+function consumeQuantifier(
+  kind: "lquery" | "ltxtquery",
+  value: string,
+  i: number,
+  allow: boolean,
+): number {
+  if (value[i] !== "{") return i;
+  if (!allow) {
+    fail(kind, `syntax error at character ${i + 1}`, value);
+  }
+  let j = i + 1;
+  let low: number | undefined;
+  let high: number | undefined;
+  let sawComma = false;
+
+  const readNumber = (): number | undefined => {
+    if (j >= value.length || !isDigit(value[j]!)) return undefined;
+    const start = j;
+    while (j < value.length && isDigit(value[j]!)) j += 1;
+    return Number(value.slice(start, j));
+  };
+
+  low = readNumber();
+  if (j < value.length && value[j] === ",") {
+    sawComma = true;
+    j += 1;
+    high = readNumber();
+  }
+  if (j >= value.length || value[j] !== "}") {
+    fail(kind, `syntax error at character ${i + 1}`, value);
+  }
+  j += 1;
+
+  // `{}` is invalid; `{,}` (both ends open) is valid in Postgres.
+  if (low === undefined && high === undefined && !sawComma) {
+    fail(kind, `syntax error at character ${i + 1}`, value);
+  }
+  if (low !== undefined && high !== undefined && low > high) {
+    fail(kind, "syntax error (quantifier low > high)", value);
+  }
+  return j;
+}
+
+/** Consume `@` / `*` / `%` modifiers that follow a non-star word. */
+function consumeModifiers(value: string, i: number): number {
+  while (i < value.length) {
+    const ch = value[i]!;
+    if (ch === "@" || ch === "*" || ch === "%") {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+
+function consumeWord(kind: "lquery" | "ltxtquery", value: string, i: number): number {
+  if (i >= value.length || !isWordChar(value[i]!)) {
+    fail(kind, `syntax error at character ${i + 1}`, value);
+  }
+  let j = i;
+  while (j < value.length && isWordChar(value[j]!)) j += 1;
+  return j;
+}
+
+/**
+ * One lquery level: either `*` + optional quantifier, or an optional `!`
+ * followed by `word mods? (| word mods?)*` and an optional trailing quantifier.
+ */
+function consumeLqueryLevel(value: string, i: number): number {
+  if (value[i] === "*") {
+    // Star wildcards cannot take `@`/`%` modifiers; only an optional quantifier.
+    return consumeQuantifier("lquery", value, i + 1, true);
+  }
+
+  let j = i;
+  if (value[j] === "!") {
+    j += 1;
+  }
+
+  j = consumeWord("lquery", value, j);
+  j = consumeModifiers(value, j);
+
+  while (j < value.length && value[j] === "|") {
+    j += 1;
+    j = consumeWord("lquery", value, j);
+    j = consumeModifiers(value, j);
+  }
+
+  return consumeQuantifier("lquery", value, j, true);
+}
+
+export function assertValidLquery(value: unknown): asserts value is string {
+  if (typeof value !== "string") {
+    throw new Error("lquery pattern must be a string");
+  }
+  if (value.length === 0) {
+    throw new Error('lquery pattern must not be empty: ""');
+  }
+
+  let i = 0;
+  i = consumeLqueryLevel(value, i);
+  while (i < value.length) {
+    if (value[i] !== ".") {
+      fail("lquery", `syntax error at character ${i + 1}`, value);
+    }
+    i += 1;
+    if (i >= value.length) {
+      fail("lquery", "syntax error (trailing '.' / empty label)", value);
+    }
+    i = consumeLqueryLevel(value, i);
+  }
+}
+
+export function assertValidLqueryArray(value: unknown): asserts value is readonly string[] {
+  if (!Array.isArray(value)) {
+    throw new Error("lquery[] patterns must be a string array");
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const entry = value[index];
+    try {
+      assertValidLquery(entry);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`lquery[] patterns[${index}]: ${message}`);
+    }
+  }
+}
+
+type LtxtToken =
+  | { readonly kind: "word"; readonly text: string }
+  | { readonly kind: "and" }
+  | { readonly kind: "or" }
+  | { readonly kind: "not" }
+  | { readonly kind: "lparen" }
+  | { readonly kind: "rparen" };
+
+function tokenizeLtxtquery(value: string): LtxtToken[] {
+  const tokens: LtxtToken[] = [];
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i]!;
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      i += 1;
+      continue;
+    }
+    if (ch === "&") {
+      tokens.push({ kind: "and" });
+      i += 1;
+      continue;
+    }
+    if (ch === "|") {
+      tokens.push({ kind: "or" });
+      i += 1;
+      continue;
+    }
+    if (ch === "!") {
+      tokens.push({ kind: "not" });
+      i += 1;
+      continue;
+    }
+    if (ch === "(") {
+      tokens.push({ kind: "lparen" });
+      i += 1;
+      continue;
+    }
+    if (ch === ")") {
+      tokens.push({ kind: "rparen" });
+      i += 1;
+      continue;
+    }
+    if (isWordChar(ch)) {
+      const start = i;
+      i = consumeWord("ltxtquery", value, i);
+      i = consumeModifiers(value, i);
+      tokens.push({ kind: "word", text: value.slice(start, i) });
+      continue;
+    }
+    fail("ltxtquery", `syntax error at character ${i + 1}`, value);
+  }
+  return tokens;
+}
+
+/**
+ * Recursive-descent check mirroring Postgres ltxtquery operator precedence:
+ * OR < AND < NOT < primary (word / parenthesized expr).
+ */
+function parseLtxtExpr(tokens: readonly LtxtToken[], value: string): void {
+  let pos = 0;
+
+  const peek = (): LtxtToken | undefined => tokens[pos];
+  const take = (): LtxtToken => {
+    const tok = tokens[pos];
+    if (!tok) fail("ltxtquery", "syntax error (unexpected end)", value);
+    pos += 1;
+    return tok;
+  };
+
+  const parsePrimary = (): void => {
+    const tok = peek();
+    if (!tok) fail("ltxtquery", "syntax error (missing operand)", value);
+    if (tok.kind === "word") {
+      take();
+      return;
+    }
+    if (tok.kind === "lparen") {
+      take();
+      parseOr();
+      const close = take();
+      if (close.kind !== "rparen") {
+        fail("ltxtquery", "syntax error (expected ')')", value);
+      }
+      return;
+    }
+    fail("ltxtquery", "syntax error (missing operand)", value);
+  };
+
+  const parseFactor = (): void => {
+    while (peek()?.kind === "not") take();
+    parsePrimary();
+  };
+
+  const parseAnd = (): void => {
+    parseFactor();
+    while (peek()?.kind === "and") {
+      take();
+      parseFactor();
+    }
+  };
+
+  const parseOr = (): void => {
+    parseAnd();
+    while (peek()?.kind === "or") {
+      take();
+      parseAnd();
+    }
+  };
+
+  parseOr();
+  if (pos !== tokens.length) {
+    fail("ltxtquery", "syntax error (unexpected token)", value);
+  }
+}
+
+export function assertValidLtxtquery(value: unknown): asserts value is string {
+  if (typeof value !== "string") {
+    throw new Error("ltxtquery query must be a string");
+  }
+  if (value.length === 0) {
+    throw new Error('ltxtquery query must not be empty: ""');
+  }
+  const tokens = tokenizeLtxtquery(value);
+  if (tokens.length === 0) {
+    fail("ltxtquery", "syntax error (missing operand)", value);
+  }
+  parseLtxtExpr(tokens, value);
+}
+
+/**
+ * Validate a pattern argument when the caller passed a raw JS value. Expression
+ * / ParamRef objects are left alone so dynamic binds still round-trip to
+ * Postgres (which remains the authority for those).
+ */
+export function assertPatternArg(
+  castType: "lquery" | "ltxtquery" | "lquery[]",
+  arg: unknown,
+): void {
+  if (arg !== null && typeof arg === "object" && !Array.isArray(arg)) {
+    return;
+  }
+  switch (castType) {
+    case "lquery":
+      assertValidLquery(arg);
+      return;
+    case "ltxtquery":
+      assertValidLtxtquery(arg);
+      return;
+    case "lquery[]":
+      assertValidLqueryArray(arg);
+      return;
+  }
+}