Merge pull request #372 from launchql/regulate-readme-graphile

Regulate readme graphile

Author: Zetazzz

graphile/graphile-cache/README.md

@@ -16,44 +16,42 @@
   </a>
 </p>
 
-PostGraphile instance LRU cache with automatic cleanup when PostgreSQL pools are disposed.
+**`graphile-cache`** is an LRU cache for PostGraphile handlers with automatic cleanup when PostgreSQL pools are disposed.
 
-## Installation
+> This package integrates with `pg-cache` for PostgreSQL pool management.
+
+## 🚀 Installation
 
 ```bash
 npm install graphile-cache pg-cache
 ```
 
-Note: This package depends on `pg-cache` for the PostgreSQL pool management.
-
-## Features
+## ✨ Features
 
 - LRU cache for PostGraphile instances
 - Automatic cleanup when associated PostgreSQL pools are disposed
 - Integrates seamlessly with `pg-cache`
 - Service cache re-exported for convenience
 - TypeScript support
 
-## How It Works
+## 🧠 How It Works
 
 When you import this package, it automatically registers a cleanup callback with `pg-cache`. When a PostgreSQL pool is disposed, any PostGraphile instances using that pool are automatically removed from the cache.
 
-## Usage
+## 📦 Usage
 
-### Basic Usage
+### Basic caching flow
 
 ```typescript
 import { graphileCache, GraphileCache } from 'graphile-cache';
 import { getPgPool } from 'pg-cache';
 import { postgraphile } from 'postgraphile';
 
-// Create a PostGraphile instance
 const pgPool = getPgPool({ database: 'mydb' });
 const handler = postgraphile(pgPool, 'public', {
   // PostGraphile options
 });
 
-// Cache it
 const cacheEntry: GraphileCache = {
   pgPool,
   pgPoolKey: 'mydb',
@@ -69,7 +67,7 @@ if (cached) {
 }
 ```
 
-### Automatic Cleanup
+### Automatic cleanup when pools disappear
 
 The cleanup happens automatically:
 
@@ -89,7 +87,7 @@ console.log(graphileCache.has('mydb.public')); // false
 console.log(graphileCache.has('mydb.private')); // false
 ```
 
-### Complete Example
+### Complete example with Express
 
 ```typescript
 import { graphileCache, GraphileCache } from 'graphile-cache';
