Merge pull request #1056 from constructive-io/feat/graphile-ltree-plugin

feat: add graphile-ltree plugin — auto-detect ltree columns, folder fields, containment/glob filters

Author: pyramation

.github/workflows/run-tests.yaml

@@ -123,6 +123,8 @@ jobs:
             env: {}
           - package: graphile/graphile-bucket-provisioner-plugin
             env: {}
+          - package: graphile/graphile-ltree
+            env: {}
 
     env:
       PGHOST: localhost

graphile/graphile-ltree/README.md

@@ -0,0 +1,80 @@
+# graphile-ltree
+
+PostGraphile v5 plugin for PostgreSQL's ltree hierarchical data type.
+
+Auto-detects ltree columns, exposes slash-path folder fields, and provides containment/glob filter operators for hierarchical data.
+
+## Features
+
+- **Ltree scalar type** — ltree columns are exposed as the `Ltree` GraphQL scalar instead of `String`
+- **Folder fields** — virtual `{column}Folder` fields that convert dot-notation to slash paths (`projects.alpha.docs` -> `/projects/alpha/docs`)
+- **Connection filter operators** — `isAncestorOf`, `isDescendantOf`, `matchesGlob` for containment and pattern queries
+- **Auto-detection** — no configuration needed; the plugin scans the database for ltree columns
+- **ltree_helpers integration** — automatically uses `ltree_helpers.to_path()` / `to_query()` when available
+
+## Usage
+
+```typescript
+import { GraphileLtreePreset } from 'graphile-ltree';
+
+const preset = {
+  extends: [GraphileLtreePreset],
+};
+```
+
+Or add to the Constructive preset (already included):
+
+```typescript
+import { ConstructivePreset } from 'graphile-settings/presets';
+```
+
+## GraphQL API
+
+### Folder fields
+
+For a table with an ltree column `path`:
+
+```graphql
+{
+  allFiles {
+    nodes {
+      path          # "projects.alpha.docs" (raw ltree)
+      pathFolder    # "/projects/alpha/docs" (slash-delimited)
+    }
+  }
+}
+```
+
+### Filter operators
+
+```graphql
+# Files under /projects/alpha (containment)
+{
+  allFiles(where: { path: { isAncestorOf: "projects.alpha" } }) {
+    nodes { filename pathFolder }
+  }
+}
+
+# Ancestors of a deep path
+{
+  allFiles(where: { path: { isDescendantOf: "projects.alpha.docs.images" } }) {
+    nodes { filename pathFolder }
+  }
+}
+
+# Glob/lquery pattern matching
+{
+  allFiles(where: { path: { matchesGlob: "projects.*.docs" } }) {
+    nodes { filename pathFolder }
+  }
+}
+```
+
+## Plugins
+
+| Plugin | Purpose |
+|--------|---------|
+| `LtreeExtensionDetectionPlugin` | Scans pgRegistry for ltree/lquery codecs |
+| `LtreeCodecPlugin` | Registers `Ltree` scalar, maps ltree/lquery types |
+| `LtreeFolderFieldPlugin` | Adds virtual `{column}Folder` fields |
+| `createLtreeOperatorFactory()` | Connection filter operators for containment/glob |

graphile/graphile-ltree/jest.config.js

@@ -0,0 +1,19 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testTimeout: 60000,
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: 'tsconfig.json'
+      }
+    ]
+  },
+  transformIgnorePatterns: [`/node_modules/*`],
+  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePathIgnorePatterns: ['dist/*']
+};

graphile/graphile-ltree/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "graphile-ltree",
+  "version": "1.0.0",
+  "description": "PostGraphile v5 ltree plugin — auto-detects ltree columns, exposes slash-path folder fields, and provides containment/glob filter operators",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --forceExit",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "peerDependencies": {
+    "@dataplan/pg": "1.0.0",
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphile-connection-filter": "workspace:^",
+    "graphql": "16.13.0",
+    "pg-sql2": "5.0.0",
+    "postgraphile": "5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "graphile-connection-filter": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "graphile-test": "workspace:^",
+    "makage": "^0.3.0",
+    "pgsql-test": "workspace:^"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "graphql",
+    "ltree",
+    "hierarchy",
+    "path",
+    "folder",
+    "tree"
+  ]
+}