Promote docs

Author: benjie

postgraphile/website/versioned_docs/version-5/add-pg-table-order-by.md

@@ -226,3 +226,62 @@ use a simpler expression for comparisons which is not null-capable, and this
 will break cursor pagination when nulls occur.
 
 :::
+
+### Using context or other steps in the addPgTableOrderBy plugin
+
+You can use the `applyScope` method to access the context of the query. This
+method is called with the `PgSelectQueryBuilder` and can be used to apply
+additional filtering or ordering based on the context.
+
+```ts
+import { addPgTableOrderBy, orderByAscDesc } from "postgraphile/utils";
+
+// Apply scope for the specific type.
+const applyScopePlugin: GraphileConfig.Plugin = {
+  name: "applyScopePlugin",
+  schema: {
+    hooks: {
+      GraphQLEnumType(config, build) {
+        const { TYPES } = build.dataplanPg;
+        if (config.name === "CityOrderBy") {
+          const {
+            grafast: { context },
+          } = build;
+          config.extensions ??= {};
+          // @ts-expect-error The type is readonly by types you may get an error here.
+          config.extensions.grafast ??= {};
+          config.extensions.grafast.applyScope = () => context(); // Or any other unary step.
+        }
+        return config;
+      },
+    },
+  },
+};
+
+export default addPgTableOrderBy(
+  { schemaName: "app_public", tableName: "users" },
+  ({ sql }) => {
+    return orderByAscDesc(
+      "CITY_NAME",
+      (queryBuilder, info) => {
+        const { scope } = info;
+
+        const context = scope; // As we applied context as scope.
+
+        const orderByFrag = sql`(
+          select coalesce(
+            (select value from public.transactions t where t.key = ${queryBuilder.alias}.name and language = ${sqlValueWithCodec(
+              context?.locale,
+              TYPES.text,
+            )}),
+            ${queryBuilder.alias}.name
+          )
+        )`;
+
+        return { fragment: orderByFrag, codec: TYPES.text };
+      },
+      { nulls: "last-iff-ascending" },
+    );
+  },
+);
+```

postgraphile/website/versioned_docs/version-5/community-plugins.md

