graphile-ltree 1.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# 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 |
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * graphile-ltree — PostGraphile v5 ltree Plugin
+ *
+ * Two presets:
+ *
+ * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
+ * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ *
+ * @example
+ * ```typescript
+ * // For folder-style interface (recommended):
+ * import { GraphileFolderPreset } from 'graphile-ltree';
+ *
+ * // For raw ltree operators only:
+ * import { GraphileLtreePreset } from 'graphile-ltree';
+ * ```
+ */
+export { GraphileFolderPreset, GraphileLtreePreset } from './preset';
+export type { LtreeExtensionInfo } from './plugins/detect-ltree';
+export { LtreeExtensionDetectionPlugin } from './plugins/detect-ltree';
+export { LtreeFolderFieldPlugin } from './plugins/folder-field';
+export { LTREE_SCALAR_NAME, LtreeCodecPlugin } from './plugins/ltree-codec';
+export { createLtreeOperatorFactory } from './plugins/connection-filter-operators';
+export { createFolderOperatorFactory } from './plugins/folder-filter-operators';

package/esm/index.js

@@ -0,0 +1,25 @@
+/**
+ * graphile-ltree — PostGraphile v5 ltree Plugin
+ *
+ * Two presets:
+ *
+ * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
+ * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ *
+ * @example
+ * ```typescript
+ * // For folder-style interface (recommended):
+ * import { GraphileFolderPreset } from 'graphile-ltree';
+ *
+ * // For raw ltree operators only:
+ * import { GraphileLtreePreset } from 'graphile-ltree';
+ * ```
+ */
+// Presets
+export { GraphileFolderPreset, GraphileLtreePreset } from './preset';
+export { LtreeExtensionDetectionPlugin } from './plugins/detect-ltree';
+export { LtreeFolderFieldPlugin } from './plugins/folder-field';
+export { LTREE_SCALAR_NAME, LtreeCodecPlugin } from './plugins/ltree-codec';
+// Connection filter operator factories
+export { createLtreeOperatorFactory } from './plugins/connection-filter-operators';
+export { createFolderOperatorFactory } from './plugins/folder-filter-operators';

package/esm/plugins/connection-filter-operators.d.ts

@@ -0,0 +1,18 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import type { ConnectionFilterOperatorFactory } from 'graphile-connection-filter';
+/**
+ * Creates the ltree connection filter operator factory.
+ *
+ * Registers operators on the LTree scalar type (only ltree columns):
+ *
+ * - `isAncestorOf`   -- column <@ to_path(value): finds descendants
+ * - `isDescendantOf` -- column @> to_path(value): finds ancestors
+ * - `matchesGlob`    -- column ~ to_query(value): glob/lquery pattern matching
+ *
+ * All operators accept dot-delimited paths or slash-delimited paths.
+ * When ltree_helpers is installed, conversion happens server-side via
+ * to_path() / to_query(). Otherwise, inline SQL casts are used.
+ */
+export declare function createLtreeOperatorFactory(): ConnectionFilterOperatorFactory;

package/esm/plugins/connection-filter-operators.js

