prisma-ltree 0.1.0 → 0.2.0

package/README.md

@@ -8,25 +8,19 @@ them with type-safe, prisma-native operators — ancestor/descendant checks, `lq
 pattern matching, path manipulation, and lowest-common-ancestor computation — without dropping to
 raw SQL.
 
-## Overview
-
-This extension pack provides:
-
-- **`pg/ltree@1` codec** — `string ↔ string` with label-syntax + length validation (traits
-  `['equality', 'order']`).
-- **`pg/ltree-array@1` codec** — `string[] ↔ string[]` with per-element validation, for the
-  `ltree[]` first-match operators (see [ADR-003](../../docs/decisions/ADR-003-array-receiver.md)).
-- **`ltree()` / `ltreeArray()` column helpers** — non-parameterized columns with `nativeType`
-  `'ltree'` / `'ltree[]'`.
-- **Query operators** — hierarchy, pattern-match, scalar functions, concatenation, conversion, and
-  array first-match operators (full list under [Operations](#operations)).
+## Features
+
+- **`ltree` and `ltree[]` columns** — `ltree()` / `ltreeArray()` column helpers
+- **Hierarchy operators** — ancestor and descendant checks
+- **Pattern matching** — `lquery`, `lquery[]`, and `ltxtquery`
+- **Scalar functions** — depth, subpaths, label index, lowest common ancestor
+- **Concatenation & conversion** — path building and `ltree` ↔ `text` conversion
+- **Array first-match** — find the first matching path in an `ltree[]` column
 - **Baseline migration** — installs the Postgres extension via
-  `CREATE EXTENSION IF NOT EXISTS ltree` (invariantId `ltree:install-ltree-v1`).
-- **Multi-plane entrypoints** — `/control`, `/runtime`, `/column-types`, `/codec-types`,
-  `/operation-types`, `/pack`.
+  `CREATE EXTENSION IF NOT EXISTS ltree` when the pack is composed
 
-The single source of truth for what is supported, planned, or out-of-scope is
-[`docs/feature-support.md`](../../docs/feature-support.md).
+See the [feature support matrix](https://github.com/slovakian/prisma-ltree/blob/main/docs/feature-support.md)
+for what is supported, planned, or out of scope.
 
 ## Installation
 
@@ -34,9 +28,19 @@ The single source of truth for what is supported, planned, or out-of-scope is
 pnpm add prisma-ltree
 ```
 
