@drizzle-graphql-suite/schema 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Annexare Studio
+
+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

@@ -0,0 +1,348 @@
+# @drizzle-graphql-suite/schema
+
+Auto-generates a complete GraphQL schema with CRUD operations, relation-level filtering, and hooks from Drizzle PostgreSQL schemas.
+
+## Motivation
+
+Inspired by [`drizzle-graphql`](https://github.com/drizzle-team/drizzle-graphql), this package is a purpose-built replacement focused on PostgreSQL. Key improvements:
+
+- **Relation-level filtering** with EXISTS subqueries (`some`/`every`/`none` quantifiers)
+- **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)
+- **Code generation** — `generateSDL`, `generateTypes`, `generateEntityDefs`
+- **Architecture** — TypeScript source, PostgreSQL-only, `SchemaBuilder` class, type caching, lazy thunks for circular relations
+- **Bug fixes** — relation filter join conditions (Drizzle v0.44+), operator map replacements, `catch (e: unknown)` narrowing
+
+## API Reference
+
+### `buildSchema(db, config?)`
+
+Builds a complete `GraphQLSchema` with all CRUD operations from a Drizzle database instance. Returns `{ schema, entities }`.
+
+```ts
+import { buildSchema } from 'drizzle-graphql-suite/schema'
+import { createYoga } from 'graphql-yoga'
+import { db } from './db'
+
+const { schema, entities } = buildSchema(db, {
+  limitRelationDepth: 3,
+  tables: { exclude: ['session'] },
+})
+
+const yoga = createYoga({ schema })
+```
+
+### `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.
+
+```ts
+import { buildEntities } from 'drizzle-graphql-suite/schema'
+
+const entities = buildEntities(db, { mutations: false })
+// entities.queries, entities.mutations, entities.inputs, entities.types
+```
+
+### `buildSchemaFromDrizzle(drizzleSchema, config?)`
+
+Builds a schema directly from Drizzle schema exports — no database connection or `.env` required. Resolvers are stubs. Intended for schema introspection and code generation.
+
+```ts
+import { buildSchemaFromDrizzle } from 'drizzle-graphql-suite/schema'
+import * as schema from './db/schema'
+
+const { schema: graphqlSchema } = buildSchemaFromDrizzle(schema)
+```
+
+## Configuration
+
+`BuildSchemaConfig` controls all aspects of schema generation:
+
+### `mutations`
+
+Enable or disable mutation generation globally.
+
+- **Type**: `boolean`
+- **Default**: `true`
+
+### `limitRelationDepth`
+
+Maximum depth of nested relation fields on queries. Set to `0` to omit relations, `undefined` for no limit.
+
+- **Type**: `number | undefined`
+- **Default**: `3`
+
+### `limitSelfRelationDepth`
+
+Maximum occurrences of the same table via direct self-relations (e.g., `asset.template → asset`). At `1`, self-relation fields are omitted entirely. At `2`, one level of expansion is allowed. Cross-table paths that revisit a table reset the counter and use `limitRelationDepth` instead.
+
+- **Type**: `number`
+- **Default**: `1`
+
+### `suffixes`
+
+Customize query field name suffixes for list and single queries.
+
+- **Type**: `{ list?: string; single?: string }`
+- **Default**: `{ list: '', single: 'Single' }`
+
+### `tables`
+
+Per-table schema control:
+
+```ts
+{
+  tables: {
+    // Remove tables entirely (relations to them are silently skipped)
+    exclude: ['session', 'verification'],
+    // Per-table operation overrides
+    config: {
+      auditLog: { queries: true, mutations: false },
+      user: { mutations: false },
+    },
+  },
+}
+```
+
+- `exclude` — `string[]` — tables removed from the schema entirely
+- `config` — `Record<string, TableOperations>` — per-table `queries` and `mutations` booleans
+
+### `pruneRelations`
+
+Fine-grained per-relation pruning. Keys are `tableName.relationName`:
+
+```ts
+{
+  pruneRelations: {
+    // Omit this relation field entirely
+    'asset.childAssets': false,
+    // Expand with scalar columns only (no nested relations)
+    'user.posts': 'leaf',
+    // Expand with only the listed child relations
+    'post.comments': { only: ['author'] },
+  },
+}
+```
+
+- `false` — relation field omitted entirely from parent type
+- `'leaf'` — relation expands with scalar columns only
+- `{ only: string[] }` — relation expands with only the listed child relation fields
+
+### `hooks`
+
+Per-table, per-operation hooks. See [Hooks System](#hooks-system).
+
+### `debug`
+
+Enable diagnostic logging for schema size and relation tree.
+
+- **Type**: `boolean | { schemaSize?: boolean; relationTree?: boolean }`
+- **Default**: `undefined`
+
+## Hooks System
+
+Hooks intercept operations for auth, validation, audit logging, or custom resolution.
+
+### Hook Types
+
+Each operation supports either **before/after** hooks or a **resolve** hook (not both):
+
+| Hook | Timing | Use Case |
+|------|--------|----------|
+| `before` | Before default resolver | Auth checks, argument transformation, pass data to `after` |
+| `after` | After default resolver | Audit logging, result transformation |
+| `resolve` | Replaces default resolver | Full control, custom data sources |
+
+### Operations
+
+| Operation | Type | Description |
+|-----------|------|-------------|
+| `query` | Read | List query |
+| `querySingle` | Read | Single record query |
+| `count` | Read | Count query |
+| `insert` | Write | Batch insert |
+| `insertSingle` | Write | Single record insert |
+| `update` | Write | Update mutation |
+| `delete` | Write | Delete mutation |
+
+### Example
+
+```ts
+buildSchema(db, {
+  hooks: {
+    user: {
+      query: {
+        before: async ({ args, context }) => {
+          if (!context.user) throw new Error('Unauthorized')
+          // Optionally modify args or pass data to after hook
+          return { args, data: { startTime: Date.now() } }
+        },
+        after: async ({ result, beforeData }) => {
+          console.log(`Query took ${Date.now() - beforeData.startTime}ms`)
+          return result
+        },
+      },
+      delete: {
+        resolve: async ({ args, context, defaultResolve }) => {
+          // Soft delete instead of hard delete
+          return defaultResolve({ ...args, set: { deletedAt: new Date() } })
+        },
+      },
+    },
+  },
+})
+```
+
+## Relation Filtering
+
+Filter by related rows using EXISTS subqueries with `some`, `every`, and `none` quantifiers.
+
+```graphql
+query {
+  users(where: {
+    posts: {
+      some: { published: { eq: true } }
+      none: { flagged: { eq: true } }
+    }
+  }) {
+    id
+    name
+    posts {
+      title
+    }
+  }
+}
+```
+
+- **`some`** — at least one related row matches
+- **`every`** — all related rows match
+- **`none`** — no related rows match
+
+For one-to-one relations, filters apply directly (no quantifiers needed):
+
+```graphql
+query {
+  posts(where: {
+    author: { role: { eq: "admin" } }
+  }) {
+    title
+  }
+}
+```
+
+## Generated Operations
+
+| Pattern | Example (`user` table) | Type |
+|---------|----------------------|------|
+| `{table}` | `user` | Single query |
+| `{table}{listSuffix}` | `users` | List query |
+| `{table}Count` | `userCount` | Count query |
+| `insertInto{Table}` | `insertIntoUser` | Batch insert |
+| `insertInto{Table}Single` | `insertIntoUserSingle` | Single insert |
+| `update{Table}` | `updateUser` | Update |
+| `deleteFrom{Table}` | `deleteFromUser` | Delete |
+
+## Column Type Mapping
+
+| Drizzle Type | GraphQL Type |
+|-------------|--------------|
+| `boolean` | `Boolean` |
+| `text`, `varchar`, `char` | `String` |
+| `integer`, `smallint`, `serial`, `smallserial`, `bigserial` | `Int` |
+| `real`, `doublePrecision`, `numeric` | `Float` |
+| `bigint` | `String` |
+| `date`, `timestamp`, `time` | `String` |
+| `json`, `jsonb` | `JSON` (custom scalar) |
+| `bytea` | `[Int!]` |
+| `vector` | `[Float!]` |
+| `geometry` | `PgGeometryObject { x, y }` |
+| `enum` | Generated `GraphQLEnumType` |
+
+## Code Generation
+
+Three code generation functions for producing static artifacts from a GraphQL schema:
+
+### `generateSDL(schema)`
+
+Generates the GraphQL Schema Definition Language string.
+
+```ts
+import { buildSchemaFromDrizzle, generateSDL } from 'drizzle-graphql-suite/schema'
+import * as drizzleSchema from './db/schema'
+import { writeFileSync } from 'node:fs'
+
+const { schema } = buildSchemaFromDrizzle(drizzleSchema)
+writeFileSync('schema.graphql', generateSDL(schema))
+```
+
+### `generateTypes(schema, options?)`
+
+Generates TypeScript types: wire format types (Date → string), filter types, insert/update input types, and orderBy types. Optionally imports Drizzle types for precise wire format derivation.
+
+```ts
+import { generateTypes } from 'drizzle-graphql-suite/schema'
+
+const types = generateTypes(schema, {
+  drizzle: {
+    importPath: '@myapp/db/schema',
+    typeNames: { userProfile: 'UserProfile' },
+  },
+})
+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.
+
+```ts
+import { generateEntityDefs } from 'drizzle-graphql-suite/schema'
+
+const entityDefs = generateEntityDefs(schema, {
+  drizzle: { importPath: '@myapp/db/schema' },
+})
+writeFileSync('generated/entity-defs.ts', entityDefs)
+```
+
+### Full Codegen Script
+
+```ts
+import { buildSchemaFromDrizzle, generateSDL, generateTypes, generateEntityDefs } from 'drizzle-graphql-suite/schema'
+import * as drizzleSchema from './db/schema'
+import { writeFileSync, mkdirSync } from 'node:fs'
+
+const { schema } = buildSchemaFromDrizzle(drizzleSchema)
+
+mkdirSync('generated', { recursive: true })
+writeFileSync('generated/schema.graphql', generateSDL(schema))
+writeFileSync('generated/types.ts', generateTypes(schema, {
+  drizzle: { importPath: '@myapp/db/schema' },
+}))
+writeFileSync('generated/entity-defs.ts', generateEntityDefs(schema, {
+  drizzle: { importPath: '@myapp/db/schema' },
+}))
+```
+
+## `GeneratedEntities` Type
+
+The return type from `buildEntities()` and `buildSchema()`:
+
+```ts
+type GeneratedEntities = {
+  queries: Record<string, GraphQLFieldConfig<any, any>>
+  mutations: Record<string, GraphQLFieldConfig<any, any>>
+  inputs: Record<string, GraphQLInputObjectType>
+  types: Record<string, GraphQLObjectType>
+}
+```
+
+- **`queries`** — all generated query field configs, spreadable into a parent schema
+- **`mutations`** — all generated mutation field configs
+- **`inputs`** — filter, insert, update, and orderBy input types by name
+- **`types`** — output object types by table name

package/adapters/pg.d.ts

@@ -0,0 +1,10 @@
+import { type Column, type SQL, type Table } from 'drizzle-orm';
+import { type PgDatabase } from 'drizzle-orm/pg-core';
+import type { DbAdapter } from './types';
+export declare class PgAdapter implements DbAdapter {
+    readonly supportsReturning = true;
+    isTable(value: unknown): boolean;
+    executeInsert(db: PgDatabase<any, any, any>, table: Table, values: Record<string, any>[], returningColumns?: Record<string, Column>): Promise<any[]>;
+    executeUpdate(db: PgDatabase<any, any, any>, table: Table, set: Record<string, any>, where: SQL | undefined, returningColumns?: Record<string, Column>): Promise<any[]>;
+    executeDelete(db: PgDatabase<any, any, any>, table: Table, where: SQL | undefined, returningColumns?: Record<string, Column>): Promise<any[]>;
+}

package/adapters/types.d.ts

@@ -0,0 +1,11 @@
+import type { Column, SQL, Table } from 'drizzle-orm';
+import type { PgDatabase } from 'drizzle-orm/pg-core';
+export interface DbAdapter {
+    /** Identifies tables in the schema (e.g., is(value, PgTable)) */
+    isTable(value: unknown): boolean;
+    /** Whether mutations can return data (PG: yes via RETURNING, MySQL: no) */
+    readonly supportsReturning: boolean;
+    executeInsert(db: PgDatabase<any, any, any>, table: Table, values: Record<string, any>[], returningColumns?: Record<string, Column>): Promise<any[]>;
+    executeUpdate(db: PgDatabase<any, any, any>, table: Table, set: Record<string, any>, where: SQL | undefined, returningColumns?: Record<string, Column>): Promise<any[]>;
+    executeDelete(db: PgDatabase<any, any, any>, table: Table, where: SQL | undefined, returningColumns?: Record<string, Column>): Promise<any[]>;
+}

package/case-ops.d.ts

@@ -0,0 +1,2 @@
+export declare const uncapitalize: <T extends string>(input: T) => Uncapitalize<T>;
+export declare const capitalize: <T extends string>(input: T) => Capitalize<T>;

package/codegen.d.ts

@@ -0,0 +1,12 @@
+import type { GraphQLSchema } from 'graphql';
+export type CodegenOptions = {
+    drizzle?: {
+        /** Import path for Drizzle schema types (e.g. '@ir/core/db/schema') */
+        importPath: string;
+        /** Override mapping: Drizzle table name → export type name (e.g. { overrideToAsset: 'OverrideAsset' }) */
+        typeNames?: Record<string, string>;
+    };
+};
+export declare function generateSDL(schema: GraphQLSchema): string;
+export declare function generateTypes(schema: GraphQLSchema, options?: CodegenOptions): string;
+export declare function generateEntityDefs(schema: GraphQLSchema, options?: CodegenOptions): string;

package/data-mappers.d.ts

@@ -0,0 +1,12 @@
+import type { Relation } from 'drizzle-orm';
+import { type Column, type Table } from 'drizzle-orm';
+export type TableNamedRelations = {
+    relation: Relation;
+    targetTableName: string;
+};
+export declare const remapToGraphQLCore: (key: string, value: any, tableName: string, column: Column, relationMap?: Record<string, Record<string, TableNamedRelations>>) => any;
+export declare const remapToGraphQLSingleOutput: (queryOutput: Record<string, any>, tableName: string, table: Table, relationMap?: Record<string, Record<string, TableNamedRelations>>) => Record<string, any>;
+export declare const remapToGraphQLArrayOutput: (queryOutput: Record<string, any>[], tableName: string, table: Table, relationMap?: Record<string, Record<string, TableNamedRelations>>) => Record<string, any>[];
+export declare const remapFromGraphQLCore: (value: any, column: Column, columnName: string) => any;
+export declare const remapFromGraphQLSingleInput: (queryInput: Record<string, any>, table: Table) => Record<string, any>;
+export declare const remapFromGraphQLArrayInput: (queryInput: Record<string, any>[], table: Table) => Record<string, any>[];

package/graphql/scalars.d.ts

@@ -0,0 +1,2 @@
+import { GraphQLScalarType } from 'graphql';
+export declare const GraphQLJSON: GraphQLScalarType<any, unknown>;

package/graphql/type-builder.d.ts

@@ -0,0 +1,7 @@
+import type { Column } from 'drizzle-orm';
+import { GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull, GraphQLObjectType, type GraphQLScalarType } from 'graphql';
+export type ConvertedColumn<TIsInput extends boolean = false> = {
+    type: GraphQLScalarType | GraphQLEnumType | GraphQLNonNull<GraphQLScalarType> | GraphQLNonNull<GraphQLEnumType> | GraphQLList<GraphQLScalarType> | GraphQLList<GraphQLNonNull<GraphQLScalarType>> | GraphQLNonNull<GraphQLList<GraphQLScalarType>> | GraphQLNonNull<GraphQLList<GraphQLNonNull<GraphQLScalarType>>> | (TIsInput extends true ? GraphQLInputObjectType | GraphQLNonNull<GraphQLInputObjectType> : GraphQLObjectType | GraphQLNonNull<GraphQLObjectType>);
+    description?: string;
+};
+export declare const drizzleColumnToGraphQLType: <TColumn extends Column, TIsInput extends boolean>(column: TColumn, columnName: string, tableName: string, forceNullable?: boolean, defaultIsNullable?: boolean, isInput?: TIsInput) => ConvertedColumn<TIsInput>;

package/index.d.ts

@@ -0,0 +1,26 @@
+import type { PgDatabase } from 'drizzle-orm/pg-core';
+import type { GraphQLSchema } from 'graphql';
+import type { BuildSchemaConfig, GeneratedEntities } from './types';
+export { GraphQLJSON } from './graphql/scalars';
+export declare const buildSchema: (db: PgDatabase<any, any, any>, config?: BuildSchemaConfig) => {
+    schema: GraphQLSchema;
+    entities: GeneratedEntities;
+};
+export declare const buildEntities: (db: PgDatabase<any, any, any>, config?: BuildSchemaConfig) => GeneratedEntities;
+/**
+ * Build a GraphQL schema directly from Drizzle schema exports — no database
+ * connection or `.env` required. Creates a lightweight mock db instance that
+ * satisfies `SchemaBuilder`'s metadata needs (table definitions, relations,
+ * table name mapping) without an actual connection.
+ *
+ * Resolver functions on the returned entities are stubs — this is intended
+ * for schema introspection and code generation, not query execution.
+ */
+export declare const buildSchemaFromDrizzle: (drizzleSchema: Record<string, unknown>, config?: BuildSchemaConfig) => {
+    schema: GraphQLSchema;
+    entities: GeneratedEntities;
+};
+export type { CodegenOptions } from './codegen';
+export { generateEntityDefs, generateSDL, generateTypes } from './codegen';
+export { SchemaBuilder } from './schema-builder';
+export * from './types';