graphile-i18n 1.1.1 → 1.2.1

package/README.md

@@ -8,90 +8,170 @@
   <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-i18n">
-    <img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-i18n%2Fpackage.json"/>
-  </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-i18n"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-i18n%2Fpackage.json"/></a>
 </p>
 
-**`graphile-i18n`** is a TypeScript rewrite of the Graphile/PostGraphile i18n plugin. It adds language-aware fields sourced from translation tables declared via smart comments and respects `Accept-Language` with sensible fallbacks.
+PostGraphile v5 i18n plugin — language-aware fields sourced from `@i18n` translation tables with Accept-Language negotiation and configurable fallback chains.
+
+## Overview
+
+`graphile-i18n` auto-discovers tables tagged with the `@i18n` smart comment, finds the companion translation table, and injects a `localeStrings` field on the base type. The field resolves the best-matching translation row based on the GraphQL context's language codes, falling back to the base table's own values when no translation exists.
+
+## Usage
+
+```typescript
+import { I18nPreset } from 'graphile-i18n';
 
-## 🚀 Installation
+const preset = {
+  extends: [
+    I18nPreset(),
+  ],
+};
+```
+
+### Custom configuration
+
+```typescript
+import { I18nPreset } from 'graphile-i18n';
 
-```bash
-pnpm add graphile-i18n
+const preset = {
+  extends: [
+    I18nPreset({
+      defaultLanguages: ['en', 'es'],
+      langCodeColumn: 'lang_code',
+      allowedTypes: ['text', 'citext'],
+    }),
+  ],
+};
 ```
 
-## ✨ Features
+### Accept-Language middleware
 
-- Smart comments (`@i18n`) to wire translation tables
-- `Accept-Language` detection with graceful fallback to base values
-- Works with PostGraphile context via `additionalGraphQLContextFromRequest`
-- TypeScript-first implementation
+For production use with Express/PostGraphile, add the Accept-Language context builder:
+
+```typescript
+import { I18nPreset, makeI18nContext } from 'graphile-i18n';
+
+const preset = {
+  extends: [I18nPreset()],
+  grafast: {
+    context: makeI18nContext({
+      supportedLanguages: ['en', 'es', 'fr'],
+    }),
+  },
+};
+```
 
-## 📦 Usage
+## Database Setup
 
-1. Add a translation table and tag the base table with `@i18n`:
+Tag the base table with a `@i18n` smart comment pointing to its translation table:
 
 ```sql
-CREATE TABLE app_public.projects (
-  id serial PRIMARY KEY,
-  name citext,
-  description citext
-);
-COMMENT ON TABLE app_public.projects IS E'@i18n project_language_variations';
+COMMENT ON TABLE app_public.posts IS E'@i18n posts_translations';
+```
 
-CREATE TABLE app_public.project_language_variations (
+The translation table must have:
+- A FK column referencing the base table's PK (convention: `{table}_id`)
+- A `lang_code` text column (configurable)
+- A `UNIQUE(fk_column, lang_code)` constraint
+- One or more `text`/`citext` columns matching translatable base columns
+
+```sql
+CREATE TABLE app_public.posts_translations (
   id serial PRIMARY KEY,
-  project_id int NOT NULL REFERENCES app_public.projects(id),
-  lang_code citext,
-  name citext,
-  description citext,
-  UNIQUE (project_id, lang_code)
+  post_id int NOT NULL REFERENCES app_public.posts(id) ON DELETE CASCADE,
+  lang_code text NOT NULL,
+  title text NOT NULL,
+  body text,
+  UNIQUE (post_id, lang_code)
 );
 ```
 
-2. Register the plugin:
-
-```ts
-import express from 'express';
-import { postgraphile } from 'postgraphile';
-import {
-  LangPlugin,
-  additionalGraphQLContextFromRequest,
-} from 'graphile-i18n';
-
-const app = express();
-app.use(
-  postgraphile(process.env.DATABASE_URL, ['app_public'], {
-    appendPlugins: [LangPlugin],
-    graphileBuildOptions: {
-      langPluginDefaultLanguages: ['en'],
-    },
-    additionalGraphQLContextFromRequest,
-  })
-);
+## GraphQL API
+
+Once configured, every tagged table gets a `localeStrings` field:
+
+```graphql
+query {
+  allPosts {
+    nodes {
+      title          # original base value
+      localeStrings {
+        langCode     # matched language code (null if no translation)
+        title        # translated or base fallback
+        body         # translated or base fallback
+      }
+    }
+  }
+}
 ```
 