@@ -84,6 +84,12 @@ Schema extension plugins for PostGraphile:
   foreign relationships to be created. :question:_(Not yet ported to V5, but use the "relay" preset instead?)_
 - [postgraphile-plugin-timestamp-format](https://github.com/RedShift1/postgraphile-plugin-timestamp-format) -
   Format timestamps with PostgreSQL’s to*char function. Supports timezones too :question:*(Not yet ported to V5)\_
+- [@haathie/postgraphile-fancy-mutations](https://github.com/haathie/graphile-tools/tree/main/packages/fancy-mutations) - Plugin for performant bulk upserts with nested relations, bulk updates, and deletes. :white_check_mark:
+- [@haathie/postgraphile-targeted-conditions](https://github.com/haathie/graphile-tools/tree/main/packages/targeted-conditions) - Plugin for advanced filtering, including relational conditions, [ParadeDB](https://github.com/paradedb/paradedb) support, and more. :white_check_mark:
+- [@haathie/postgraphile-realtime](https://github.com/haathie/graphile-tools/tree/main/packages/realtime) - Plugin for performant, conditional subscriptions, allowing real-time updates from any table in your Postgres database. :white_check_mark:
+- [@haathie/postgraphile-rate-limits](https://github.com/haathie/graphile-tools/tree/main/packages/rate-limits) - Plugin for rate limiting queries and mutations. Add rate limits using smart tags and get reasonably friendly error messages. :white_check_mark:
+- [@haathie/postgraphile-otel](https://github.com/haathie/graphile-tools/tree/main/packages/otel) - Plugin for OpenTelemetry Tracing Capabilities for GraphQL Requests. :white_check_mark:
+- [@haathie/postgraphile-reasonable-limits](https://github.com/haathie/graphile-tools/tree/main/packages/reasonable-limits) - Plugin to enforce reasonable limits on queries, preventing excessive data retrieval. :white_check_mark:
 
 Examples of using these plugins:
 

postgraphile/website/versioned_docs/version-5/extending.md renamed to postgraphile/website/versioned_docs/version-5/extending.mdx

@@ -2,6 +2,8 @@
 title: GraphQL Schema Plugins
 ---
 
+import DocCardList from "@theme/DocCardList";
+
 PostGraphile’s schema generator is built from a number of
 [graphile-build plugins](https://build.graphile.org/graphile-build/5/plugins). You can
 write your own plugins — either using the helpers available in `graphile-utils`,
@@ -73,3 +75,7 @@ Remember: multiple versions of `graphql` in your `node_modules` will cause
 problems; so we **strongly** recommend using the `graphql` object that's
 available on the `Build` object (second argument to hooks) rather than requiring
 your own version.
+
+### Schema plugins
+
+<DocCardList />

postgraphile/website/versioned_docs/version-5/polymorphism.md

@@ -227,6 +227,16 @@ comment on table polymorphic.gcp_applications is $$
   $$;
 ```
 
+:::warning[Cannot return mode:union from functions]
+
+You will not be able to return the `mode:union` type from a PostgreSQL function.
+Consider the above example - if we receive
+`{id: 1, name: "Foo", last_deployed: null}` how can we know if this came from
+`aws_applications` or `gcp_applications`? Instead, consider using
+[`extendSchema`](./extend-schema.md).
+
+:::
+
 ## @unionMember
 
 For cases where you want multiple tables that don't necessarily share any

postgraphile/website/versioned_docs/version-5/requirements.md

@@ -49,9 +49,8 @@ experience.
   or primary key is defined for a table." --
   [PG docs](https://www.postgresql.org/docs/current/static/indexes-unique.html)
 - **Use the defaults** for formatting output; we only run tests for the
-  defaults so you may have an issue if you were to use, for example,
-  `intervalstyle = 'iso_8601'` rather than the default
-  `intervalstyle = 'postgres'`.
+  defaults so if you change them you may face issues. (You may change
+  `intervalstyle` since we have specific handling code for that.)
 - **Use UTF8 encoding**: GraphQL operates over the UTF8 character set, using
   different encodings may impact your ability to store/retrieve certain values.
 

postgraphile/website/versioned_docs/version-5/usage-schema.md

@@ -103,7 +103,7 @@ Here's a full example:
 
 ```ts
 import { postgraphile } from "postgraphile";
-import { grafast } from "postgraphile/grafast";
+import { grafast, type ErrorBehavior } from "postgraphile/grafast";
 import preset from "./graphile.config.js";
 
 // Make a new PostGraphile instance:
@@ -121,13 +121,15 @@ export async function executeQuery(
   source: string,
   variableValues?: Record<string, unknown> | null,
   operationName?: string,
+  onError?: ErrorBehavior,
 ) {
   const { schema, resolvedPreset } = await pgl.getSchemaResult();
   return await grafast({
     schema,
     source,
     variableValues,
     operationName,
+    onError,
     resolvedPreset,
     requestContext,
   });
@@ -158,7 +160,7 @@ Here's an example using hookArgs:
 ```ts
 import { postgraphile } from "postgraphile";
 import { parse, validate } from "postgraphile/graphql";
-import { execute, hookArgs } from "postgraphile/grafast";
+import { execute, hookArgs, type ErrorBehavior } from "postgraphile/grafast";
 import preset from "./graphile.config.js";
 
 // Build a `pgl` instance, with helpers and schema based on our preset.
@@ -174,6 +176,7 @@ export async function executeQuery(
   source: string,
   variableValues?: Record<string, unknown> | null,
   operationName?: string,
+  onError?: ErrorBehavior,
 ) {
   // We might get a newer schema in "watch" mode
   const { schema, resolvedPreset } = await pgl.getSchemaResult();
@@ -193,6 +196,7 @@ export async function executeQuery(
     document,
     variableValues,
     operationName,
+    onError,
     resolvedPreset,
     requestContext,
   });
@@ -204,28 +208,36 @@ export async function executeQuery(
 
 ### Example using `TypedDocumentNode`
 
-You can use GraphQL Code Generator with the client-preset to make your GraphQL
-execution function type safe. In this case, rather than passing in a raw
+You can use GraphQL Code Generator with the `client-preset` to make your GraphQL
+execution function type-safe. In this case, rather than passing in a raw
 `source` string, we pass in a `TypedDocumentNode` which is generated by the
 `gql` tagged template literal, and this means the result we return will
-automatically reflect the correct types thanks to graphql-codegen:
+automatically reflect the correct types thanks to `graphql-codegen`:
 
 ```ts
 import type { DocumentNode, ExecutionResult } from "postgraphile/graphql";
-import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
+import type {
+  TypedDocumentNode,
+  VariablesOf,
+  ResultOf,
+} from "@graphql-typed-document-node/core";
 import { postgraphile } from "postgraphile";
-import { execute, hookArgs } from "postgraphile/grafast";
+import { execute, hookArgs, type ErrorBehavior } from "postgraphile/grafast";
 import { validate } from "postgraphile/graphql";
 import preset from "./graphile.config.js";
 
 const pgl = postgraphile(preset);
 
-export async function executeDocument<TData = any, TVariables = any>(
+export async function executeDocument<
+  TDoc extends TypedDocumentNode | DocumentNode,
+  TExtensions = ObjMap<unknown>,
+>(
   requestContext: Partial<Grafast.RequestContext>,
-  document: DocumentNode | TypedDocumentNode<TData, TVariables>,
-  variableValues?: Record<string, unknown> | null,
+  document: TDoc,
+  variableValues?: VariablesOf<TDoc>,
   operationName?: string,
-): Promise<ExecutionResult<TData, TVariables>> {
+  onError?: ErrorBehavior,
+): Promise<ExecutionResult<ResultOf<TDoc>, TExtensions>> {
   const { schema, resolvedPreset } = await pgl.getSchemaResult();
 
   // Validate the GraphQL document against the schema:
@@ -240,14 +252,29 @@ export async function executeDocument<TData = any, TVariables = any>(
     document,
     variableValues,
     operationName,
+    onError,
     resolvedPreset,
     requestContext,
-  });
+  } as any);
 
   // Execute the request using Grafast:
   const result = await execute(args);
 
   // Cast the result to the types implied by the TypedDocumentNode:
-  return result as ExecutionResult<TData, TVariables>;
+  return result as ExecutionResult<ResultOf<TDoc>, TExtensions>;
 }
 ```
+
+Usage for [`gql.tada`](https://gql-tada.0no.co/guides/typed-documents) is
+similar; just import the helpers from `gql.tada` instead and note that
+`TypedDocumentNode` is renamed to `TadaDocumentNode`:
+
+```diff
+ import type {
+   VariablesOf,
+   ResultOf,
+-  TypedDocumentNode,
++  TadaDocumentNode,
+-} from "@graphql-typed-document-node/core";
++} from "gql.tada";
+```