-Requires Node `>=24` and `@prisma-next/*@0.14.0`.
+Requires Node `>=24` and `@prisma-next/*@0.14.0` (exact pin — see
+[versioning & compatibility](https://github.com/slovakian/prisma-ltree/blob/main/docs/prisma-next/versioning-and-compatibility.md)).
 
-## Database Setup
+### Agent skills (optional)
+
+Agent skills for adoption and query patterns ship in the repo under
+[`skills/`](https://github.com/slovakian/prisma-ltree/tree/main/skills):
+
+```bash
+pnpm dlx skills add slovakian/prisma-ltree --all
+```
+
+## Database setup
 
 The extension ships an on-disk baseline migration that installs `ltree` when the pack is composed
 into an application. `prisma-next db init` / `db update` apply it automatically. The equivalent
@@ -67,7 +71,35 @@ export default defineConfig({
 
 ## Usage
 
-### Contract Definition
+### Contract definition
+
+Author ltree columns in either lane — `contract.prisma` (PSL) or `contract.ts`
+(TypeScript). Both emit a byte-identical compiled contract.
+
+**PSL lane** — reference the `ltree` namespace constructors (parens required) and compose
+`ltree` into `extensions` in `prisma-next.config.ts`:
+
+```prisma
+// contract.prisma — use prisma-next
+
+types {
+  Path  = ltree.Ltree()      // → pg/ltree@1 / ltree
+  Paths = ltree.LtreeArray() // → pg/ltree-array@1 / ltree[]
+}
+
+model Page {
+  id          String @id @default(uuid())
+  path        Path
+  breadcrumbs Paths
+
+  @@map("page")
+}
+```
+
+`@db.Ltree` is not available — `@db.*` is a closed core table with no extension hook; the
+namespace constructor is the sanctioned surface (the same one pgvector and postgis use).
+
+**TypeScript lane**:
 
 ```typescript
 import { int4Column, textColumn } from "@prisma-next/adapter-postgres/column-types";
@@ -93,7 +125,7 @@ export const contract = defineContract({
 });
 ```
 
-### Runtime Setup
+### Runtime setup
 
 ```typescript
 import { instantiateExecutionStack } from "@prisma-next/framework-components/execution";
@@ -111,7 +143,7 @@ const context = createExecutionContext({ contract, stack });
 const stackInstance = instantiateExecutionStack(stack);
 ```
 
-### Query Usage
+### Query usage
 
 ```typescript
 import { sql, tables } from "../prisma/query";
@@ -130,9 +162,6 @@ const plan = sql
 
 ## Operations
 
-All boolean operators return `pg/bool@1`. See
-[`docs/feature-support.md`](../../docs/feature-support.md) for the authoritative matrix.
-
 ### Hierarchy (→ boolean)
 
 | Method                     | SQL              |
@@ -150,30 +179,28 @@ All boolean operators return `pg/bool@1`. See
 
 ### Scalar functions
 
-| Method                       | SQL                           | Returns      |
-| ---------------------------- | ----------------------------- | ------------ |
-| `path.nlevel()`              | `nlevel(ltree)`               | `pg/int4@1`  |
-| `path.subltree(start, end)`  | `subltree(ltree, start, end)` | `pg/ltree@1` |
-| `path.subpath(offset, len?)` | `subpath(ltree, offset, len)` | `pg/ltree@1` |
-| `path.indexOf(other, off?)`  | `index(ltree, ltree, off)`    | `pg/int4@1`  |
-| `path.lca(other, ...rest)`   | `lca(ltree, ltree, ...)`      | `pg/ltree@1` |
+| Method                       | SQL                           | Returns |
+| ---------------------------- | ----------------------------- | ------- |
+| `path.nlevel()`              | `nlevel(ltree)`               | `int`   |
+| `path.subltree(start, end)`  | `subltree(ltree, start, end)` | `ltree` |
+| `path.subpath(offset, len?)` | `subpath(ltree, offset, len)` | `ltree` |
+| `path.indexOf(other, off?)`  | `index(ltree, ltree, off)`    | `int`   |
+| `path.lca(other, ...rest)`   | `lca(ltree, ltree, ...)`      | `ltree` |
 
-`lca` is a variadic method requiring **≥2 paths** and returns the proper (strictly shorter) lowest
-common ancestor (see [ADR-001](../../docs/decisions/ADR-001-lca-api-shape.md)).
+`lca` requires **≥2 paths** and returns the proper (strictly shorter) lowest common ancestor.
 
 ### Concatenation (→ ltree) & conversion
 
-| Method                    | SQL                 | Returns      |
-| ------------------------- | ------------------- | ------------ |
-| `path.concat(rhs)`        | `ltree \|\| ltree`  | `pg/ltree@1` |
-| `path.concatText(label)`  | `ltree \|\| text`   | `pg/ltree@1` |
-| `path.prependText(label)` | `text \|\| ltree`   | `pg/ltree@1` |
-| `path.toText()`           | `ltree2text(ltree)` | `pg/text@1`  |
-| `text.toLtree()`          | `text2ltree(text)`  | `pg/ltree@1` |
+| Method                    | SQL                 | Returns |
+| ------------------------- | ------------------- | ------- |
+| `path.concat(rhs)`        | `ltree \|\| ltree`  | `ltree` |
+| `path.concatText(label)`  | `ltree \|\| text`   | `ltree` |
+| `path.prependText(label)` | `text \|\| ltree`   | `ltree` |
+| `path.toText()`           | `ltree2text(ltree)` | `text`  |
+| `text.toLtree()`          | `text2ltree(text)`  | `ltree` |
 
-`prependText` keeps the ltree column as the receiver even though it is the right operand, and
-`toLtree` is rooted on a text column (see
-[ADR-002](../../docs/decisions/ADR-002-free-function-lowering.md)).
+`prependText` keeps the ltree column as the receiver even though it is the right SQL operand.
+`toLtree` is called on a text column.
 
 ### Array first-match (→ ltree, receiver `ltree[]`)
 
@@ -184,6 +211,8 @@ common ancestor (see [ADR-001](../../docs/decisions/ADR-001-lca-api-shape.md)).
 | `paths.firstMatchLquery(pattern)`  | `ltree[] ?~ lquery`    |
 | `paths.firstMatchLtxtquery(query)` | `ltree[] ?@ ltxtquery` |
 
+Use `ltreeArray()` for `ltree[]` columns that expose these methods.
+
 ## Types
 
 ```typescript
@@ -194,21 +223,6 @@ import type { QueryOperationTypes } from "prisma-ltree/operation-types";
 // CodecTypes['pg/ltree-array@1']['output'] = readonly string[]
 ```
 
-## Development
-
-This package is built with [Vite+](https://viteplus.dev/):
-
-```bash
-vp install        # install dependencies
-vp check          # format, lint, typecheck
-vp test           # run unit + integration + type-level tests
-vp test --coverage # enforce the 95% coverage threshold
-vp run build      # build dist/
-```
-
-Integration tests run against [PGlite](https://pglite.dev/) with the `ltree` contrib extension —
-every operator is lowered through a composed Postgres runtime adapter and executed for real.
-
 ## License
 
 Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prisma-ltree",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Prisma Next extension pack for PostgreSQL's ltree hierarchical tree data type.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,15 +26,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "vp pack",
-    "dev": "vp pack --watch",
-    "test": "vp test",
-    "check": "vp check",
-    "build:contract-space": "prisma-next contract emit",
-    "check-pins": "prisma-next-check-pins",
-    "prepublishOnly": "vp run build"
-  },
   "dependencies": {
     "@prisma-next/contract": "0.14.0",
     "@prisma-next/contract-authoring": "0.14.0",
@@ -50,7 +41,7 @@
     "arktype": "^2.2.0"
   },
   "devDependencies": {
-    "@electric-sql/pglite": "catalog:",
+    "@electric-sql/pglite": "^0.5.3",
     "@prisma-next/adapter-postgres": "0.14.0",
     "@prisma-next/cli": "0.14.0",
     "@prisma-next/extension-author-tools": "0.14.0",
@@ -58,11 +49,11 @@
     "@prisma-next/postgres": "0.14.0",
     "@prisma-next/sql-contract-ts": "0.14.0",
     "@prisma-next/target-postgres": "0.14.0",
-    "@types/node": "catalog:",
+    "@types/node": "^24",
     "@typescript/native-preview": "7.0.0-dev.20260509.2",
     "@vitest/coverage-v8": "4.1.8",
-    "typescript": "catalog:",
-    "vite-plus": "catalog:"
+    "typescript": "^5",
+    "vite-plus": "0.1.24"
   },
   "peerDependencies": {
     "@prisma-next/adapter-postgres": "0.14.0",
@@ -85,5 +76,13 @@
       "postgres"
     ],
     "type": "extension-pack"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "build:contract-space": "prisma-next contract emit",
+    "check-pins": "prisma-next-check-pins"
   }
-}
+}