graphile-ltree 1.2.0 → 1.4.0

package/esm/index.d.ts

@@ -1,24 +1,19 @@
 /**
  * graphile-ltree — PostGraphile v5 ltree Plugin
  *
- * Two presets:
- *
- * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
- * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ * File-path syntax for ltree columns. The LTree scalar auto-converts between
+ * slash-delimited file paths ("/projects/alpha/docs") in the GraphQL API and
+ * dot-delimited ltree ("projects.alpha.docs") in PostgreSQL.
  *
  * @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 { ltreeToSlash, LTREE_SCALAR_NAME, LtreeCodecPlugin, slashToLtree } from './plugins/ltree-codec';
+export { createFolderOperatorFactory } from './plugins/folder-filter-operators';
 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

@@ -1,25 +1,22 @@
 /**
  * graphile-ltree — PostGraphile v5 ltree Plugin
  *
- * Two presets:
- *
- * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
- * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ * File-path syntax for ltree columns. The LTree scalar auto-converts between
+ * slash-delimited file paths ("/projects/alpha/docs") in the GraphQL API and
+ * dot-delimited ltree ("projects.alpha.docs") in PostgreSQL.
  *
  * @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';
+export { ltreeToSlash, LTREE_SCALAR_NAME, LtreeCodecPlugin, slashToLtree } from './plugins/ltree-codec';
 // Connection filter operator factories
-export { createLtreeOperatorFactory } from './plugins/connection-filter-operators';
 export { createFolderOperatorFactory } from './plugins/folder-filter-operators';
+// Deprecated — folder field plugin is no longer needed (scalar handles conversion)
+export { LtreeFolderFieldPlugin } from './plugins/folder-field';
+// Deprecated — use createFolderOperatorFactory instead (better operator names)
+export { createLtreeOperatorFactory } from './plugins/connection-filter-operators';

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

@@ -7,10 +7,33 @@
  * 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)
+ * 3. Converts between slash-delimited file paths (external API) and dot-delimited
+ *    ltree (internal storage) at the GraphQL boundary via the codec's fromPg/toPg.
+ *
+ * External API: "/projects/alpha/docs" (slash-delimited file paths)
+ * Internal DB:  "projects.alpha.docs" (ltree native format)
+ *
+ * The conversion happens at the codec level (fromPg/toPg) so it works regardless
+ * of whether PostGraphile registers its own LTree scalar or we register ours.
  *
  * 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";
+/**
+ * Convert a slash-delimited file path to ltree format.
+ * Idempotent on ltree values (no slashes → no change).
+ *
+ * "/projects/alpha/docs" → "projects.alpha.docs"
+ * "projects.alpha.docs"  → "projects.alpha.docs" (no-op)
+ */
+export declare function slashToLtree(value: string): string;
+/**
+ * Convert an ltree value to a slash-delimited file path.
+ *
+ * "projects.alpha.docs" → "/projects/alpha/docs"
+ * ""                     → "/"
+ */
+export declare function ltreeToSlash(value: string): string;
 export declare const LtreeCodecPlugin: GraphileConfig.Plugin;

package/esm/plugins/ltree-codec.js

@@ -7,6 +7,14 @@
  * 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)
+ * 3. Converts between slash-delimited file paths (external API) and dot-delimited
+ *    ltree (internal storage) at the GraphQL boundary via the codec's fromPg/toPg.
+ *
+ * External API: "/projects/alpha/docs" (slash-delimited file paths)
+ * Internal DB:  "projects.alpha.docs" (ltree native format)
+ *
+ * The conversion happens at the codec level (fromPg/toPg) so it works regardless
+ * of whether PostGraphile registers its own LTree scalar or we register ours.
  *
  * The native scalar name is "LTree" (capital T). All operators and downstream
  * plugins should reference LTREE_SCALAR_NAME for consistency.
@@ -14,10 +22,31 @@
 import { GraphQLString } from 'graphql';
 import sql from 'pg-sql2';
 export const LTREE_SCALAR_NAME = 'LTree';
