graphile-ltree 1.1.0

package/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/plugins/folder-filter-operators.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFolderOperatorFactory = createFolderOperatorFactory;
+require("graphile-build");
+require("graphile-build-pg");
+require("graphile-connection-filter");
+const pg_sql2_1 = __importDefault(require("pg-sql2"));
+const ltree_codec_1 = require("./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 pg_sql2_1.default.fragment `ltree_helpers.to_path(${value})`;
+    }
+    return pg_sql2_1.default.fragment `replace(ltrim(${value}, '/'), '/', '.')::ltree`;
+}
+function slashGlobToLquery(value, useHelpers) {
+    if (useHelpers) {
+        return pg_sql2_1.default.fragment `ltree_helpers.to_query(${value})`;
+    }
+    return pg_sql2_1.default.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" } }) { ... }
+ * ```
+ */
+function createFolderOperatorFactory() {
+    return (build) => {
+        const ltreeInfo = build.pgLtreeExtensionInfo;
+        if (!ltreeInfo)
+            return [];
+        const useHelpers = hasLtreeHelpers(build);
+        const registrations = [];
+        registrations.push({
+            typeNames: ltree_codec_1.LTREE_SCALAR_NAME,
+            operatorName: 'within',
+            spec: {
+                description: 'Files within the specified folder (inclusive). ' +
+                    'Accepts slash-delimited paths like "/projects/alpha".',
+                resolveType: (fieldType) => fieldType,
+                resolveSqlValue: () => pg_sql2_1.default.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = pg_sql2_1.default.value(String(input));
+                    return pg_sql2_1.default.fragment `${sqlIdentifier} <@ ${slashToLtree(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: ltree_codec_1.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: () => pg_sql2_1.default.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const pathVal = pg_sql2_1.default.value(String(input));
+                    return pg_sql2_1.default.fragment `${sqlIdentifier} @> ${slashToLtree(pathVal, useHelpers)}`;
+                }
+            }
+        });
+        registrations.push({
+            typeNames: ltree_codec_1.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: () => pg_sql2_1.default.null,
+                resolve(sqlIdentifier, _sqlValue, input, _$where, _details) {
+                    const globVal = pg_sql2_1.default.value(String(input));
+                    return pg_sql2_1.default.fragment `${sqlIdentifier} ~ ${slashGlobToLquery(globVal, useHelpers)}`;
+                }
+            }
+        });
+        return registrations;
+    };
+}

package/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;