@@ -136,14 +134,14 @@ app.use((req, res, next) => {
 ```typescript
 import { closeAllCaches } from 'graphile-cache';
 
-// This closes all caches including pg pools
 process.on('SIGTERM', async () => {
+  // Closes all caches including pg pools
   await closeAllCaches();
   process.exit(0);
 });
 ```
 
-## API Reference
+## 📘 API Reference
 
 ### graphileCache
 
@@ -173,7 +171,7 @@ Closes all caches including the service cache, graphile cache, and all PostgreSQ
 
 Re-exported from `pg-cache` for convenience.
 
-## Integration Details
+## 🔌 Integration Details
 
 The integration with `pg-cache` happens automatically when this module is imported. The cleanup callback is registered immediately, ensuring that PostGraphile instances are cleaned up whenever their associated PostgreSQL pools are disposed.
 

graphile/graphile-i18n/README.md

@@ -16,15 +16,22 @@
   </a>
 </p>
 
-TypeScript rewrite of the Graphile/PostGraphile i18n plugin. Adds language-aware fields sourced from translation tables declared via smart comments.
+**`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.
 
-## Install
+## 🚀 Installation
 
 ```bash
 pnpm add graphile-i18n
 ```
 
-## Usage
+## ✨ Features
+
+- 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
+
+## 📦 Usage
 
 1. Add a translation table and tag the base table with `@i18n`:
 
@@ -70,12 +77,18 @@ app.use(
 
 Requests with `Accept-Language` headers receive the closest translation; fields fall back to the base table values when a translation is missing.
 
-## Tests
+## 🧰 Configuration Options
 
-Tests run against a real Postgres instance using `graphile-test`:
+All options are provided through `graphileBuildOptions`:
 
-```bash
-pnpm test
-```
+- `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']`
+
+## 🧪 Testing
 
-Ensure Postgres is available at `postgres://postgres:password@localhost:5432`.
+```sh
+# requires a local Postgres available (defaults to postgres/password@localhost:5432)
+pnpm --filter graphile-i18n test
+```

graphile/graphile-meta-schema/README.md

@@ -16,13 +16,41 @@
   </a>
 </p>
 
-## Install
+**`graphile-meta-schema`** exposes a `_meta` GraphQL schema so you can introspect tables, fields, and constraints directly from PostGraphile.
+
+## 🚀 Installation
 
 ```sh
 pnpm add graphile-meta-schema
 ```
 
-## Example Query
+## ✨ Features
+
+- GraphQL meta endpoint for table/field/constraint details
+- Works alongside your existing PostGraphile schemas
+- Ships with fixtures to explore constraint metadata
+
+## 📦 Usage
+
+Register the plugin with PostGraphile (CLI or library):
+
+```ts
+import express from 'express';
+import { postgraphile } from 'postgraphile';
+import PgMetaschemaPlugin from 'graphile-meta-schema';
+
+const app = express();
+
+app.use(
+  postgraphile(process.env.DATABASE_URL, ['app_public'], {
+    appendPlugins: [PgMetaschemaPlugin]
+  })
+);
+```
+
+The plugin adds a `_meta` query root alongside your existing schemas. Use it to inspect fields, constraints, relations, and generated inflection.
+
+### Example Query
 
 ```gql
 query MetaQuery {
@@ -88,17 +116,9 @@ query MetaQuery {
 }
 ```
 
-## Testing
+## 🧪 Testing
 
 ```sh
 # requires a local Postgres with PostGIS available (defaults to postgres/password@localhost:5432)
 pnpm --filter graphile-meta-schema test
-```
-
-If you want to explore the fixtures manually:
-
-```sh
-createdb metaschema_example
-psql metaschema_example < sql/test.sql
-psql metaschema_example < sql/types.sql
-```
+```

graphile/graphile-pg-type-mappings/README.md

@@ -16,9 +16,22 @@
   </a>
 </p>
 
-Custom PostgreSQL type mappings plugin for Graphile/PostGraphile.
+**`graphile-pg-type-mappings`** is a Graphile/PostGraphile plugin that maps custom PostgreSQL types to GraphQL scalars.
 
-This plugin provides custom type mappings for PostgreSQL types to GraphQL types, including:
+## 🚀 Installation
+
+```bash
+npm install graphile-pg-type-mappings
+```
+
+## ✨ Features
+
+- Sensible defaults for common custom Postgres types (`email`, `origin`, `multiple_select`, etc.)
+- Override or extend mappings via `customTypeMappings`
+- Works with PostGraphile v4 as a standard plugin
+- TypeScript definitions for mapping configuration
+
+### Default mappings
 
 - `email` → `String`
 - `hostname` → `String`
@@ -29,13 +42,7 @@ This plugin provides custom type mappings for PostgreSQL types to GraphQL types,
 
 > **Note:** If you need PostGIS types (like `geolocation` or `geopolygon` → `GeoJSON`), you can add them via `customTypeMappings` when using the PostGIS plugin.
 
-## Installation
-
-```bash
-npm install graphile-pg-type-mappings
-```
-
-## Usage
+## 📦 Usage
 
 ### Basic Usage (Default Mappings)
 
@@ -132,7 +139,7 @@ const postgraphileOptions = {
 };
 ```
 
-## API
+## 📘 API
 
 ### `CustomPgTypeMappingsPlugin`
 
@@ -155,3 +162,10 @@ interface CustomPgTypeMappingsPluginOptions {
   customTypeMappings?: TypeMapping[];
 }
 ```
+
+## 🧪 Testing
+
+```sh
+# requires a local Postgres available (defaults to postgres/password@localhost:5432)
+pnpm --filter graphile-pg-type-mappings test
+```

graphile/graphile-plugin-connection-filter-postgis/README.md

@@ -16,16 +16,44 @@
   </a>
 </p>
 
-This plugin exposes additional PostGIS-related fields on the `filter` argument of Connections.
+**`graphile-plugin-connection-filter-postgis`** exposes PostGIS-aware operators on the `filter` argument for PostGraphile connections.
 
-## Usage
+## 🚀 Installation
+
+```bash
+npm install graphile-plugin-connection-filter-postgis
+```
+
+## ✨ Features
+
+- Adds PostGIS functions and operators to `graphile-plugin-connection-filter`
+- Supports both `geometry` and `geography` columns
+- Works with PostGraphile v4 filter inputs
+
+## 📦 Usage
 
 Requires `postgraphile@^4.5.0` and the following plugins appended prior to this plugin:
 
 - `@graphile/postgis@0.1.0`
 - `graphile-plugin-connection-filter@^2.0.0`
 
-## Operators
+```ts
+import PostGISFilterPlugin from 'graphile-plugin-connection-filter-postgis';
+import PostGISPlugin from '@graphile/postgis';
+import ConnectionFilterPlugin from 'graphile-plugin-connection-filter';
+
+app.use(
+  postgraphile(pgConfig, schemas, {
+    appendPlugins: [
+      PostGISPlugin,
+      ConnectionFilterPlugin,
+      PostGISFilterPlugin
+    ]
+  })
+);
+```
+
+## 🔎 Operators
 
 | PostGIS function | Types | GraphQL field name |
 | --- | --- | --- |
@@ -59,13 +87,11 @@ Requires `postgraphile@^4.5.0` and the following plugins appended prior to this
 | ~ | geometry | bboxContains |
 | ~= | geometry | bboxEquals |
 
-## Development
+## 🧑‍💻 Development
 
-To establish a test environment, create an empty PostgreSQL database and set a `TEST_DATABASE_URL` environment variable with your database connection string.
+## 🧪 Testing
 
-```bash
-createdb graphile_test
-export TEST_DATABASE_URL=postgres://localhost:5432/graphile_test
-yarn
-yarn test
+```sh
+# requires a local Postgres with PostGIS available (defaults to postgres/password@localhost:5432)
+pnpm --filter graphile-plugin-connection-filter-postgis test
 ```