graphile-function-source 0.0.0-stage → 0.2.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

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# graphile-function-source
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/graphile-function-source"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-function-source%2Fpackage.json"/></a>
+</p>
+
+Author PostgreSQL functions from `CREATE FUNCTION` source text in PostGraphile v5.
+
+Adds two mutations over the `metaschema_public.function` table:
+
+- `createFunctionFromSource(input: { databaseId, schemaId, source, apiExposed })`, when the table is insertable — the same insert as `createFunction`.
+- `updateFunctionFromSource(input: { id, source })`, when the table is updatable — the same update as `updateFunction`. It rewrites only the definition columns; `databaseId`, `schemaId` and `apiExposed` are unchanged.
+
+Both take the same text: one plain `CREATE FUNCTION` statement. `CREATE OR REPLACE` is refused by both — replacing is what `updateFunctionFromSource` means.
+
+The server parses `source` with [`plpgsql-parser`](https://www.npmjs.com/package/plpgsql-parser), maps it onto the table's columns (`name`, `kind`, `arguments`, `returns`, `volatility`, `is_strict`, `security_invoker`, and the hydrated `body_ast`), and writes the same row `createFunction` / `updateFunction` would, on the request's own client. The database decides whether a definition is allowed; the plugin only parses and writes. Deleting needs no source: use the generated `deleteFunction`.
+
+Parse failures are GraphQL errors with `extensions.code = 'FUNCTION_SOURCE_PARSE_ERROR'` and, when the parser reports one, `extensions.position` (0-based offset into `source`). Constructs the table cannot represent are refused with `FUNCTION_SOURCE_UNSUPPORTED`.
+
+## Usage
+
+```ts
+import { FunctionFromSourcePreset } from 'graphile-function-source';
+
+const preset = {
+  extends: [FunctionFromSourcePreset]
+};
+```
+
+`parseFunctionSource(source)` is exported for parsing without GraphQL.
+
+---
+
+## 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.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [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.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## 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/function-from-source.d.ts

@@ -0,0 +1,50 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+type AstNode = Record<string, any>;
+interface FieldType {
+    name: string;
+    schema?: string;
+    args?: (number | string)[];
+    array_dimensions?: number;
+}
+export interface FunctionDefinition {
+    name: string;
+    kind: 'sql' | 'plpgsql' | 'trigger';
+    arguments: {
+        name?: string;
+        type: FieldType;
+        mode?: string;
+    }[];
+    returns: {
+        type: FieldType;
+        setof?: boolean;
+    } | {
+        table: {
+            name: string;
+            type: FieldType;
+        }[];
+    };
+    volatility: 'IMMUTABLE' | 'STABLE' | 'VOLATILE';
+    is_strict: boolean;
+    security_invoker: boolean;
+    body_ast: AstNode;
+}
+export declare const FUNCTION_SOURCE_PARSE_ERROR = "FUNCTION_SOURCE_PARSE_ERROR";
+export declare const FUNCTION_SOURCE_UNSUPPORTED = "FUNCTION_SOURCE_UNSUPPORTED";
+/**
+ * Maps one `CREATE FUNCTION` statement onto the columns `metaschema_public.function`
+ * accepts. Anything those columns cannot carry is refused rather than dropped; whether
+ * the definition is *allowed* is left to the database.
+ * Create and update take the same text: replacing is chosen by the mutation, not the source.
+ */
+export declare const parseFunctionSource: (source: string) => Promise<FunctionDefinition>;
+/**
+ * `createFunctionFromSource` / `updateFunctionFromSource`: author or replace a customer
+ * function from SQL text. The server parses (the database never parses strings) and
+ * performs the same `pgInsertSingle` / `pgUpdateSingle` as `createFunction` /
+ * `updateFunction`, on the request's own client.
+ */
+export declare const FunctionFromSourcePlugin: GraphileConfig.Plugin;
+export declare const FunctionFromSourcePreset: GraphileConfig.Preset;
+export {};

package/esm/function-from-source.js

@@ -0,0 +1,289 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import { pgInsertSingle, pgUpdateSingle } from '@dataplan/pg';
+import { access, lambda, object } from 'grafast';
+import { GraphQLError } from 'graphql';
+import { loadModule, parseSql, parseSync } from 'plpgsql-parser';
+export const FUNCTION_SOURCE_PARSE_ERROR = 'FUNCTION_SOURCE_PARSE_ERROR';
+export const FUNCTION_SOURCE_UNSUPPORTED = 'FUNCTION_SOURCE_UNSUPPORTED';
+/** `position` is the parser's 0-based offset into the submitted source. */
+const sourceError = (code, message, position) => new GraphQLError(message, {
+    extensions: position === undefined ? { code } : { code, position }
+});
+const unsupported = (message, position) => sourceError(FUNCTION_SOURCE_UNSUPPORTED, message, position);
+/** Rethrows anything that is not a parser syntax error. */
+const asParseError = (err, offset) => {
+    const details = err.sqlDetails;
+    if (!details)
+        throw err;
+    return sourceError(FUNCTION_SOURCE_PARSE_ERROR, details.message, offset === undefined ? undefined : offset + details.cursorPosition);
+};
+const sval = (node) => node.String.sval;
+const MODES = {
+    FUNC_PARAM_DEFAULT: undefined,
+    FUNC_PARAM_IN: 'in',
+    FUNC_PARAM_OUT: 'out',
+    FUNC_PARAM_INOUT: 'inout',
+    FUNC_PARAM_VARIADIC: 'variadic'
+};
+const fieldType = (typeName) => {
+    if (typeName.pct_type)
+        throw unsupported('%TYPE references are not supported', typeName.location);
+    if (typeName.setof)
+        throw unsupported('SETOF is only supported as the return type', typeName.location);
+    const names = typeName.names.map(sval);
+    if (names.length > 2)
+        throw unsupported('type names take at most a schema qualifier', typeName.location);
+    const name = names[names.length - 1];
+    const type = { name };
+    if (names.length === 2 && names[0] !== 'pg_catalog')
+        type.schema = names[0];
+    if (typeName.typmods) {
+        if (name === 'interval')
+            throw unsupported('interval field qualifiers are not supported', typeName.location);
+        type.args = typeName.typmods.map((mod) => {
+            const value = mod.A_Const?.ival?.ival ?? mod.A_Const?.sval?.sval;
+            if (value === undefined)
+                throw unsupported('type modifiers must be constants', typeName.location);
+            return value;
+        });
+    }
+    if (typeName.arrayBounds)
+        type.array_dimensions = typeName.arrayBounds.length;
+    return type;
+};
+/**
+ * Maps one `CREATE FUNCTION` statement onto the columns `metaschema_public.function`
+ * accepts. Anything those columns cannot carry is refused rather than dropped; whether
+ * the definition is *allowed* is left to the database.
+ * Create and update take the same text: replacing is chosen by the mutation, not the source.
+ */
+export const parseFunctionSource = async (source) => {
+    await loadModule();
+    let parsed;
+    try {
+        parsed = parseSync(source);
+    }
+    catch (err) {
+        throw asParseError(err, 0);
+    }
+    const stmts = parsed.sql.stmts ?? [];
+    if (stmts.length !== 1 || !stmts[0].stmt.CreateFunctionStmt) {
+        throw unsupported('source must be exactly one CREATE FUNCTION statement', stmts[1]?.stmt_location);
+    }
+    const stmt = stmts[0].stmt.CreateFunctionStmt;
+    if (stmt.is_procedure)
+        throw unsupported('procedures are not supported');
+    if (stmt.replace) {
+        throw unsupported('CREATE OR REPLACE is not supported; to replace a function, send CREATE FUNCTION to updateFunctionFromSource with its id');
+    }
+    if (stmt.sql_body)
+        throw unsupported('write the body as a string literal (AS $$ ... $$)');
+    if (stmt.funcname.length !== 1) {
+        throw unsupported('the function name must be unqualified; schemaId chooses its schema');
+    }
+    let language;
+    let body;
+    let bodyLocation;
+    let volatility = 'VOLATILE';
+    let isStrict = false;
+    let securityInvoker = true;
+    for (const { DefElem: opt } of stmt.options ?? []) {
+        switch (opt.defname) {
+            case 'language':
+                language = sval(opt.arg).toLowerCase();
+                break;
+            case 'as':
+                if (opt.arg.List.items.length !== 1)
+                    throw unsupported('AS takes a single body string', opt.location);
+                body = sval(opt.arg.List.items[0]);
+                bodyLocation = opt.location;
+                break;
+            case 'volatility':
+                volatility = sval(opt.arg).toUpperCase();
+                break;
+            case 'strict':
+                isStrict = Boolean(opt.arg.Boolean.boolval);
+                break;
+            case 'security':
+                securityInvoker = !opt.arg.Boolean.boolval;
+                break;
+            default:
+                throw unsupported(`${opt.defname.toUpperCase()} is not supported`, opt.location);
+        }
+    }
+    if (body === undefined)
+        throw unsupported('the function has no body (AS $$ ... $$)');
+    const args = [];
+    const table = [];
+    for (const { FunctionParameter: param } of stmt.parameters ?? []) {
+        if (param.defexpr)
+            throw unsupported('argument defaults are not supported', param.location);
+        if (param.mode === 'FUNC_PARAM_TABLE') {
+            table.push({ name: param.name, type: fieldType(param.argType) });
+            continue;
+        }
+        if (!(param.mode in MODES))
+            throw unsupported(`argument mode ${param.mode} is not supported`, param.location);
+        const mode = MODES[param.mode];
+        args.push({
+            ...(param.name ? { name: param.name } : {}),
+            type: fieldType(param.argType),
+            ...(mode ? { mode } : {})
+        });
+    }
+    const returnType = stmt.returnType;
+    if (!returnType)
+        throw unsupported('the function must declare RETURNS');
+    const returns = table.length
+        ? { table }
+        : { type: fieldType({ ...returnType, setof: false }), ...(returnType.setof ? { setof: true } : {}) };
+    const common = {
+        name: sval(stmt.funcname[0]),
+        arguments: args,
+        returns,
+        volatility,
+        is_strict: isStrict,
+        security_invoker: securityInvoker
+    };
+    if (language === 'sql') {
+        // Body offsets map onto the source only when the body appears verbatim (dollar-quoted).
+        const bodyStart = source.indexOf(body, bodyLocation);
+        let bodyAst;
+        try {
+            bodyAst = parseSql(body);
+        }
+        catch (err) {
+            throw asParseError(err, bodyStart < 0 ? undefined : bodyStart);
+        }
+        return { ...common, kind: 'sql', body_ast: bodyAst };
+    }
+    if (language === 'plpgsql') {
+        const [bodyError] = parsed.errors;
+        if (bodyError)
+            throw sourceError(FUNCTION_SOURCE_PARSE_ERROR, bodyError.message);
+        const fn = parsed.functions[0];
+        const [hydrationError] = fn.plpgsql.errors;
+        if (hydrationError)
+            throw sourceError(FUNCTION_SOURCE_PARSE_ERROR, hydrationError.error);
+        const kind = 'type' in returns && returns.type.name === 'trigger' ? 'trigger' : 'plpgsql';
+        return { ...common, kind, body_ast: fn.plpgsql.hydrated.plpgsql_funcs[0] };
+    }
+    throw unsupported(`LANGUAGE ${language ?? '(none)'} is not supported; use plpgsql or sql`);
+};
+const isFunctionTable = (resource) => {
+    const pg = resource.codec.extensions?.pg;
+    return !resource.parameters && pg?.schemaName === 'metaschema_public' && pg?.name === 'function';
+};
+/** `updateFunctionFromSource` addresses the row the way `updateFunction` does: by `id`. */
+const isIdPrimaryKey = (unique) => Boolean(unique.isPrimary) && unique.attributes.length === 1 && unique.attributes[0] === 'id';
+const findFunctionResource = (build, behavior) => Object.values(build.pgResources).find((resource) => isFunctionTable(resource) &&
+    (behavior === 'resource:insert' || resource.uniques.some(isIdPrimaryKey)) &&
+    build.behavior.pgResourceMatches(resource, behavior) === true);
+const CREATE_INPUT = 'CreateFunctionFromSourceInput';
+const UPDATE_INPUT = 'UpdateFunctionFromSourceInput';
+/** The columns the source text decides; create and update write exactly these. */
+const definitionColumns = ($input) => {
+    const $definition = lambda(access($input, 'source'), (source) => parseFunctionSource(source));
+    return {
+        name: access($definition, 'name'),
+        kind: access($definition, 'kind'),
+        arguments: access($definition, 'arguments'),
+        returns: access($definition, 'returns'),
+        volatility: access($definition, 'volatility'),
+        is_strict: access($definition, 'is_strict'),
+        security_invoker: access($definition, 'security_invoker'),
+        body_ast: access($definition, 'body_ast')
+    };
+};
+/**
+ * `createFunctionFromSource` / `updateFunctionFromSource`: author or replace a customer
+ * function from SQL text. The server parses (the database never parses strings) and
+ * performs the same `pgInsertSingle` / `pgUpdateSingle` as `createFunction` /
+ * `updateFunction`, on the request's own client.
+ */
+export const FunctionFromSourcePlugin = {
+    name: 'FunctionFromSourcePlugin',
+    version: '1.0.0',
+    after: ['PgMutationCreatePlugin', 'PgMutationUpdateDeletePlugin', 'PgMutationPayloadEdgePlugin'],
+    schema: {
+        hooks: {
+            init(_, build) {
+                const { GraphQLBoolean, GraphQLNonNull, GraphQLString } = build.graphql;
+                const register = (name, description, fields) => build.registerInputObjectType(name, { isMutationInput: true }, () => ({
+                    description,
+                    fields: () => ({
+                        clientMutationId: {
+                            type: GraphQLString,
+                            apply(qb, val) {
+                                qb.setMeta('clientMutationId', val);
+                            }
+                        },
+                        ...fields(build.getInputTypeByName('UUID')),
+                        source: {
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'One `CREATE FUNCTION` statement (LANGUAGE plpgsql or sql).'
+                        }
+                    })
+                }), 'FunctionFromSourcePlugin input');
+                if (findFunctionResource(build, 'resource:insert')) {
+                    register(CREATE_INPUT, 'Author a function from its `CREATE FUNCTION` source text.', (uuid) => ({
+                        databaseId: { type: new GraphQLNonNull(uuid) },
+                        schemaId: { type: new GraphQLNonNull(uuid) },
+                        apiExposed: { type: GraphQLBoolean, defaultValue: false }
+                    }));
+                }
+                if (findFunctionResource(build, 'resource:update')) {
+                    register(UPDATE_INPUT, 'Replace a function\'s definition from its `CREATE FUNCTION` source text.', (uuid) => ({ id: { type: new GraphQLNonNull(uuid) } }));
+                }
+                return _;
+            },
+            GraphQLObjectType_fields(fields, build, context) {
+                if (!context.scope.isRootMutation)
+                    return fields;
+                const { GraphQLNonNull } = build.graphql;
+                const field = (fieldName, description, payloadType, inputType, plan) => context.fieldWithHooks({ fieldName }, {
+                    description,
+                    type: build.getOutputTypeByName(payloadType),
+                    args: {
+                        input: {
+                            type: new GraphQLNonNull(build.getInputTypeByName(inputType)),
+                            applyPlan(_, $mutation) {
+                                return $mutation;
+                            }
+                        }
+                    },
+                    plan(_$root, fieldArgs) {
+                        const $mutation = plan(fieldArgs);
+                        fieldArgs.apply($mutation);
+                        return object({ result: $mutation });
+                    }
+                });
+                const added = {};
+                const insertable = findFunctionResource(build, 'resource:insert');
+                if (insertable) {
+                    added.createFunctionFromSource = field('createFunctionFromSource', 'Creates a `Function` from its `CREATE FUNCTION` source text.', build.inflection.createPayloadType(insertable), CREATE_INPUT, (fieldArgs) => {
+                        const $input = fieldArgs.getRaw('input');
+                        return pgInsertSingle(insertable, {
+                            database_id: access($input, 'databaseId'),
+                            schema_id: access($input, 'schemaId'),
+                            api_exposed: access($input, 'apiExposed'),
+                            ...definitionColumns($input)
+                        });
+                    });
+                }
+                const updatable = findFunctionResource(build, 'resource:update');
+                if (updatable) {
+                    added.updateFunctionFromSource = field('updateFunctionFromSource', 'Replaces a `Function`\'s definition from its source text; its database, schema and exposure are unchanged.', build.inflection.updatePayloadType({ resource: updatable }), UPDATE_INPUT, (fieldArgs) => {
+                        const $input = fieldArgs.getRaw('input');
+                        return pgUpdateSingle(updatable, { id: access($input, 'id') }, definitionColumns($input));
+                    });
+                }
+                return build.extend(fields, added, 'Adding FunctionFromSource mutations');
+            }
+        }
+    }
+};
+export const FunctionFromSourcePreset = {
+    plugins: [FunctionFromSourcePlugin]
+};

package/esm/index.d.ts

@@ -0,0 +1,2 @@
+export type { FunctionDefinition } from './function-from-source';
+export { FUNCTION_SOURCE_PARSE_ERROR, FUNCTION_SOURCE_UNSUPPORTED, FunctionFromSourcePlugin, FunctionFromSourcePreset, parseFunctionSource } from './function-from-source';

package/esm/index.js

@@ -0,0 +1 @@
+export { FUNCTION_SOURCE_PARSE_ERROR, FUNCTION_SOURCE_UNSUPPORTED, FunctionFromSourcePlugin, FunctionFromSourcePreset, parseFunctionSource } from './function-from-source';

package/function-from-source.d.ts

@@ -0,0 +1,50 @@
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+type AstNode = Record<string, any>;
+interface FieldType {
+    name: string;
+    schema?: string;
+    args?: (number | string)[];
+    array_dimensions?: number;
+}
+export interface FunctionDefinition {
+    name: string;
+    kind: 'sql' | 'plpgsql' | 'trigger';
+    arguments: {
+        name?: string;
+        type: FieldType;
+        mode?: string;
+    }[];
+    returns: {
+        type: FieldType;
+        setof?: boolean;
+    } | {
+        table: {
+            name: string;
+            type: FieldType;
+        }[];
+    };
+    volatility: 'IMMUTABLE' | 'STABLE' | 'VOLATILE';
+    is_strict: boolean;
+    security_invoker: boolean;
+    body_ast: AstNode;
+}
+export declare const FUNCTION_SOURCE_PARSE_ERROR = "FUNCTION_SOURCE_PARSE_ERROR";
+export declare const FUNCTION_SOURCE_UNSUPPORTED = "FUNCTION_SOURCE_UNSUPPORTED";
+/**
+ * Maps one `CREATE FUNCTION` statement onto the columns `metaschema_public.function`
+ * accepts. Anything those columns cannot carry is refused rather than dropped; whether
+ * the definition is *allowed* is left to the database.
+ * Create and update take the same text: replacing is chosen by the mutation, not the source.
+ */
+export declare const parseFunctionSource: (source: string) => Promise<FunctionDefinition>;
+/**
+ * `createFunctionFromSource` / `updateFunctionFromSource`: author or replace a customer
+ * function from SQL text. The server parses (the database never parses strings) and
+ * performs the same `pgInsertSingle` / `pgUpdateSingle` as `createFunction` /
+ * `updateFunction`, on the request's own client.
+ */
+export declare const FunctionFromSourcePlugin: GraphileConfig.Plugin;
+export declare const FunctionFromSourcePreset: GraphileConfig.Preset;
+export {};

package/function-from-source.js

@@ -0,0 +1,293 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionFromSourcePreset = exports.FunctionFromSourcePlugin = exports.parseFunctionSource = exports.FUNCTION_SOURCE_UNSUPPORTED = exports.FUNCTION_SOURCE_PARSE_ERROR = void 0;
+require("graphile-build");
+require("graphile-build-pg");
+const pg_1 = require("@dataplan/pg");
+const grafast_1 = require("grafast");
+const graphql_1 = require("graphql");
+const plpgsql_parser_1 = require("plpgsql-parser");
+exports.FUNCTION_SOURCE_PARSE_ERROR = 'FUNCTION_SOURCE_PARSE_ERROR';
+exports.FUNCTION_SOURCE_UNSUPPORTED = 'FUNCTION_SOURCE_UNSUPPORTED';
+/** `position` is the parser's 0-based offset into the submitted source. */
+const sourceError = (code, message, position) => new graphql_1.GraphQLError(message, {
+    extensions: position === undefined ? { code } : { code, position }
+});
+const unsupported = (message, position) => sourceError(exports.FUNCTION_SOURCE_UNSUPPORTED, message, position);
+/** Rethrows anything that is not a parser syntax error. */
+const asParseError = (err, offset) => {
+    const details = err.sqlDetails;
+    if (!details)
+        throw err;
+    return sourceError(exports.FUNCTION_SOURCE_PARSE_ERROR, details.message, offset === undefined ? undefined : offset + details.cursorPosition);
+};
+const sval = (node) => node.String.sval;
+const MODES = {
+    FUNC_PARAM_DEFAULT: undefined,
+    FUNC_PARAM_IN: 'in',
+    FUNC_PARAM_OUT: 'out',
+    FUNC_PARAM_INOUT: 'inout',
+    FUNC_PARAM_VARIADIC: 'variadic'
+};
+const fieldType = (typeName) => {
+    if (typeName.pct_type)
+        throw unsupported('%TYPE references are not supported', typeName.location);
+    if (typeName.setof)
+        throw unsupported('SETOF is only supported as the return type', typeName.location);
+    const names = typeName.names.map(sval);
+    if (names.length > 2)
+        throw unsupported('type names take at most a schema qualifier', typeName.location);
+    const name = names[names.length - 1];
+    const type = { name };
+    if (names.length === 2 && names[0] !== 'pg_catalog')
+        type.schema = names[0];
+    if (typeName.typmods) {
+        if (name === 'interval')
+            throw unsupported('interval field qualifiers are not supported', typeName.location);
+        type.args = typeName.typmods.map((mod) => {
+            const value = mod.A_Const?.ival?.ival ?? mod.A_Const?.sval?.sval;
+            if (value === undefined)
+                throw unsupported('type modifiers must be constants', typeName.location);
+            return value;
+        });
+    }
+    if (typeName.arrayBounds)
+        type.array_dimensions = typeName.arrayBounds.length;
+    return type;
+};
+/**
+ * Maps one `CREATE FUNCTION` statement onto the columns `metaschema_public.function`
+ * accepts. Anything those columns cannot carry is refused rather than dropped; whether
+ * the definition is *allowed* is left to the database.
+ * Create and update take the same text: replacing is chosen by the mutation, not the source.
+ */
+const parseFunctionSource = async (source) => {
+    await (0, plpgsql_parser_1.loadModule)();
+    let parsed;
+    try {
+        parsed = (0, plpgsql_parser_1.parseSync)(source);
+    }
+    catch (err) {
+        throw asParseError(err, 0);
+    }
+    const stmts = parsed.sql.stmts ?? [];
+    if (stmts.length !== 1 || !stmts[0].stmt.CreateFunctionStmt) {
+        throw unsupported('source must be exactly one CREATE FUNCTION statement', stmts[1]?.stmt_location);
+    }
+    const stmt = stmts[0].stmt.CreateFunctionStmt;
+    if (stmt.is_procedure)
+        throw unsupported('procedures are not supported');
+    if (stmt.replace) {
+        throw unsupported('CREATE OR REPLACE is not supported; to replace a function, send CREATE FUNCTION to updateFunctionFromSource with its id');
+    }
+    if (stmt.sql_body)
+        throw unsupported('write the body as a string literal (AS $$ ... $$)');
+    if (stmt.funcname.length !== 1) {
+        throw unsupported('the function name must be unqualified; schemaId chooses its schema');
+    }
+    let language;
+    let body;
+    let bodyLocation;
+    let volatility = 'VOLATILE';
+    let isStrict = false;
+    let securityInvoker = true;
+    for (const { DefElem: opt } of stmt.options ?? []) {
+        switch (opt.defname) {
+            case 'language':
+                language = sval(opt.arg).toLowerCase();
+                break;
+            case 'as':
+                if (opt.arg.List.items.length !== 1)
+                    throw unsupported('AS takes a single body string', opt.location);
+                body = sval(opt.arg.List.items[0]);
+                bodyLocation = opt.location;
+                break;
+            case 'volatility':
+                volatility = sval(opt.arg).toUpperCase();
+                break;
+            case 'strict':
+                isStrict = Boolean(opt.arg.Boolean.boolval);
+                break;
+            case 'security':
+                securityInvoker = !opt.arg.Boolean.boolval;
+                break;
+            default:
+                throw unsupported(`${opt.defname.toUpperCase()} is not supported`, opt.location);
+        }
+    }
+    if (body === undefined)
+        throw unsupported('the function has no body (AS $$ ... $$)');
+    const args = [];
+    const table = [];
+    for (const { FunctionParameter: param } of stmt.parameters ?? []) {
+        if (param.defexpr)
+            throw unsupported('argument defaults are not supported', param.location);
+        if (param.mode === 'FUNC_PARAM_TABLE') {
+            table.push({ name: param.name, type: fieldType(param.argType) });
+            continue;
+        }
+        if (!(param.mode in MODES))
+            throw unsupported(`argument mode ${param.mode} is not supported`, param.location);
+        const mode = MODES[param.mode];
+        args.push({
+            ...(param.name ? { name: param.name } : {}),
+            type: fieldType(param.argType),
+            ...(mode ? { mode } : {})
+        });
+    }
+    const returnType = stmt.returnType;
+    if (!returnType)
+        throw unsupported('the function must declare RETURNS');
+    const returns = table.length
+        ? { table }
+        : { type: fieldType({ ...returnType, setof: false }), ...(returnType.setof ? { setof: true } : {}) };
+    const common = {
+        name: sval(stmt.funcname[0]),
+        arguments: args,
+        returns,
+        volatility,
+        is_strict: isStrict,
+        security_invoker: securityInvoker
+    };
+    if (language === 'sql') {
+        // Body offsets map onto the source only when the body appears verbatim (dollar-quoted).
+        const bodyStart = source.indexOf(body, bodyLocation);
+        let bodyAst;
+        try {
+            bodyAst = (0, plpgsql_parser_1.parseSql)(body);
+        }
+        catch (err) {
+            throw asParseError(err, bodyStart < 0 ? undefined : bodyStart);
+        }
+        return { ...common, kind: 'sql', body_ast: bodyAst };
+    }
+    if (language === 'plpgsql') {
+        const [bodyError] = parsed.errors;
+        if (bodyError)
+            throw sourceError(exports.FUNCTION_SOURCE_PARSE_ERROR, bodyError.message);
+        const fn = parsed.functions[0];
+        const [hydrationError] = fn.plpgsql.errors;
+        if (hydrationError)
+            throw sourceError(exports.FUNCTION_SOURCE_PARSE_ERROR, hydrationError.error);
+        const kind = 'type' in returns && returns.type.name === 'trigger' ? 'trigger' : 'plpgsql';
+        return { ...common, kind, body_ast: fn.plpgsql.hydrated.plpgsql_funcs[0] };
+    }
+    throw unsupported(`LANGUAGE ${language ?? '(none)'} is not supported; use plpgsql or sql`);
+};
+exports.parseFunctionSource = parseFunctionSource;
+const isFunctionTable = (resource) => {
+    const pg = resource.codec.extensions?.pg;
+    return !resource.parameters && pg?.schemaName === 'metaschema_public' && pg?.name === 'function';
+};
+/** `updateFunctionFromSource` addresses the row the way `updateFunction` does: by `id`. */
+const isIdPrimaryKey = (unique) => Boolean(unique.isPrimary) && unique.attributes.length === 1 && unique.attributes[0] === 'id';
+const findFunctionResource = (build, behavior) => Object.values(build.pgResources).find((resource) => isFunctionTable(resource) &&
+    (behavior === 'resource:insert' || resource.uniques.some(isIdPrimaryKey)) &&
+    build.behavior.pgResourceMatches(resource, behavior) === true);
+const CREATE_INPUT = 'CreateFunctionFromSourceInput';
+const UPDATE_INPUT = 'UpdateFunctionFromSourceInput';
+/** The columns the source text decides; create and update write exactly these. */
+const definitionColumns = ($input) => {
+    const $definition = (0, grafast_1.lambda)((0, grafast_1.access)($input, 'source'), (source) => (0, exports.parseFunctionSource)(source));
+    return {
+        name: (0, grafast_1.access)($definition, 'name'),
+        kind: (0, grafast_1.access)($definition, 'kind'),
+        arguments: (0, grafast_1.access)($definition, 'arguments'),
+        returns: (0, grafast_1.access)($definition, 'returns'),
+        volatility: (0, grafast_1.access)($definition, 'volatility'),
+        is_strict: (0, grafast_1.access)($definition, 'is_strict'),
+        security_invoker: (0, grafast_1.access)($definition, 'security_invoker'),
+        body_ast: (0, grafast_1.access)($definition, 'body_ast')
+    };
+};
+/**
+ * `createFunctionFromSource` / `updateFunctionFromSource`: author or replace a customer
+ * function from SQL text. The server parses (the database never parses strings) and
+ * performs the same `pgInsertSingle` / `pgUpdateSingle` as `createFunction` /
+ * `updateFunction`, on the request's own client.
+ */
+exports.FunctionFromSourcePlugin = {
+    name: 'FunctionFromSourcePlugin',
+    version: '1.0.0',
+    after: ['PgMutationCreatePlugin', 'PgMutationUpdateDeletePlugin', 'PgMutationPayloadEdgePlugin'],
+    schema: {
+        hooks: {
+            init(_, build) {
+                const { GraphQLBoolean, GraphQLNonNull, GraphQLString } = build.graphql;
+                const register = (name, description, fields) => build.registerInputObjectType(name, { isMutationInput: true }, () => ({
+                    description,
+                    fields: () => ({
+                        clientMutationId: {
+                            type: GraphQLString,
+                            apply(qb, val) {
+                                qb.setMeta('clientMutationId', val);
+                            }
+                        },
+                        ...fields(build.getInputTypeByName('UUID')),
+                        source: {
+                            type: new GraphQLNonNull(GraphQLString),
+                            description: 'One `CREATE FUNCTION` statement (LANGUAGE plpgsql or sql).'
+                        }
+                    })
+                }), 'FunctionFromSourcePlugin input');
+                if (findFunctionResource(build, 'resource:insert')) {
+                    register(CREATE_INPUT, 'Author a function from its `CREATE FUNCTION` source text.', (uuid) => ({
+                        databaseId: { type: new GraphQLNonNull(uuid) },
+                        schemaId: { type: new GraphQLNonNull(uuid) },
+                        apiExposed: { type: GraphQLBoolean, defaultValue: false }
+                    }));
+                }
+                if (findFunctionResource(build, 'resource:update')) {
+                    register(UPDATE_INPUT, 'Replace a function\'s definition from its `CREATE FUNCTION` source text.', (uuid) => ({ id: { type: new GraphQLNonNull(uuid) } }));
+                }
+                return _;
+            },
+            GraphQLObjectType_fields(fields, build, context) {
+                if (!context.scope.isRootMutation)
+                    return fields;
+                const { GraphQLNonNull } = build.graphql;
+                const field = (fieldName, description, payloadType, inputType, plan) => context.fieldWithHooks({ fieldName }, {
+                    description,
+                    type: build.getOutputTypeByName(payloadType),
+                    args: {
+                        input: {
+                            type: new GraphQLNonNull(build.getInputTypeByName(inputType)),
+                            applyPlan(_, $mutation) {
+                                return $mutation;
+                            }
+                        }
+                    },
+                    plan(_$root, fieldArgs) {
+                        const $mutation = plan(fieldArgs);
+                        fieldArgs.apply($mutation);
+                        return (0, grafast_1.object)({ result: $mutation });
+                    }
+                });
+                const added = {};
+                const insertable = findFunctionResource(build, 'resource:insert');
+                if (insertable) {
+                    added.createFunctionFromSource = field('createFunctionFromSource', 'Creates a `Function` from its `CREATE FUNCTION` source text.', build.inflection.createPayloadType(insertable), CREATE_INPUT, (fieldArgs) => {
+                        const $input = fieldArgs.getRaw('input');
+                        return (0, pg_1.pgInsertSingle)(insertable, {
+                            database_id: (0, grafast_1.access)($input, 'databaseId'),
+                            schema_id: (0, grafast_1.access)($input, 'schemaId'),
+                            api_exposed: (0, grafast_1.access)($input, 'apiExposed'),
+                            ...definitionColumns($input)
+                        });
+                    });
+                }
+                const updatable = findFunctionResource(build, 'resource:update');
+                if (updatable) {
+                    added.updateFunctionFromSource = field('updateFunctionFromSource', 'Replaces a `Function`\'s definition from its source text; its database, schema and exposure are unchanged.', build.inflection.updatePayloadType({ resource: updatable }), UPDATE_INPUT, (fieldArgs) => {
+                        const $input = fieldArgs.getRaw('input');
+                        return (0, pg_1.pgUpdateSingle)(updatable, { id: (0, grafast_1.access)($input, 'id') }, definitionColumns($input));
+                    });
+                }
+                return build.extend(fields, added, 'Adding FunctionFromSource mutations');
+            }
+        }
+    }
+};
+exports.FunctionFromSourcePreset = {
+    plugins: [exports.FunctionFromSourcePlugin]
+};

package/index.d.ts

@@ -0,0 +1,2 @@
+export type { FunctionDefinition } from './function-from-source';
+export { FUNCTION_SOURCE_PARSE_ERROR, FUNCTION_SOURCE_UNSUPPORTED, FunctionFromSourcePlugin, FunctionFromSourcePreset, parseFunctionSource } from './function-from-source';

package/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFunctionSource = exports.FunctionFromSourcePreset = exports.FunctionFromSourcePlugin = exports.FUNCTION_SOURCE_UNSUPPORTED = exports.FUNCTION_SOURCE_PARSE_ERROR = void 0;
+var function_from_source_1 = require("./function-from-source");
+Object.defineProperty(exports, "FUNCTION_SOURCE_PARSE_ERROR", { enumerable: true, get: function () { return function_from_source_1.FUNCTION_SOURCE_PARSE_ERROR; } });
+Object.defineProperty(exports, "FUNCTION_SOURCE_UNSUPPORTED", { enumerable: true, get: function () { return function_from_source_1.FUNCTION_SOURCE_UNSUPPORTED; } });
+Object.defineProperty(exports, "FunctionFromSourcePlugin", { enumerable: true, get: function () { return function_from_source_1.FunctionFromSourcePlugin; } });
+Object.defineProperty(exports, "FunctionFromSourcePreset", { enumerable: true, get: function () { return function_from_source_1.FunctionFromSourcePreset; } });
+Object.defineProperty(exports, "parseFunctionSource", { enumerable: true, get: function () { return function_from_source_1.parseFunctionSource; } });

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "graphile-function-source",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Author PostgreSQL functions from CREATE FUNCTION source text in PostGraphile v5",
+  "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"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "postgres",
+    "graphql",
+    "plpgsql",
+    "functions"
+  ],
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "plpgsql-parser": "^18.5.14"
+  },
+  "peerDependencies": {
+    "@dataplan/pg": "^1.1.1",
+    "grafast": "^1.1.2",
+    "graphile-build": "^5.1.1",
+    "graphile-build-pg": "^5.1.3",
+    "graphile-config": "^1.1.0",
+    "graphql": "^16.9.0",
+    "postgraphile": "^5.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "graphile-test": "^5.18.2",
+    "makage": "^0.8.0"
+  },
+  "gitHead": "772d31b8f0afd8947d4f4df8b0ffee86414ec866"
+}