package/plugins/ltree-codec.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LtreeCodecPlugin = exports.LTREE_SCALAR_NAME = void 0;
+const graphql_1 = require("graphql");
+const pg_sql2_1 = __importDefault(require("pg-sql2"));
+exports.LTREE_SCALAR_NAME = 'LTree';
+exports.LtreeCodecPlugin = {
+    name: 'LtreeCodecPlugin',
+    version: '1.0.0',
+    description: 'Ensures ltree/lquery codecs are properly registered and enabled',
+    gather: {
+        hooks: {
+            async pgCodecs_findPgCodec(info, event) {
+                if (event.pgCodec)
+                    return;
+                const { pgType: type, serviceName } = event;
+                const isLtree = type.typname === 'ltree';
+                const isLquery = type.typname === 'lquery';
+                const isLtxtquery = type.typname === 'ltxtquery';
+                if (!isLtree && !isLquery && !isLtxtquery)
+                    return;
+                const ns = await info.helpers.pgIntrospection.getNamespace(serviceName, type.typnamespace);
+                const schemaName = ns?.nspname || 'pg_catalog';
+                event.pgCodec = {
+                    name: type.typname,
+                    sqlType: pg_sql2_1.default.identifier(schemaName, type.typname),
+                    fromPg: (value) => value,
+                    toPg: (value) => value,
+                    attributes: undefined,
+                    executor: null,
+                    extensions: {
+                        oid: type._id,
+                        pg: {
+                            serviceName,
+                            schemaName,
+                            name: type.typname
+                        }
+                    }
+                };
+            }
+        }
+    },
+    schema: {
+        hooks: {
+            init: {
+                before: ['PgCodecs', 'PgConnectionArgFilterPlugin'],
+                callback(_, build) {
+                    const { setGraphQLTypeForPgCodec, hasGraphQLTypeForPgCodec } = build;
+                    for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) {
+                        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").',
+                                    serialize(value) {
+                                        return String(value);
+                                    },
+                                    parseValue(value) {
+                                        if (typeof value === 'string')
+                                            return value;
+                                        throw new Error(`${exports.LTREE_SCALAR_NAME} must be a string`);
+                                    },
+                                    parseLiteral(lit) {
+                                        if (lit.kind === 'NullValue')
+                                            return null;
+                                        if (lit.kind !== 'StringValue') {
+                                            throw new Error(`${exports.LTREE_SCALAR_NAME} must be a string`);
+                                        }
+                                        return lit.value;
+                                    }
+                                }), `LtreeCodecPlugin registering ${exports.LTREE_SCALAR_NAME} scalar`);
+                                setGraphQLTypeForPgCodec(codec, 'input', exports.LTREE_SCALAR_NAME);
+                                setGraphQLTypeForPgCodec(codec, 'output', exports.LTREE_SCALAR_NAME);
+                            }
+                        }
+                        else if (codec.name === 'lquery' || codec.name === 'ltxtquery') {
+                            if (!hasGraphQLTypeForPgCodec(codec, 'input')) {
+                                setGraphQLTypeForPgCodec(codec, 'input', graphql_1.GraphQLString.name);
+                            }
+                            if (!hasGraphQLTypeForPgCodec(codec, 'output')) {
+                                setGraphQLTypeForPgCodec(codec, 'output', graphql_1.GraphQLString.name);
+                            }
+                        }
+                    }
+                    return _;
+                }
+            }
+        },
+        entityBehavior: {
+            pgCodecAttribute: {
+                inferred: {
+                    after: ['default'],
+                    provides: ['ltreeCodecPlugin'],
+                    callback(behavior, [codec, attributeName]) {
+                        const attr = codec.attributes?.[attributeName];
+                        const attrCodec = attr?.codec;
+                        const isLtree = attrCodec?.name === 'ltree' ||
+                            attrCodec?.extensions?.pg?.name === 'ltree';
+                        if (!isLtree)
+                            return behavior;
+                        return [
+                            behavior,
+                            'attribute:select',
+                            'attribute:base',
+                            'condition:attribute:filterBy'
+                        ];
+                    }
+                }
+            }
+        }
+    }
+};

package/preset.d.ts

@@ -0,0 +1,28 @@
+import type { GraphileConfig } from 'graphile-config';
+/**
+ * GraphileLtreePreset
+ *
+ * Base preset: ltree codec, detection, and raw ltree operators.
+ *
+ * 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)
+ *
+ * @example
+ * ```graphql
+ * allFiles(where: { path: { within: "/projects/alpha" } }) {
+ *   nodes { pathFolder filename }
+ * }
+ * ```
+ */
+export declare const GraphileFolderPreset: GraphileConfig.Preset;
+export default GraphileFolderPreset;

package/preset.js

@@ -0,0 +1,55 @@
+"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.
+ *
+ * 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)
+ *
+ * @example
+ * ```graphql
+ * allFiles(where: { path: { within: "/projects/alpha" } }) {
+ *   nodes { pathFolder filename }
+ * }
+ * ```
+ */
+exports.GraphileFolderPreset = {
+    extends: [exports.GraphileLtreePreset],
+    plugins: [
+        folder_field_1.LtreeFolderFieldPlugin
+    ],
+    schema: {
+        connectionFilterOperatorFactories: [
+            (0, folder_filter_operators_1.createFolderOperatorFactory)()
+        ]
+    }
+};
+exports.default = exports.GraphileFolderPreset;