@@ -0,0 +1,97 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import sql from 'pg-sql2';
+import { LTREE_SCALAR_NAME } from './ltree-codec';
+function hasLtreeHelpers(build) {
+    const pgRegistry = build.input?.pgRegistry;
+    if (!pgRegistry)
+        return false;
+    for (const resource of Object.values(pgRegistry.pgResources)) {
+        const r = resource;
+        if (r?.extensions?.pg?.schemaName === 'ltree_helpers')
+            return true;
+    }
+    return false;
+}
+function toPathExpr(value, useHelpers) {
+    if (useHelpers) {
+        return sql.fragment `ltree_helpers.to_path(${value})`;
+    }
+    return sql.fragment `replace(ltrim(${value}, '/'), '/', '.')::ltree`;
+}
+function toQueryExpr(value, useHelpers) {
+    if (useHelpers) {
+        return sql.fragment `ltree_helpers.to_query(${value})`;
+    }
+    // Glob → lquery conversion:
+    //   ** → * (0+ labels in lquery)
+    //   *  → *{1} (exactly 1 label)
+    // We use a placeholder to avoid ** being affected by the * → *{1} step.
+    return sql.fragment `replace(replace(replace(replace(ltrim(${value}, '/'), '**', '__DSTAR__'), '*', '*{1}'), '__DSTAR__', '*'), '/', '.')::lquery`;
+}
+/**
+ * Creates the ltree connection filter operator factory.
+ *
+ * Registers operators on the LTree scalar type (only ltree columns):
+ *
+ * - `isAncestorOf`   -- column <@ to_path(value): finds descendants
+ * - `isDescendantOf` -- column @> to_path(value): finds ancestors
+ * - `matchesGlob`    -- column ~ to_query(value): glob/lquery pattern matching
+ *
+ * All operators accept dot-delimited paths or slash-delimited paths.
+ * When ltree_helpers is installed, conversion happens server-side via
+ * to_path() / to_query(). Otherwise, inline SQL casts are used.
+ */
+export function createLtreeOperatorFactory() {
+    return (build) => {
+        const ltreeInfo = build.pgLtreeExtensionInfo;
+        if (!ltreeInfo)
+            return [];
+        const useHelpers = hasLtreeHelpers(build);
+        const registrations = [];
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'isAncestorOf',
+            spec: {
+                description: 'Is a descendant of (or equal to) the specified path. ' +
+                    'Returns rows whose ltree path is contained by the given path.',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} <@ ${toPathExpr(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'isDescendantOf',
+            spec: {
+                description: 'Is an ancestor of (or equal to) the specified path. ' +
+                    'Returns rows whose ltree path contains the given path.',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} @> ${toPathExpr(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'matchesGlob',
+            spec: {
+                description: 'Matches the specified glob pattern (lquery). ' +
+                    'Use * for single-level wildcard, ** for recursive descent.',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const globVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} ~ ${toQueryExpr(globVal, useHelpers)}`;
+                }
+            }
+        });
+        return registrations;
+    };
+}

package/esm/plugins/detect-ltree.d.ts

@@ -0,0 +1,18 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { PgCodec } from '@dataplan/pg';
+import type { GraphileConfig } from 'graphile-config';
+export interface LtreeExtensionInfo {
+    ltreeCodec: PgCodec;
+    lqueryCodec: PgCodec | null;
+}
+/**
+ * LtreeExtensionDetectionPlugin
+ *
+ * Detects ltree presence in the database by searching for ltree/lquery
+ * codecs in the pgRegistry. Stores detected info on the build object
+ * for downstream plugins.
+ *
+ * Gracefully degrades if ltree is not installed.
+ */
+export declare const LtreeExtensionDetectionPlugin: GraphileConfig.Plugin;

package/esm/plugins/detect-ltree.js

@@ -0,0 +1,52 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+function isLtreeCodec(codec) {
+    return (codec?.name === 'ltree' ||
+        codec?.extensions?.pg?.name === 'ltree');
+}
+function isLqueryCodec(codec) {
+    return (codec?.name === 'lquery' ||
+        codec?.extensions?.pg?.name === 'lquery');
+}
+/**
+ * LtreeExtensionDetectionPlugin
+ *
+ * Detects ltree presence in the database by searching for ltree/lquery
+ * codecs in the pgRegistry. Stores detected info on the build object
+ * for downstream plugins.
+ *
+ * Gracefully degrades if ltree is not installed.
+ */
+export const LtreeExtensionDetectionPlugin = {
+    name: 'LtreeExtensionDetectionPlugin',
+    version: '1.0.0',
+    description: 'Detects ltree extension in the database',
+    schema: {
+        hooks: {
+            build(build) {
+                const pgRegistry = build.input?.pgRegistry;
+                if (!pgRegistry) {
+                    return build;
+                }
+                let ltreeCodec = null;
+                let lqueryCodec = null;
+                for (const codec of Object.values(pgRegistry.pgCodecs)) {
+                    if (isLtreeCodec(codec)) {
+                        ltreeCodec = codec;
+                    }
+                    else if (isLqueryCodec(codec)) {
+                        lqueryCodec = codec;
+                    }
+                }
+                if (!ltreeCodec) {
+                    return build;
+                }
+                const ltreeInfo = {
+                    ltreeCodec,
+                    lqueryCodec
+                };
+                return build.extend(build, { pgLtreeExtensionInfo: ltreeInfo }, 'LtreeExtensionDetectionPlugin adding ltree build state');
+            }
+        }
+    }
+};

package/esm/plugins/folder-field.d.ts

@@ -0,0 +1,19 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * LtreeFolderFieldPlugin
+ *
+ * For every ltree column on every table:
+ *
+ * 1. Renames the raw ltree field from `{column}` to `{column}Tree`
+ *    via the `@name` smart tag (e.g. `path` -> `pathTree`)
+ *
+ * 2. Adds a virtual field with the original name (`path`) that returns
+ *    the slash-delimited folder path.
+ *    (e.g. 'projects.alpha.docs' -> '/projects/alpha/docs')
+ *
+ * This gives users the clean field name for display while preserving
+ * the raw ltree field (with all filter operators) under `{column}Tree`.
+ */
+export declare const LtreeFolderFieldPlugin: GraphileConfig.Plugin;

package/esm/plugins/folder-field.js

@@ -0,0 +1,102 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import { GraphQLString } from 'graphql';
+/**
+ * LtreeFolderFieldPlugin
+ *
+ * For every ltree column on every table:
+ *
+ * 1. Renames the raw ltree field from `{column}` to `{column}Tree`
+ *    via the `@name` smart tag (e.g. `path` -> `pathTree`)
+ *
+ * 2. Adds a virtual field with the original name (`path`) that returns
+ *    the slash-delimited folder path.
+ *    (e.g. 'projects.alpha.docs' -> '/projects/alpha/docs')
+ *
+ * This gives users the clean field name for display while preserving
+ * the raw ltree field (with all filter operators) under `{column}Tree`.
+ */
+export const LtreeFolderFieldPlugin = {
+    name: 'LtreeFolderFieldPlugin',
+    version: '1.0.0',
+    description: 'Renames ltree columns to {col}Tree and adds virtual {col} folder fields',
+    after: ['LtreeExtensionDetectionPlugin', 'LtreeCodecPlugin', 'PgAttributesPlugin'],
+    schema: {
+        hooks: {
+            /**
+             * Before fields are built, rename ltree attributes via the @name tag.
+             * This ensures PostGraphile's plan system correctly maps the renamed
+             * field to the underlying database column.
+             */
+            init(_, build) {
+                const ltreeInfo = build.pgLtreeExtensionInfo;
+                if (!ltreeInfo)
+                    return _;
+                const pgRegistry = build.input?.pgRegistry;
+                if (!pgRegistry)
+                    return _;
+                for (const resource of Object.values(pgRegistry.pgResources)) {
+                    const r = resource;
+                    const codec = r?.codec;
+                    if (!codec?.attributes)
+                        continue;
+                    for (const [attrName, attr] of Object.entries(codec.attributes)) {
+                        const attrCodec = attr?.codec;
+                        if (!attrCodec)
+                            continue;
+                        const isLtree = attrCodec.name === 'ltree' ||
+                            attrCodec.extensions?.pg?.name === 'ltree';
+                        if (!isLtree)
+                            continue;
+                        // Set @name tag to rename: path → path_tree
+                        // PostGraphile's _attributeName inflector reads this tag
+                        attr.extensions = attr.extensions || {};
+                        attr.extensions.tags = attr.extensions.tags || {};
+                        attr.extensions.tags.name = `${attrName}_tree`;
+                    }
+                }
+                return _;
+            },
+            GraphQLObjectType_fields(fields, build, context) {
+                const ltreeInfo = build.pgLtreeExtensionInfo;
+                if (!ltreeInfo)
+                    return fields;
+                const { scope: { isPgClassType, pgCodec: rawPgCodec }, fieldWithHooks } = context;
+                if (!isPgClassType || !rawPgCodec?.attributes)
+                    return fields;
+                const codec = rawPgCodec;
+                const { lambda } = build.grafast;
+                let newFields = fields;
+                for (const [attrName, attr] of Object.entries(codec.attributes)) {
+                    const attrCodec = attr?.codec;
+                    if (!attrCodec)
+                        continue;
+                    const isLtree = attrCodec.name === 'ltree' ||
+                        attrCodec.extensions?.pg?.name === 'ltree';
+                    if (!isLtree)
+                        continue;
+                    // The original column name becomes the folder field name
+                    const folderFieldName = build.inflection.camelCase(attrName);
+                    newFields = build.extend(newFields, {
+                        [folderFieldName]: fieldWithHooks({ fieldName: folderFieldName }, () => ({
+                            description: `Slash-delimited path derived from the \`${attrName}\` ltree column. Example: \`/projects/alpha/docs\``,
+                            type: GraphQLString,
+                            plan($row) {
+                                const $ltreeVal = $row.get(attrName);
+                                return lambda($ltreeVal, (val) => {
+                                    if (val == null)
+                                        return null;
+                                    const str = String(val);
+                                    if (str === '')
+                                        return '/';
+                                    return '/' + str.replace(/\./g, '/');
+                                });
+                            }
+                        }))
+                    }, `LtreeFolderFieldPlugin adding folder field '${folderFieldName}' for '${attrName}' on '${codec.name}'`);
+                }
+                return newFields;
+            }
+        }
+    }
+};

