@drizzle-graphql-suite/schema 0.5.0 → 0.7.0

package/README.md

@@ -1,17 +1,43 @@
 # @drizzle-graphql-suite/schema
 
+> Part of [`drizzle-graphql-suite`](https://github.com/annexare/drizzle-graphql-suite).
+> See also: [`client`](https://github.com/annexare/drizzle-graphql-suite/tree/main/packages/client) | [`query`](https://github.com/annexare/drizzle-graphql-suite/tree/main/packages/query)
+
 Auto-generates a complete GraphQL schema with CRUD operations, relation-level filtering, and hooks from Drizzle PostgreSQL schemas.
 
+## Installation
+
+```bash
+bun add @drizzle-graphql-suite/schema
+```
+
+```bash
+npm install @drizzle-graphql-suite/schema
+```
+
+Or install the full suite:
+
+```bash
+bun add drizzle-graphql-suite
+```
+
+```bash
+npm install drizzle-graphql-suite
+```
+
 ## Motivation
 
 Inspired by [`drizzle-graphql`](https://github.com/drizzle-team/drizzle-graphql), this package is a purpose-built replacement focused on PostgreSQL. Key improvements:
 
+- **Small generated schema** — the generated schema stays compact even when supporting self-relations and deeply nested relations, thanks to configurable depth limiting (`limitRelationDepth`, `limitSelfRelationDepth`), per-relation pruning (`pruneRelations`), and per-table control (`tables.exclude`, per-table `queries`/`mutations` toggles) — up to 90% schema size reduction when tuned
+- **Native PostgreSQL JSON/JSONB support** — `json` and `jsonb` columns map to a custom `JSON` GraphQL scalar, so structured data passes through without manual type wiring
 - **Relation-level filtering** with EXISTS subqueries (`some`/`every`/`none` quantifiers)
+- **Runtime permissions** — `withPermissions()` builds filtered schemas per role, fully reflected in introspection
+- **Row-level security helpers** — `withRowSecurity()` + `mergeHooks()` for composable auth
 - **Per-operation hooks system** (before/after/resolve) for auth, audit, and custom logic
 - **Count queries** with full filter support
 - **`buildEntities()`** for composable schema building (avoids redundant schema validation)
 - **Configurable query/mutation suffixes** for naming customization
-- **Per-table schema control** — exclude tables, disable queries/mutations per table (up to 90% schema size reduction)
 - **Self-relation depth limiting** — separate from general depth, prevents exponential type growth
 - **Relation pruning** — `false`, `'leaf'`, or `{ only: [...] }` per relation
 - **`buildSchemaFromDrizzle()`** — no database connection needed (for codegen/introspection)
@@ -23,14 +49,14 @@ Inspired by [`drizzle-graphql`](https://github.com/drizzle-team/drizzle-graphql)
 
 ### `buildSchema(db, config?)`
 
-Builds a complete `GraphQLSchema` with all CRUD operations from a Drizzle database instance. Returns `{ schema, entities }`.
+Builds a complete `GraphQLSchema` with all CRUD operations from a Drizzle database instance. Returns `{ schema, entities, withPermissions }`.
 
 ```ts
 import { buildSchema } from 'drizzle-graphql-suite/schema'
 import { createYoga } from 'graphql-yoga'
 import { db } from './db'
 
-const { schema, entities } = buildSchema(db, {
+const { schema, entities, withPermissions } = buildSchema(db, {
   limitRelationDepth: 3,
   tables: { exclude: ['session'] },
 })
@@ -38,6 +64,39 @@ const { schema, entities } = buildSchema(db, {
 const yoga = createYoga({ schema })
 ```
 
+See [Runtime Permissions](#runtime-permissions) for `withPermissions` usage.
+
+#### Framework Integration
+
+**Next.js App Router**
+
+```ts
+// app/api/graphql/route.ts
+import { createYoga } from 'graphql-yoga'
+import { schema } from '@/lib/schema' // from buildSchema() above
+
+const { handleRequest } = createYoga({
+  schema,
+  graphqlEndpoint: '/api/graphql',
+  fetchAPI: { Response },
+})
+
+export { handleRequest as GET, handleRequest as POST }
+```
+
+**ElysiaJS**
+
+```ts
+// server.ts
+import { Elysia } from 'elysia'
+import { yoga } from '@elysiajs/graphql-yoga'
+import { schema } from './schema' // from buildSchema() above
+
+new Elysia()
+  .use(yoga({ schema }))
+  .listen(3000)
+```
+
 ### `buildEntities(db, config?)`
 
 Returns `GeneratedEntities` only — queries, mutations, inputs, and types — without constructing a `GraphQLSchema`. Use this when composing into a larger schema (e.g., Pothos) to avoid redundant schema validation.
@@ -145,6 +204,92 @@ Enable diagnostic logging for schema size and relation tree.
 - **Type**: `boolean | { schemaSize?: boolean; relationTree?: boolean }`
 - **Default**: `undefined`
 
+## Runtime Permissions
+
+Build filtered `GraphQLSchema` variants per role or user — introspection fully reflects what each role can see and do.
+
+```ts
+import { buildSchema, permissive, restricted, readOnly } from 'drizzle-graphql-suite/schema'
+
+const { schema, withPermissions } = buildSchema(db)
+
+// Full schema (admin)
+const adminSchema = schema
+
+// Permissive: everything allowed except audit (excluded) and users (read-only)
+const maintainerSchema = withPermissions(
+  permissive('maintainer', { audit: false, users: readOnly() }),
+)
+
+// Restricted: nothing allowed except posts and comments (queries only)
+const userSchema = withPermissions(
+  restricted('user', { posts: { query: true }, comments: { query: true } }),
+)
+
+// Restricted with nothing granted — only Query { _empty: Boolean }
+const anonSchema = withPermissions(restricted('anon'))
+```
+
+Schemas are cached by `id` — calling `withPermissions` with the same `id` returns the same `GraphQLSchema` instance.
+
+### Permission Helpers
+
+| Helper | Description |
+|--------|-------------|
+| `permissive(id, tables?)` | All tables allowed by default; overrides deny |
+| `restricted(id, tables?)` | Nothing allowed by default; overrides grant |
+| `readOnly()` | Shorthand for `{ query: true, insert: false, update: false, delete: false }` |
+
+### Table Access
+
+Each table can be set to `true` (all operations), `false` (excluded entirely), or a `TableAccess` object:
+
+```ts
+type TableAccess = {
+  query?: boolean   // list + single + count
+  insert?: boolean  // insert + insertSingle
+  update?: boolean
+  delete?: boolean
+}
+```
+
+In **permissive** mode, omitted fields default to `true`. In **restricted** mode, omitted fields default to `false`.
+
+### Introspection Behavior
+
+- `false` (excluded table) — removed from everywhere: no entry points, no relation fields on other types, no filter fields
+- `readOnly()` — table types exist (accessible via relations), but only query entry points; no mutations
+- Granular control — e.g. `{ query: true, insert: true, delete: false }` removes only `deleteFrom{Table}` mutation
+
+## Row-Level Security
+
+Generate hooks that inject WHERE clauses for row-level filtering. Compose with other hooks using `mergeHooks`.
+
+```ts
+import { buildSchema, withRowSecurity, mergeHooks } from 'drizzle-graphql-suite/schema'
+
+const { schema } = buildSchema(db, {
+  hooks: mergeHooks(
+    withRowSecurity({
+      posts: (context) => ({ authorId: { eq: context.user.id } }),
+    }),
+    myOtherHooks,
+  ),
+})
+```
+
+### `withRowSecurity(rules)`
+
+Generates a `HooksConfig` with `before` hooks on `query`, `querySingle`, `count`, `update`, and `delete` operations. Each rule is a function that receives the GraphQL context and returns a WHERE filter object.
+
+### `mergeHooks(...configs)`
+
+Deep-merges multiple `HooksConfig` objects:
+
+- **`before` hooks** — chained sequentially; each receives the previous hook's modified args
+- **`after` hooks** — chained sequentially; each receives the previous hook's result
+- **`resolve` hooks** — last one wins (cannot be composed)
+
 ## Hooks System
 
 Hooks intercept operations for auth, validation, audit logging, or custom resolution.
@@ -266,6 +411,8 @@ query {
 
 ## Code Generation
 
+> **When to use:** Only when the client is in a separate repository that cannot import the Drizzle schema directly. For same-repo setups, [`createDrizzleClient`](https://github.com/annexare/drizzle-graphql-suite/tree/main/packages/client) infers all types automatically — no codegen needed.
+
 Three code generation functions for producing static artifacts from a GraphQL schema:
 
 ### `generateSDL(schema)`
@@ -299,7 +446,7 @@ writeFileSync('generated/types.ts', types)
 
 ### `generateEntityDefs(schema, options?)`
 
-Generates a runtime schema descriptor object and `EntityDefs` type for the client package. This is an alternative to `createDrizzleClient` — useful when you want to ship pre-built schema metadata.
+Generates a runtime schema descriptor object and `EntityDefs` type for the client package. Use this instead of `createDrizzleClient` when the client is in a separate repo and can't import the Drizzle schema.
 
 ```ts
 import { generateEntityDefs } from 'drizzle-graphql-suite/schema'

package/index.d.ts

@@ -1,10 +1,12 @@
 import type { PgDatabase } from 'drizzle-orm/pg-core';
 import type { GraphQLSchema } from 'graphql';
-import type { BuildSchemaConfig, GeneratedEntities } from './types';
+import type { BuildSchemaConfig, GeneratedEntities, PermissionConfig } from './types';
 export { GraphQLJSON } from './graphql/scalars';
 export declare const buildSchema: (db: PgDatabase<any, any, any>, config?: BuildSchemaConfig) => {
     schema: GraphQLSchema;
     entities: GeneratedEntities;
+    withPermissions: (permissions: PermissionConfig) => GraphQLSchema;
+    clearPermissionCache: (id?: string) => void;
 };
 export declare const buildEntities: (db: PgDatabase<any, any, any>, config?: BuildSchemaConfig) => GeneratedEntities;
 /**
@@ -19,8 +21,12 @@ export declare const buildEntities: (db: PgDatabase<any, any, any>, config?: Bui
 export declare const buildSchemaFromDrizzle: (drizzleSchema: Record<string, unknown>, config?: BuildSchemaConfig) => {
     schema: GraphQLSchema;
     entities: GeneratedEntities;
+    withPermissions: (permissions: PermissionConfig) => GraphQLSchema;
+    clearPermissionCache: (id?: string) => void;
 };
 export type { CodegenOptions } from './codegen';
 export { generateEntityDefs, generateSDL, generateTypes } from './codegen';
+export { permissive, readOnly, restricted } from './permissions';
+export { mergeHooks, withRowSecurity } from './row-security';
 export { SchemaBuilder } from './schema-builder';
 export * from './types';

package/index.js

@@ -363,6 +363,103 @@ var drizzleColumnToGraphQLType = (column, columnName, tableName, forceNullable =
   return typeDesc;
 };
 
+// src/permissions.ts
+var readOnly = () => ({
+  query: true,
+  insert: false,
+  update: false,
+  delete: false
+});
+var permissive = (id, tables) => ({
+  id,
+  mode: "permissive",
+  tables
+});
+var restricted = (id, tables) => ({
+  id,
+  mode: "restricted",
+  tables
+});
+function mergePermissionsIntoConfig(baseConfig, permissions, allTableNames) {
+  const excluded = [...baseConfig.tables?.exclude ?? []];
+  const tableConfig = {
+    ...baseConfig.tables?.config ?? {}
+  };
+  const mutationFilter = {};
+  for (const tableName of allTableNames) {
+    if (excluded.includes(tableName))
+      continue;
+    const access = resolveTableAccess(permissions, tableName);
+    if (access === false) {
+      excluded.push(tableName);
+      continue;
+    }
+    if (access === true) {
+      continue;
+    }
+    const defaultAllow = permissions.mode === "permissive";
+    const queryAllowed = access.query ?? defaultAllow;
+    const insertAllowed = access.insert ?? defaultAllow;
+    const updateAllowed = access.update ?? defaultAllow;
+    const deleteAllowed = access.delete ?? defaultAllow;
+    if (!queryAllowed && !insertAllowed && !updateAllowed && !deleteAllowed) {
+      excluded.push(tableName);
+      continue;
+    }
+    tableConfig[tableName] = {
+      ...tableConfig[tableName],
+      queries: queryAllowed
+    };
+    const anyMutation = insertAllowed || updateAllowed || deleteAllowed;
+    if (!anyMutation) {
+      tableConfig[tableName] = { ...tableConfig[tableName], mutations: false };
+    } else {
+      tableConfig[tableName] = { ...tableConfig[tableName], mutations: true };
+      if (!insertAllowed || !updateAllowed || !deleteAllowed) {
+        mutationFilter[tableName] = {
+          insert: insertAllowed,
+          update: updateAllowed,
+          delete: deleteAllowed
+        };
+      }
+    }
+  }
+  const config = {
+    ...baseConfig,
+    tables: {
+      exclude: excluded.length ? excluded : undefined,
+      config: Object.keys(tableConfig).length ? tableConfig : undefined
+    }
+  };
+  return { config, mutationFilter };
+}
+function resolveTableAccess(permissions, tableName) {
+  const override = permissions.tables?.[tableName];
+  if (permissions.mode === "permissive") {
+    if (override === undefined)
+      return true;
+    return override;
+  }
+  if (override === undefined)
+    return false;
+  return override;
+}
+function postFilterMutations(mutations, mutationFilter) {
+  for (const [tableName, flags] of Object.entries(mutationFilter)) {
+    const cap = capitalize(tableName);
+    if (!flags.insert) {
+      delete mutations[`insertInto${cap}`];
+      delete mutations[`insertInto${cap}Single`];
+    }
+    if (!flags.update) {
+      delete mutations[`update${cap}`];
+    }
+    if (!flags.delete) {
+      delete mutations[`deleteFrom${cap}`];
+    }
+  }
+}
+
 // src/schema-builder.ts
 class SchemaBuilder {
   db;
@@ -376,6 +473,7 @@ class SchemaBuilder {
   suffixes;
   limitRelationDepth;
   limitSelfRelationDepth;
+  allTableNames;
   excludedTables;
   tableOperations;
   pruneRelations;
@@ -434,6 +532,7 @@ class SchemaBuilder {
       }
     });
     this.tables = this.extractTables(schema);
+    this.allTableNames = Object.keys(this.tables);
     this.excludedTables = new Set(config?.tables?.exclude ?? []);
     this.tableOperations = config?.tables?.config ?? {};
     for (const tableName of this.excludedTables) {
@@ -533,7 +632,58 @@ class SchemaBuilder {
     }
     const schema = new GraphQLSchema(graphQLSchemaConfig);
     this.logDebugInfo(schema);
-    return { schema, entities };
+    const cache = new Map;
+    const db = this.db;
+    const baseConfig = this.config;
+    const allTableNames = this.allTableNames;
+    const withPermissions = (permissions) => {
+      const cached = cache.get(permissions.id);
+      if (cached)
+        return cached;
+      const { config: mergedConfig, mutationFilter } = mergePermissionsIntoConfig(baseConfig, permissions, allTableNames);
+      const excludedSet = new Set(mergedConfig.tables?.exclude ?? []);
+      const hasAnyTable = allTableNames.some((t) => !excludedSet.has(t));
+      if (!hasAnyTable) {
+        const emptySchema = new GraphQLSchema({
+          query: new GraphQLObjectType2({
+            name: "Query",
+            fields: {
+              _empty: { type: GraphQLBoolean2 }
+            }
+          })
+        });
+        cache.set(permissions.id, emptySchema);
+        return emptySchema;
+      }
+      const permBuilder = new SchemaBuilder(db, mergedConfig);
+      const permEntities = permBuilder.buildEntities();
+      if (Object.keys(mutationFilter).length) {
+        postFilterMutations(permEntities.mutations, mutationFilter);
+      }
+      const permSchemaConfig = {
+        types: [...Object.values(permEntities.inputs), ...Object.values(permEntities.types)],
+        query: new GraphQLObjectType2({
+          name: "Query",
+          fields: Object.keys(permEntities.queries).length ? permEntities.queries : { _empty: { type: GraphQLBoolean2 } }
+        })
+      };
+      if (mergedConfig.mutations !== false && Object.keys(permEntities.mutations).length) {
+        permSchemaConfig.mutation = new GraphQLObjectType2({
+          name: "Mutation",
+          fields: permEntities.mutations
+        });
+      }
+      const permSchema = new GraphQLSchema(permSchemaConfig);
+      cache.set(permissions.id, permSchema);
+      return permSchema;
+    };
+    const clearPermissionCache = (id) => {
+      if (id)
+        cache.delete(id);
+      else
+        cache.clear();
+    };
+    return { schema, entities, withPermissions, clearPermissionCache };
   }
   logDebugInfo(schema) {
     const debug = this.config.debug;
@@ -1774,6 +1924,81 @@ function generateEntityDefs(schema, options) {
   return lines.join(`
 `);
 }
+// src/row-security.ts
+function withRowSecurity(rules) {
+  const hooks = {};
+  for (const [tableName, rule] of Object.entries(rules)) {
+    const before = (ctx) => {
+      const whereClause = rule(ctx.context);
+      const existingWhere = ctx.args?.where;
+      const mergedWhere = existingWhere ? { ...existingWhere, ...whereClause } : whereClause;
+      return { args: { ...ctx.args, where: mergedWhere } };
+    };
+    const ops = ["query", "querySingle", "count", "update", "delete"];
+    const tableHooks = {};
+    for (const op of ops) {
+      tableHooks[op] = { before };
+    }
+    hooks[tableName] = tableHooks;
+  }
+  return hooks;
+}
+function mergeHooks(...configs) {
+  const result = {};
+  for (const config of configs) {
+    if (!config)
+      continue;
+    for (const [tableName, tableHooks] of Object.entries(config)) {
+      if (!result[tableName]) {
+        result[tableName] = {};
+      }
+      const existing = result[tableName];
+      for (const [op, hooks] of Object.entries(tableHooks)) {
+        if (!existing[op]) {
+          existing[op] = hooks;
+          continue;
+        }
+        const existingOp = existing[op];
+        if ("resolve" in hooks) {
+          existing[op] = hooks;
+          continue;
+        }
+        if ("resolve" in existingOp) {
+          existing[op] = hooks;
+          continue;
+        }
+        const merged = {};
+        if (hooks.before && existingOp.before) {
+          const first = existingOp.before;
+          const second = hooks.before;
+          merged.before = async (ctx) => {
+            const firstResult = await first(ctx);
+            const nextCtx = firstResult?.args ? { ...ctx, args: firstResult.args } : ctx;
+            const secondResult = await second(nextCtx);
+            return {
+              args: secondResult?.args ?? firstResult?.args ?? undefined,
+              data: secondResult?.data ?? firstResult?.data ?? undefined
+            };
+          };
+        } else {
+          merged.before = hooks.before ?? existingOp.before;
+        }
+        if (hooks.after && existingOp.after) {
+          const first = existingOp.after;
+          const second = hooks.after;
+          merged.after = async (ctx) => {
+            const firstResult = await first(ctx);
+            return second({ ...ctx, result: firstResult });
+          };
+        } else {
+          merged.after = hooks.after ?? existingOp.after;
+        }
+        existing[op] = merged;
+      }
+    }
+  }
+  return result;
+}
 
 // src/index.ts
 var buildSchema = (db, config) => {
@@ -1801,6 +2026,11 @@ var buildSchemaFromDrizzle = (drizzleSchema, config) => {
   return builder.build();
 };
 export {
+  withRowSecurity,
+  restricted,
+  readOnly,
+  permissive,
+  mergeHooks,
   generateTypes,
   generateSDL,
   generateEntityDefs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drizzle-graphql-suite/schema",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "GraphQL schema builder with CRUD operations, relation filtering, and hooks from Drizzle ORM",
   "license": "MIT",
   "author": "https://github.com/dmythro",

package/permissions.d.ts

@@ -0,0 +1,25 @@
+import type { GraphQLFieldConfig } from 'graphql';
+import type { BuildSchemaConfig, PermissionConfig, TableAccess } from './types';
+export declare const readOnly: () => TableAccess;
+export declare const permissive: (id: string, tables?: Record<string, boolean | TableAccess>) => PermissionConfig;
+export declare const restricted: (id: string, tables?: Record<string, boolean | TableAccess>) => PermissionConfig;
+type MergeResult = {
+    config: BuildSchemaConfig;
+    /** Tables that need individual mutation entry points filtered after build */
+    mutationFilter: Record<string, {
+        insert: boolean;
+        update: boolean;
+        delete: boolean;
+    }>;
+};
+/**
+ * Converts a PermissionConfig into BuildSchemaConfig overrides.
+ * Returns the merged config + a map of tables needing post-build mutation filtering.
+ */
+export declare function mergePermissionsIntoConfig(baseConfig: BuildSchemaConfig, permissions: PermissionConfig, allTableNames: string[]): MergeResult;
+/**
+ * Removes disallowed mutation entry points from the mutations record.
+ * Mutates and returns the same record.
+ */
+export declare function postFilterMutations(mutations: Record<string, GraphQLFieldConfig<any, any>>, mutationFilter: MergeResult['mutationFilter']): void;
+export {};

package/row-security.d.ts

@@ -0,0 +1,21 @@
+import type { HooksConfig } from './types';
+type RowSecurityRule = (context: any) => Record<string, unknown>;
+/**
+ * Generates a HooksConfig that injects WHERE clauses from row-level security rules.
+ * Rules are applied as `before` hooks on query, querySingle, count, update, and delete operations.
+ *
+ * ```ts
+ * const hooks = withRowSecurity({
+ *   posts: (context) => ({ authorId: { eq: context.user.id } }),
+ * })
+ * ```
+ */
+export declare function withRowSecurity(rules: Record<string, RowSecurityRule>): HooksConfig;
+/**
+ * Deep-merges multiple HooksConfig objects.
+ * - `before` hooks are chained: each runs sequentially, passing the modified args forward.
+ * - `after` hooks are chained: each runs sequentially, passing the modified result forward.
+ * - `resolve` hooks: last one wins (cannot be composed).
+ */
+export declare function mergeHooks(...configs: (HooksConfig | undefined)[]): HooksConfig;
+export {};

package/schema-builder.d.ts

@@ -1,6 +1,6 @@
 import { type PgDatabase } from 'drizzle-orm/pg-core';
 import { GraphQLSchema } from 'graphql';
-import type { BuildSchemaConfig, GeneratedEntities } from './types';
+import type { BuildSchemaConfig, GeneratedEntities, PermissionConfig } from './types';
 export declare class SchemaBuilder {
     private db;
     private tables;
@@ -13,6 +13,7 @@ export declare class SchemaBuilder {
     private suffixes;
     private limitRelationDepth;
     private limitSelfRelationDepth;
+    private allTableNames;
     private excludedTables;
     private tableOperations;
     private pruneRelations;
@@ -27,6 +28,8 @@ export declare class SchemaBuilder {
     build(): {
         schema: GraphQLSchema;
         entities: GeneratedEntities;
+        withPermissions: (permissions: PermissionConfig) => GraphQLSchema;
+        clearPermissionCache: (id?: string) => void;
     };
     private logDebugInfo;
     private extractTables;

package/types.d.ts

@@ -39,6 +39,17 @@ export type TableHookConfig = {
 export type HooksConfig = {
     [tableName: string]: TableHookConfig;
 };
+export type TableAccess = {
+    query?: boolean;
+    insert?: boolean;
+    update?: boolean;
+    delete?: boolean;
+};
+export type PermissionConfig = {
+    id: string;
+    mode: 'permissive' | 'restricted';
+    tables?: Record<string, boolean | TableAccess>;
+};
 export type TableOperations = {
     /** Generate query operations (list, single, count). @default true */
     queries?: boolean;