+/**
+ * Convert a slash-delimited file path to ltree format.
+ * Idempotent on ltree values (no slashes → no change).
+ *
+ * "/projects/alpha/docs" → "projects.alpha.docs"
+ * "projects.alpha.docs"  → "projects.alpha.docs" (no-op)
+ */
+export function slashToLtree(value) {
+    return value.replace(/^\//, '').replace(/\//g, '.');
+}
+/**
+ * Convert an ltree value to a slash-delimited file path.
+ *
+ * "projects.alpha.docs" → "/projects/alpha/docs"
+ * ""                     → "/"
+ */
+export function ltreeToSlash(value) {
+    if (value === '')
+        return '/';
+    return '/' + value.replace(/\./g, '/');
+}
 export const LtreeCodecPlugin = {
     name: 'LtreeCodecPlugin',
-    version: '1.0.0',
-    description: 'Ensures ltree/lquery codecs are properly registered and enabled',
+    version: '2.0.0',
+    description: 'Ensures ltree/lquery codecs are registered; converts between file paths and ltree at the GraphQL boundary',
     gather: {
         hooks: {
             async pgCodecs_findPgCodec(info, event) {
@@ -52,6 +81,37 @@ export const LtreeCodecPlugin = {
     },
     schema: {
         hooks: {
+            /**
+             * Patch the ltree codec's fromPg/toPg to convert between file paths
+             * and ltree. This runs in the `build` hook (before type registration)
+             * so it works regardless of whether PostGraphile registers its own
+             * LTree scalar or we register ours.
+             *
+             * fromPg: "projects.alpha.docs" → "/projects/alpha/docs"
+             * toPg:   "/projects/alpha/docs" → "projects.alpha.docs"
+             */
+            build(build) {
+                for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                    if (codec.name === 'ltree') {
+                        const c = codec;
+                        const origFromPg = c.fromPg;
+                        c.fromPg = (value) => {
+                            const raw = origFromPg ? origFromPg(value) : value;
+                            if (raw == null)
+                                return raw;
+                            return ltreeToSlash(String(raw));
+                        };
+                        const origToPg = c.toPg;
+                        c.toPg = (value) => {
+                            if (value == null)
+                                return origToPg ? origToPg(value) : value;
+                            const converted = slashToLtree(String(value));
+                            return origToPg ? origToPg(converted) : converted;
+                        };
+                    }
+                }
+                return build;
+            },
             init: {
                 before: ['PgCodecs', 'PgConnectionArgFilterPlugin'],
                 callback(_, build) {
@@ -60,14 +120,18 @@ export const LtreeCodecPlugin = {
                         if (codec.name === 'ltree') {
                             if (!hasGraphQLTypeForPgCodec(codec, 'input')) {
                                 build.registerScalarType(LTREE_SCALAR_NAME, {}, () => ({
-                                    description: 'A PostgreSQL ltree hierarchical label path, represented as a dot-delimited string (e.g. "projects.alpha.docs").',
+                                    description: 'A hierarchical file path. Accepts slash-delimited paths (e.g. "/projects/alpha/docs"). ' +
+                                        'Stored internally as PostgreSQL ltree.',
                                     serialize(value) {
+                                        if (value == null)
+                                            return null;
                                         return String(value);
                                     },
                                     parseValue(value) {
-                                        if (typeof value === 'string')
-                                            return value;
-                                        throw new Error(`${LTREE_SCALAR_NAME} must be a string`);
+                                        if (typeof value !== 'string') {
+                                            throw new Error(`${LTREE_SCALAR_NAME} must be a string`);
+                                        }
+                                        return value;
                                     },
                                     parseLiteral(lit) {
                                         if (lit.kind === 'NullValue')

package/esm/preset.d.ts

@@ -2,27 +2,23 @@ import type { GraphileConfig } from 'graphile-config';
 /**
  * GraphileLtreePreset
  *
- * Base preset: ltree codec, detection, and raw ltree operators.
+ * Full ltree support with file-path syntax.
  *
- * Operators on LTree fields: isAncestorOf, isDescendantOf, matchesGlob
- * (accept dot-delimited or slash-delimited paths)
- */
-export declare const GraphileLtreePreset: GraphileConfig.Preset;
-/**
- * GraphileFolderPreset
- *
- * Folder-oriented layer on top of the base ltree preset.
- *
- * Adds:
- * - Virtual `{column}Folder` fields with slash-delimited paths
- * - Folder operators: within, ancestorOf, glob (always slash-delimited)
+ * - LTree scalar auto-converts between slash-delimited file paths (API) and
+ *   dot-delimited ltree (DB). External API always uses "/projects/alpha/docs".
+ * - Filter operators: within, ancestorOf, glob (all accept slash-delimited paths)
  *
  * @example
  * ```graphql
  * allFiles(where: { path: { within: "/projects/alpha" } }) {
- *   nodes { pathFolder filename }
+ *   nodes { path filename }
  * }
  * ```
  */
+export declare const GraphileLtreePreset: GraphileConfig.Preset;
+/**
+ * @deprecated Use GraphileLtreePreset instead. The folder field plugin is no
+ * longer needed — the LTree scalar now handles slash↔ltree conversion directly.
+ */
 export declare const GraphileFolderPreset: GraphileConfig.Preset;
-export default GraphileFolderPreset;
+export default GraphileLtreePreset;

package/esm/preset.js

@@ -1,47 +1,26 @@
-import { createLtreeOperatorFactory } from './plugins/connection-filter-operators';
 import { LtreeExtensionDetectionPlugin } from './plugins/detect-ltree';
-import { LtreeFolderFieldPlugin } from './plugins/folder-field';
 import { createFolderOperatorFactory } from './plugins/folder-filter-operators';
 import { LtreeCodecPlugin } from './plugins/ltree-codec';
 /**
  * GraphileLtreePreset
  *
- * Base preset: ltree codec, detection, and raw ltree operators.
+ * Full ltree support with file-path syntax.
  *
- * Operators on LTree fields: isAncestorOf, isDescendantOf, matchesGlob
- * (accept dot-delimited or slash-delimited paths)
- */
-export const GraphileLtreePreset = {
-    plugins: [
-        LtreeExtensionDetectionPlugin,
-        LtreeCodecPlugin
-    ],
-    schema: {
-        connectionFilterOperatorFactories: [
-            createLtreeOperatorFactory()
-        ]
-    }
-};
-/**
- * GraphileFolderPreset
- *
- * Folder-oriented layer on top of the base ltree preset.
- *
- * Adds:
- * - Virtual `{column}Folder` fields with slash-delimited paths
- * - Folder operators: within, ancestorOf, glob (always slash-delimited)
+ * - LTree scalar auto-converts between slash-delimited file paths (API) and
+ *   dot-delimited ltree (DB). External API always uses "/projects/alpha/docs".
+ * - Filter operators: within, ancestorOf, glob (all accept slash-delimited paths)
  *
  * @example
  * ```graphql
  * allFiles(where: { path: { within: "/projects/alpha" } }) {
- *   nodes { pathFolder filename }
+ *   nodes { path filename }
  * }
  * ```
  */
-export const GraphileFolderPreset = {
-    extends: [GraphileLtreePreset],
+export const GraphileLtreePreset = {
     plugins: [
-        LtreeFolderFieldPlugin
+        LtreeExtensionDetectionPlugin,
+        LtreeCodecPlugin
     ],
     schema: {
         connectionFilterOperatorFactories: [
@@ -49,4 +28,9 @@ export const GraphileFolderPreset = {
         ]
     }
 };
-export default GraphileFolderPreset;
+/**
+ * @deprecated Use GraphileLtreePreset instead. The folder field plugin is no
+ * longer needed — the LTree scalar now handles slash↔ltree conversion directly.
+ */
+export const GraphileFolderPreset = GraphileLtreePreset;
+export default GraphileLtreePreset;

package/index.d.ts

@@ -1,24 +1,19 @@
 /**
  * graphile-ltree — PostGraphile v5 ltree Plugin
  *
- * Two presets:
- *
- * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
- * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ * File-path syntax for ltree columns. The LTree scalar auto-converts between
+ * slash-delimited file paths ("/projects/alpha/docs") in the GraphQL API and
+ * dot-delimited ltree ("projects.alpha.docs") in PostgreSQL.
  *
  * @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 { ltreeToSlash, LTREE_SCALAR_NAME, LtreeCodecPlugin, slashToLtree } from './plugins/ltree-codec';
+export { createFolderOperatorFactory } from './plugins/folder-filter-operators';
 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/index.js

@@ -2,35 +2,34 @@
 /**
  * graphile-ltree — PostGraphile v5 ltree Plugin
  *
- * Two presets:
- *
- * - `GraphileLtreePreset` — base ltree operators (isAncestorOf, isDescendantOf, matchesGlob)
- * - `GraphileFolderPreset` — folder-oriented layer (within, ancestorOf, glob) + pathFolder fields
+ * File-path syntax for ltree columns. The LTree scalar auto-converts between
+ * slash-delimited file paths ("/projects/alpha/docs") in the GraphQL API and
+ * dot-delimited ltree ("projects.alpha.docs") in PostgreSQL.
  *
  * @example
  * ```typescript
- * // For folder-style interface (recommended):
- * import { GraphileFolderPreset } from 'graphile-ltree';
- *
- * // For raw ltree operators only:
  * import { GraphileLtreePreset } from 'graphile-ltree';
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFolderOperatorFactory = exports.createLtreeOperatorFactory = exports.LtreeCodecPlugin = exports.LTREE_SCALAR_NAME = exports.LtreeFolderFieldPlugin = exports.LtreeExtensionDetectionPlugin = exports.GraphileLtreePreset = exports.GraphileFolderPreset = void 0;
+exports.createLtreeOperatorFactory = exports.LtreeFolderFieldPlugin = exports.createFolderOperatorFactory = exports.slashToLtree = exports.LtreeCodecPlugin = exports.LTREE_SCALAR_NAME = exports.ltreeToSlash = exports.LtreeExtensionDetectionPlugin = exports.GraphileLtreePreset = exports.GraphileFolderPreset = void 0;
 // Presets
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "GraphileFolderPreset", { enumerable: true, get: function () { return preset_1.GraphileFolderPreset; } });
 Object.defineProperty(exports, "GraphileLtreePreset", { enumerable: true, get: function () { return preset_1.GraphileLtreePreset; } });
 var detect_ltree_1 = require("./plugins/detect-ltree");
 Object.defineProperty(exports, "LtreeExtensionDetectionPlugin", { enumerable: true, get: function () { return detect_ltree_1.LtreeExtensionDetectionPlugin; } });
-var folder_field_1 = require("./plugins/folder-field");
-Object.defineProperty(exports, "LtreeFolderFieldPlugin", { enumerable: true, get: function () { return folder_field_1.LtreeFolderFieldPlugin; } });
 var ltree_codec_1 = require("./plugins/ltree-codec");
+Object.defineProperty(exports, "ltreeToSlash", { enumerable: true, get: function () { return ltree_codec_1.ltreeToSlash; } });
 Object.defineProperty(exports, "LTREE_SCALAR_NAME", { enumerable: true, get: function () { return ltree_codec_1.LTREE_SCALAR_NAME; } });
 Object.defineProperty(exports, "LtreeCodecPlugin", { enumerable: true, get: function () { return ltree_codec_1.LtreeCodecPlugin; } });
+Object.defineProperty(exports, "slashToLtree", { enumerable: true, get: function () { return ltree_codec_1.slashToLtree; } });
 // Connection filter operator factories
-var connection_filter_operators_1 = require("./plugins/connection-filter-operators");
-Object.defineProperty(exports, "createLtreeOperatorFactory", { enumerable: true, get: function () { return connection_filter_operators_1.createLtreeOperatorFactory; } });
 var folder_filter_operators_1 = require("./plugins/folder-filter-operators");
 Object.defineProperty(exports, "createFolderOperatorFactory", { enumerable: true, get: function () { return folder_filter_operators_1.createFolderOperatorFactory; } });
+// Deprecated — folder field plugin is no longer needed (scalar handles conversion)
+var folder_field_1 = require("./plugins/folder-field");
+Object.defineProperty(exports, "LtreeFolderFieldPlugin", { enumerable: true, get: function () { return folder_field_1.LtreeFolderFieldPlugin; } });
+// Deprecated — use createFolderOperatorFactory instead (better operator names)
+var connection_filter_operators_1 = require("./plugins/connection-filter-operators");
+Object.defineProperty(exports, "createLtreeOperatorFactory", { enumerable: true, get: function () { return connection_filter_operators_1.createLtreeOperatorFactory; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-ltree",
-  "version": "1.2.0",
+  "version": "1.4.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",
@@ -34,7 +34,7 @@
     "graphile-build": "5.0.0",
     "graphile-build-pg": "5.0.0",
     "graphile-config": "1.0.0",
-    "graphile-connection-filter": "^1.6.0",
+    "graphile-connection-filter": "^1.7.0",
     "graphql": "16.13.0",
     "pg-sql2": "5.0.0",
     "postgraphile": "5.0.0"
@@ -46,9 +46,9 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
-    "graphile-test": "^4.10.0",
+    "graphile-test": "^4.11.0",
     "makage": "^0.3.0",
-    "pgsql-test": "^4.10.0"
+    "pgsql-test": "^4.11.0"
   },
   "keywords": [
     "postgraphile",
@@ -63,5 +63,5 @@
     "folder",
     "tree"
   ],
-  "gitHead": "fb12131bc72ca66e2eb554e15c49e35dc5b362ac"
+  "gitHead": "0ad9af424bb7760e50835edb9ee083b919a4b1f0"
 }

package/plugins/ltree-codec.d.ts

@@ -7,10 +7,33 @@
  * 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)
+ * 3. Converts between slash-delimited file paths (external API) and dot-delimited
+ *    ltree (internal storage) at the GraphQL boundary via the codec's fromPg/toPg.
+ *
+ * External API: "/projects/alpha/docs" (slash-delimited file paths)
+ * Internal DB:  "projects.alpha.docs" (ltree native format)
+ *
+ * The conversion happens at the codec level (fromPg/toPg) so it works regardless
+ * of whether PostGraphile registers its own LTree scalar or we register ours.
  *
  * 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";
+/**
+ * Convert a slash-delimited file path to ltree format.
+ * Idempotent on ltree values (no slashes → no change).
+ *
+ * "/projects/alpha/docs" → "projects.alpha.docs"
+ * "projects.alpha.docs"  → "projects.alpha.docs" (no-op)
+ */
+export declare function slashToLtree(value: string): string;
+/**
+ * Convert an ltree value to a slash-delimited file path.
+ *
+ * "projects.alpha.docs" → "/projects/alpha/docs"
+ * ""                     → "/"
+ */
+export declare function ltreeToSlash(value: string): string;
 export declare const LtreeCodecPlugin: GraphileConfig.Plugin;

package/plugins/ltree-codec.js

@@ -8,6 +8,14 @@
  * 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)
+ * 3. Converts between slash-delimited file paths (external API) and dot-delimited
+ *    ltree (internal storage) at the GraphQL boundary via the codec's fromPg/toPg.
+ *
+ * External API: "/projects/alpha/docs" (slash-delimited file paths)
+ * Internal DB:  "projects.alpha.docs" (ltree native format)
+ *
+ * The conversion happens at the codec level (fromPg/toPg) so it works regardless
+ * of whether PostGraphile registers its own LTree scalar or we register ours.
  *
  * The native scalar name is "LTree" (capital T). All operators and downstream
  * plugins should reference LTREE_SCALAR_NAME for consistency.
@@ -17,13 +25,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LtreeCodecPlugin = exports.LTREE_SCALAR_NAME = void 0;
+exports.slashToLtree = slashToLtree;
+exports.ltreeToSlash = ltreeToSlash;
 const graphql_1 = require("graphql");
 const pg_sql2_1 = __importDefault(require("pg-sql2"));
 exports.LTREE_SCALAR_NAME = 'LTree';
+/**
+ * Convert a slash-delimited file path to ltree format.
+ * Idempotent on ltree values (no slashes → no change).
+ *
+ * "/projects/alpha/docs" → "projects.alpha.docs"
+ * "projects.alpha.docs"  → "projects.alpha.docs" (no-op)
+ */
+function slashToLtree(value) {
+    return value.replace(/^\//, '').replace(/\//g, '.');
+}
+/**
+ * Convert an ltree value to a slash-delimited file path.
+ *
+ * "projects.alpha.docs" → "/projects/alpha/docs"
+ * ""                     → "/"
+ */
+function ltreeToSlash(value) {
+    if (value === '')
+        return '/';
+    return '/' + value.replace(/\./g, '/');
+}
 exports.LtreeCodecPlugin = {
     name: 'LtreeCodecPlugin',
-    version: '1.0.0',
-    description: 'Ensures ltree/lquery codecs are properly registered and enabled',
+    version: '2.0.0',
+    description: 'Ensures ltree/lquery codecs are registered; converts between file paths and ltree at the GraphQL boundary',
     gather: {
         hooks: {
             async pgCodecs_findPgCodec(info, event) {
@@ -58,6 +89,37 @@ exports.LtreeCodecPlugin = {
     },
     schema: {
         hooks: {
+            /**
+             * Patch the ltree codec's fromPg/toPg to convert between file paths
+             * and ltree. This runs in the `build` hook (before type registration)
+             * so it works regardless of whether PostGraphile registers its own
+             * LTree scalar or we register ours.
+             *
+             * fromPg: "projects.alpha.docs" → "/projects/alpha/docs"
+             * toPg:   "/projects/alpha/docs" → "projects.alpha.docs"
+             */
+            build(build) {
+                for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                    if (codec.name === 'ltree') {
+                        const c = codec;
+                        const origFromPg = c.fromPg;
+                        c.fromPg = (value) => {
+                            const raw = origFromPg ? origFromPg(value) : value;
+                            if (raw == null)
+                                return raw;
+                            return ltreeToSlash(String(raw));
+                        };
+                        const origToPg = c.toPg;
+                        c.toPg = (value) => {
+                            if (value == null)
+                                return origToPg ? origToPg(value) : value;
+                            const converted = slashToLtree(String(value));
+                            return origToPg ? origToPg(converted) : converted;
+                        };
+                    }
+                }
+                return build;
+            },
             init: {
                 before: ['PgCodecs', 'PgConnectionArgFilterPlugin'],
                 callback(_, build) {
@@ -66,14 +128,18 @@ exports.LtreeCodecPlugin = {
                         if (codec.name === 'ltree') {
                             if (!hasGraphQLTypeForPgCodec(codec, 'input')) {
                                 build.registerScalarType(exports.LTREE_SCALAR_NAME, {}, () => ({
-                                    description: 'A PostgreSQL ltree hierarchical label path, represented as a dot-delimited string (e.g. "projects.alpha.docs").',
+                                    description: 'A hierarchical file path. Accepts slash-delimited paths (e.g. "/projects/alpha/docs"). ' +
+                                        'Stored internally as PostgreSQL ltree.',
                                     serialize(value) {
+                                        if (value == null)
+                                            return null;
                                         return String(value);
                                     },
                                     parseValue(value) {
-                                        if (typeof value === 'string')
-                                            return value;
-                                        throw new Error(`${exports.LTREE_SCALAR_NAME} must be a string`);
+                                        if (typeof value !== 'string') {
+                                            throw new Error(`${exports.LTREE_SCALAR_NAME} must be a string`);
+                                        }
+                                        return value;
                                     },
                                     parseLiteral(lit) {
                                         if (lit.kind === 'NullValue')

package/preset.d.ts

@@ -2,27 +2,23 @@ import type { GraphileConfig } from 'graphile-config';
 /**
  * GraphileLtreePreset
  *
- * Base preset: ltree codec, detection, and raw ltree operators.
+ * Full ltree support with file-path syntax.
  *
- * Operators on LTree fields: isAncestorOf, isDescendantOf, matchesGlob
- * (accept dot-delimited or slash-delimited paths)
- */
-export declare const GraphileLtreePreset: GraphileConfig.Preset;
-/**
- * GraphileFolderPreset
- *
- * Folder-oriented layer on top of the base ltree preset.
- *
- * Adds:
- * - Virtual `{column}Folder` fields with slash-delimited paths
- * - Folder operators: within, ancestorOf, glob (always slash-delimited)
+ * - LTree scalar auto-converts between slash-delimited file paths (API) and
+ *   dot-delimited ltree (DB). External API always uses "/projects/alpha/docs".
+ * - Filter operators: within, ancestorOf, glob (all accept slash-delimited paths)
  *
  * @example
  * ```graphql
  * allFiles(where: { path: { within: "/projects/alpha" } }) {
- *   nodes { pathFolder filename }
+ *   nodes { path filename }
  * }
  * ```
  */
+export declare const GraphileLtreePreset: GraphileConfig.Preset;
+/**
+ * @deprecated Use GraphileLtreePreset instead. The folder field plugin is no
+ * longer needed — the LTree scalar now handles slash↔ltree conversion directly.
+ */
 export declare const GraphileFolderPreset: GraphileConfig.Preset;
-export default GraphileFolderPreset;
+export default GraphileLtreePreset;

package/preset.js

@@ -1,50 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GraphileFolderPreset = exports.GraphileLtreePreset = void 0;
-const connection_filter_operators_1 = require("./plugins/connection-filter-operators");
 const detect_ltree_1 = require("./plugins/detect-ltree");
-const folder_field_1 = require("./plugins/folder-field");
 const folder_filter_operators_1 = require("./plugins/folder-filter-operators");
 const ltree_codec_1 = require("./plugins/ltree-codec");
 /**
  * GraphileLtreePreset
  *
- * Base preset: ltree codec, detection, and raw ltree operators.
+ * Full ltree support with file-path syntax.
  *
- * Operators on LTree fields: isAncestorOf, isDescendantOf, matchesGlob
- * (accept dot-delimited or slash-delimited paths)
- */
-exports.GraphileLtreePreset = {
-    plugins: [
-        detect_ltree_1.LtreeExtensionDetectionPlugin,
-        ltree_codec_1.LtreeCodecPlugin
-    ],
-    schema: {
-        connectionFilterOperatorFactories: [
-            (0, connection_filter_operators_1.createLtreeOperatorFactory)()
-        ]
-    }
-};
-/**
- * GraphileFolderPreset
- *
- * Folder-oriented layer on top of the base ltree preset.
- *
- * Adds:
- * - Virtual `{column}Folder` fields with slash-delimited paths
- * - Folder operators: within, ancestorOf, glob (always slash-delimited)
+ * - LTree scalar auto-converts between slash-delimited file paths (API) and
+ *   dot-delimited ltree (DB). External API always uses "/projects/alpha/docs".
+ * - Filter operators: within, ancestorOf, glob (all accept slash-delimited paths)
  *
  * @example
  * ```graphql
  * allFiles(where: { path: { within: "/projects/alpha" } }) {
- *   nodes { pathFolder filename }
+ *   nodes { path filename }
  * }
  * ```
  */
-exports.GraphileFolderPreset = {
-    extends: [exports.GraphileLtreePreset],
+exports.GraphileLtreePreset = {
     plugins: [
-        folder_field_1.LtreeFolderFieldPlugin
+        detect_ltree_1.LtreeExtensionDetectionPlugin,
+        ltree_codec_1.LtreeCodecPlugin
     ],
     schema: {
         connectionFilterOperatorFactories: [
@@ -52,4 +31,9 @@ exports.GraphileFolderPreset = {
         ]
     }
 };
-exports.default = exports.GraphileFolderPreset;
+/**
+ * @deprecated Use GraphileLtreePreset instead. The folder field plugin is no
+ * longer needed — the LTree scalar now handles slash↔ltree conversion directly.
+ */
+exports.GraphileFolderPreset = exports.GraphileLtreePreset;
+exports.default = exports.GraphileLtreePreset;