package/esm/plugins/folder-filter-operators.d.ts

@@ -0,0 +1,23 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import type { ConnectionFilterOperatorFactory } from 'graphile-connection-filter';
+/**
+ * Creates folder-oriented connection filter operators for the LTree scalar.
+ *
+ * These are user-friendly aliases for the raw ltree operators, designed for
+ * slash-delimited file/folder paths:
+ *
+ * - `within`     — files within a folder: path <@ to_path('/projects/alpha')
+ * - `ancestorOf` — ancestor folders: path @> to_path('/projects/alpha/docs')
+ * - `glob`       — glob pattern: path ~ to_query('/projects/* /docs')
+ *
+ * All inputs use slash-delimited paths. Conversion to ltree happens server-side.
+ *
+ * @example
+ * ```graphql
+ * allFiles(where: { path: { within: "/projects/alpha" } }) { ... }
+ * allFiles(where: { path: { glob: "/projects/* /docs" } }) { ... }
+ * ```
+ */
+export declare function createFolderOperatorFactory(): ConnectionFilterOperatorFactory;

package/esm/plugins/folder-filter-operators.js

@@ -0,0 +1,99 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import 'graphile-connection-filter';
+import sql from 'pg-sql2';
+import { LTREE_SCALAR_NAME } from './ltree-codec';
+function hasLtreeHelpers(build) {
+    const pgRegistry = build.input?.pgRegistry;
+    if (!pgRegistry)
+        return false;
+    for (const resource of Object.values(pgRegistry.pgResources)) {
+        const r = resource;
+        if (r?.extensions?.pg?.schemaName === 'ltree_helpers')
+            return true;
+    }
+    return false;
+}
+function slashToLtree(value, useHelpers) {
+    if (useHelpers) {
+        return sql.fragment `ltree_helpers.to_path(${value})`;
+    }
+    return sql.fragment `replace(ltrim(${value}, '/'), '/', '.')::ltree`;
+}
+function slashGlobToLquery(value, useHelpers) {
+    if (useHelpers) {
+        return sql.fragment `ltree_helpers.to_query(${value})`;
+    }
+    return sql.fragment `replace(replace(replace(replace(ltrim(${value}, '/'), '**', '__DSTAR__'), '*', '*{1}'), '__DSTAR__', '*'), '/', '.')::lquery`;
+}
+/**
+ * Creates folder-oriented connection filter operators for the LTree scalar.
+ *
+ * These are user-friendly aliases for the raw ltree operators, designed for
+ * slash-delimited file/folder paths:
+ *
+ * - `within`     — files within a folder: path <@ to_path('/projects/alpha')
+ * - `ancestorOf` — ancestor folders: path @> to_path('/projects/alpha/docs')
+ * - `glob`       — glob pattern: path ~ to_query('/projects/* /docs')
+ *
+ * All inputs use slash-delimited paths. Conversion to ltree happens server-side.
+ *
+ * @example
+ * ```graphql
+ * allFiles(where: { path: { within: "/projects/alpha" } }) { ... }
+ * allFiles(where: { path: { glob: "/projects/* /docs" } }) { ... }
+ * ```
+ */
+export function createFolderOperatorFactory() {
+    return (build) => {
+        const ltreeInfo = build.pgLtreeExtensionInfo;
+        if (!ltreeInfo)
+            return [];
+        const useHelpers = hasLtreeHelpers(build);
+        const registrations = [];
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'within',
+            spec: {
+                description: 'Files within the specified folder (inclusive). ' +
+                    'Accepts slash-delimited paths like "/projects/alpha".',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} <@ ${slashToLtree(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'ancestorOf',
+            spec: {
+                description: 'Ancestor folders of the specified path. ' +
+                    'Accepts slash-delimited paths like "/projects/alpha/docs".',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} @> ${slashToLtree(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: LTREE_SCALAR_NAME,
+            operatorName: 'glob',
+            spec: {
+                description: 'Matches a slash-delimited glob pattern. ' +
+                    'Use * for single-level wildcard, ** for recursive descent. ' +
+                    'Example: "/projects/*/docs".',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => sql.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const globVal = sql.value(String(input));
+                    return sql.fragment `${sqlIdentifier} ~ ${slashGlobToLquery(globVal, useHelpers)}`;
+                }
+            }
+        });
+        return registrations;
+    };
+}

package/esm/plugins/ltree-codec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LtreeCodecPlugin
+ *
+ * Ensures PostGraphile v5 properly handles ltree, lquery, and ltxtquery types.
+ *
+ * PostGraphile v5 (rc.8+) natively maps ltree to a GraphQL scalar named "LTree".
+ * This plugin:
+ * 1. Falls back to registering codecs if PostGraphile's native handling misses them
+ * 2. Re-enables ltree columns for select/filterBy (overrides rc.8 HIDE_BY_DEFAULT)
+ *
+ * The native scalar name is "LTree" (capital T). All operators and downstream
+ * plugins should reference LTREE_SCALAR_NAME for consistency.
+ */
+import type { GraphileConfig } from 'graphile-config';
+export declare const LTREE_SCALAR_NAME = "LTree";
+export declare const LtreeCodecPlugin: GraphileConfig.Plugin;