-Requests with `Accept-Language` headers receive the closest translation; fields fall back to the base table values when a translation is missing.
+### Language selection
 
-## 🧰 Configuration Options
+Pass `langCodes` in the GraphQL context (automatically handled by `makeI18nContext` or set manually in tests):
 
-All options are provided through `graphileBuildOptions`:
+```graphql
+# With context: { langCodes: ['es'] }
+query {
+  postByRowId(rowId: 1) {
+    localeStrings {
+      langCode  # "es"
+      title     # "Hola Mundo"
+    }
+  }
+}
+```
 
-- `langPluginLanguageCodeColumn` — translation table column name, default `lang_code`
-- `langPluginLanguageCodeGqlField` — exposed GraphQL field name, default `langCode`
-- `langPluginAllowedTypes` — allowed base column types for translation, default `['citext', 'text']`
-- `langPluginDefaultLanguages` — fallback language order, default `['en']`
+When the requested language has no translation, the plugin falls back through the `langCodes` array. If no match is found, base table values are returned with `langCode: null`.
+
+## Features
+
+- **Smart tag discovery**: Auto-detects `@i18n` tagged tables and their translation companions
+- **Grafast-native resolution**: Uses `lambda` + `object` steps for proper v5 execution
+- **Accept-Language negotiation**: Built-in middleware parses headers and injects context
+- **Fallback chain**: Tries each language in order, falls back to base table values
+- **Convention-based FK**: Discovers FK by `{table}_id` convention or type matching
+- **Type-safe**: Full TypeScript types for options, registry, and field mappings
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `langCodeColumn` | `'lang_code'` | Column name on translation table storing the language code |
+| `langCodeGqlField` | `'langCode'` | GraphQL field name for the language code in the locale object |
+| `allowedTypes` | `['text', 'citext']` | PostgreSQL column types eligible for translation |
+| `defaultLanguages` | `['en']` | Fallback languages when no context is provided |
+
+## Constructive Integration
+
+When used with the Constructive framework, the `DataI18n` node type automates translation table creation and optionally composes with `SearchFullText` for multilingual full-text search:
+
+```json
+{
+  "nodes": [
+    {
+      "$type": "DataI18n",
+      "data": {
+        "fields": ["name", "description"],
+        "search": {
+          "field_name": "search",
+          "source_fields": [
+            { "field": "name", "weight": "A" },
+            { "field": "description", "weight": "B" }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
 
-## 🧪 Testing
+When `search` is provided, the tsvector is created on the **translations table** with dynamic per-row language stemming — each row is stemmed using its own `lang_code` value (e.g., `'spanish'` → Spanish stemmer, `'french'` → French stemmer). PostgreSQL ships with 30+ built-in text search configurations, so multilingual search works out of the box with no per-language configuration.
 
-```sh
-# requires a local Postgres available (defaults to postgres/password@localhost:5432)
-pnpm --filter graphile-i18n test
-```
+The `i18n_module` provides app-level configuration via `app_settings_i18n` with supported languages, default language, and fallback chain — all manageable via GraphQL mutations.
+
+For the full i18n guide (blueprint patterns, ORM queries, SQL search examples), see the [constructive-sdk-i18n skill](https://github.com/constructive-io/constructive-skills/tree/main/.agents/skills/constructive-sdk-i18n).
 
 ---
 
@@ -141,6 +221,10 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 * [@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.
+
 ## 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).**

package/esm/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * graphile-i18n — PostGraphile v5 i18n Plugin
+ *
+ * Language-aware fields sourced from @i18n translation tables
+ * with Accept-Language negotiation and configurable fallback chains.
+ *
+ * @example
+ * ```typescript
+ * import { I18nPreset } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   extends: [
+ *     I18nPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { I18nPreset } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   extends: [
+ *     I18nPreset({
+ *       defaultLanguages: ['en', 'es'],
+ *       langCodeColumn: 'lang_code',
+ *       allowedTypes: ['text', 'citext'],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+export { createI18nPlugin, I18nPlugin } from './plugin';
+export { I18nPreset } from './preset';
+export { makeI18nContext, additionalGraphQLContextFromRequest } from './middleware';
+export type { I18nPluginOptions, I18nTableInfo, TranslatableField } from './types';
+export type { I18nMiddlewareOptions } from './middleware';

package/esm/index.js

@@ -1,5 +1,38 @@
-import LangPlugin from './plugin';
-export { LangPlugin } from './plugin';
-export { additionalGraphQLContextFromRequest, makeLanguageDataLoaderForTable } from './middleware';
-export { env } from './env';
-export default LangPlugin;
+/**
+ * graphile-i18n — PostGraphile v5 i18n Plugin
+ *
+ * Language-aware fields sourced from @i18n translation tables
+ * with Accept-Language negotiation and configurable fallback chains.
+ *
+ * @example
+ * ```typescript
+ * import { I18nPreset } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   extends: [
+ *     I18nPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { I18nPreset } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   extends: [
+ *     I18nPreset({
+ *       defaultLanguages: ['en', 'es'],
+ *       langCodeColumn: 'lang_code',
+ *       allowedTypes: ['text', 'citext'],
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+// Plugin
+export { createI18nPlugin, I18nPlugin } from './plugin';
+// Preset
+export { I18nPreset } from './preset';
+// Middleware
+export { makeI18nContext, additionalGraphQLContextFromRequest } from './middleware';

package/esm/middleware.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Accept-Language middleware for PostGraphile v5
+ *
+ * Parses the Accept-Language header and injects `langCodes` into the
+ * GraphQL context so the i18n plugin can resolve the best translation.
+ */
+export interface I18nMiddlewareOptions {
+    /**
+     * Supported languages for Accept-Language negotiation.
+     * @default ['en']
+     */
+    supportedLanguages?: string[];
+}
+/**
+ * PostGraphile v5 additionalGraphQLContextFromRequest function.
+ *
+ * Parses Accept-Language and injects `langCodes` into the GraphQL context.
+ *
+ * @example
+ * ```typescript
+ * import { makeI18nContext } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   grafast: {
+ *     context: makeI18nContext({ supportedLanguages: ['en', 'es', 'fr'] }),
+ *   },
+ * };
+ * ```
+ */
+export declare function makeI18nContext(options?: I18nMiddlewareOptions): (req: any, _res: any) => Promise<{
+    langCodes: string[];
+}>;
+/**
+ * Convenience export matching the v4 API signature.
+ */
+export declare const additionalGraphQLContextFromRequest: (req: any, _res: any) => Promise<{
+    langCodes: string[];
+}>;

package/esm/middleware.js

@@ -1,57 +1,50 @@
-import DataLoader from 'dataloader';
-import langParser from 'accept-language-parser';
-import env from './env';
-const escapeIdentifier = (str) => `"${str.replace(/"/g, '""')}"`;
-export const makeLanguageDataLoaderForTable = (_req) => {
-    const cache = new Map();
-    return (props, pgClient, languageCodes, identifier, idType, sqlField, gqlField) => {
-        let dataLoader = cache.get(props);
-        if (!dataLoader) {
-            const { table, coalescedFields, variationsTableName, key } = props;
-            const schemaName = escapeIdentifier(table.namespaceName);
-            const baseTable = escapeIdentifier(table.name);
-            const variationTable = escapeIdentifier(variationsTableName);
-            const joinKey = escapeIdentifier(key ?? identifier);
-            const fields = coalescedFields.join(', ');
-            const baseAlias = [schemaName, baseTable].join('.');
-            const variationAlias = [schemaName, variationTable].join('.');
-            dataLoader = new DataLoader(async (ids) => {
-                const { rows } = await pgClient.query(`
-              select *
-              from unnest($1::${idType}[]) ids(${identifier})
-              inner join lateral (
-                select b.${identifier}, v.${sqlField} as "${gqlField}", ${fields}
-                from ${baseAlias} b
-                left join ${variationAlias} v
-                  on (v.${joinKey} = b.${identifier} and array_position($2, ${sqlField}) is not null)
-                where b.${identifier} = ids.${identifier}
-                order by array_position($2, ${sqlField}) asc nulls last
-                limit 1
-              ) tmp on (true)
-              `, [ids, languageCodes]);
-                return ids.map((id) => rows.find((row) => row?.[identifier] === id));
-            });
-            cache.set(props, dataLoader);
-        }
-        return dataLoader;
-    };
-};
-const getAcceptLanguageHeader = (req) => {
+/**
+ * Accept-Language middleware for PostGraphile v5
+ *
+ * Parses the Accept-Language header and injects `langCodes` into the
+ * GraphQL context so the i18n plugin can resolve the best translation.
+ */
+import * as acceptLanguageParser from 'accept-language-parser';
+/**
+ * Extract the Accept-Language header from a request object.
+ * Supports Express (req.get) and raw Node.js (req.headers).
+ */
+function getAcceptLanguageHeader(req) {
     if (!req)
         return undefined;
     const header = typeof req.get === 'function'
         ? req.get('accept-language')
         : req.headers?.['accept-language'];
     return Array.isArray(header) ? header.join(',') : header;
-};
-export const additionalGraphQLContextFromRequest = async (req, _res) => {
-    const acceptLanguage = getAcceptLanguageHeader(req);
-    const language = langParser.pick(env.ACCEPTED_LANGUAGES, acceptLanguage) ??
-        env.ACCEPTED_LANGUAGES[0];
-    const langCodes = language ? [language] : env.ACCEPTED_LANGUAGES;
-    return {
-        langCodes,
-        getLanguageDataLoader: makeLanguageDataLoaderForTable(req)
+}
+/**
+ * PostGraphile v5 additionalGraphQLContextFromRequest function.
+ *
+ * Parses Accept-Language and injects `langCodes` into the GraphQL context.
+ *
+ * @example
+ * ```typescript
+ * import { makeI18nContext } from 'graphile-i18n';
+ *
+ * const preset = {
+ *   grafast: {
+ *     context: makeI18nContext({ supportedLanguages: ['en', 'es', 'fr'] }),
+ *   },
+ * };
+ * ```
+ */
+export function makeI18nContext(options = {}) {
+    const { supportedLanguages = ['en'] } = options;
+    return async (req, _res) => {
+        const acceptLanguage = getAcceptLanguageHeader(req);
+        const picked = acceptLanguage
+            ? acceptLanguageParser.pick(supportedLanguages, acceptLanguage)
+            : null;
+        const langCodes = picked ? [picked] : [supportedLanguages[0]];
+        return { langCodes };
     };
-};
-export default additionalGraphQLContextFromRequest;
+}
+/**
+ * Convenience export matching the v4 API signature.
+ */
+export const additionalGraphQLContextFromRequest = makeI18nContext();

package/esm/plugin.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PostGraphile v5 i18n Plugin
+ *
+ * Discovers tables tagged with @i18n and adds a `localeStrings` field to the
+ * base type. The field resolves the best-matching translation row based on
+ * language codes provided in the GraphQL context, falling back to the base
+ * table's own values when no translation exists.
+ *
+ * Smart tag format:
+ *   COMMENT ON TABLE app_public.posts IS E'@i18n posts_translations';
+ *
+ * The value of @i18n is the name of the translation table in the same schema.
+ * The translation table must have:
+ *   - A FK column referencing the base table's PK
+ *   - A lang_code column (configurable)
+ *   - UNIQUE(fk_column, lang_code)
+ *   - One or more text/citext columns matching the base table's columns
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+import type { I18nPluginOptions } from './types';
+declare global {
+    namespace GraphileConfig {
+        interface Plugins {
+            I18nPlugin: true;
+        }
+    }
+}
+export declare function createI18nPlugin(options?: I18nPluginOptions): GraphileConfig.Plugin;
+export declare const I18nPlugin: GraphileConfig.Plugin;