drizzle-graphql-suite 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,126 @@
+# drizzle-graphql-suite
+
+Auto-generated GraphQL CRUD, type-safe clients, and React Query hooks from Drizzle PostgreSQL schemas.
+
+## Overview
+
+`drizzle-graphql-suite` is a three-layer toolkit that turns your Drizzle ORM schema into a fully working GraphQL API with end-to-end type safety:
+
+1. **Schema builder** — generates a complete GraphQL schema with CRUD operations, relation-level filtering, and per-operation hooks from Drizzle table definitions.
+2. **Client** — provides a type-safe GraphQL client that infers query/mutation types directly from your Drizzle schema, with full TypeScript support for filters, relations, and results.
+3. **React Query hooks** — wraps the client in TanStack React Query hooks for caching, pagination, and mutations with automatic cache invalidation.
+
+Inspired by [`drizzle-graphql`](https://github.com/drizzle-team/drizzle-graphql), rewritten with significant improvements including relation-level filtering, hooks, count queries, configurable schema generation, and code generation.
+
+## Packages
+
+| Subpath | Package | Description |
+|---------|---------|-------------|
+| `drizzle-graphql-suite/schema` | [`@drizzle-graphql-suite/schema`](packages/schema/README.md) | GraphQL schema builder with CRUD, filtering, hooks, and codegen |
+| `drizzle-graphql-suite/client` | [`@drizzle-graphql-suite/client`](packages/client/README.md) | Type-safe GraphQL client with full Drizzle type inference |
+| `drizzle-graphql-suite/query` | [`@drizzle-graphql-suite/query`](packages/query/README.md) | TanStack React Query hooks for the client |
+
+## Installation
+
+```bash
+bun add drizzle-graphql-suite
+```
+
+```bash
+npm install drizzle-graphql-suite
+```
+
+## Peer Dependencies
+
+Each subpath import has its own peer dependency requirements:
+
+| Subpath | Peer Dependencies |
+|---------|-------------------|
+| `./schema` | `drizzle-orm` >=0.44.0, `graphql` >=16.3.0 |
+| `./client` | `drizzle-orm` >=0.44.0 |
+| `./query` | `react` >=18.0.0, `@tanstack/react-query` >=5.0.0 |
+
+## Quick Start
+
+### 1. Server — Build GraphQL Schema
+
+```ts
+import { buildSchema } from 'drizzle-graphql-suite/schema'
+import { createYoga } from 'graphql-yoga'
+import { createServer } from 'node:http'
+import { db } from './db'
+
+const { schema } = buildSchema(db, {
+  tables: { exclude: ['session', 'verification'] },
+  hooks: {
+    user: {
+      query: {
+        before: async ({ context }) => {
+          if (!context.user) throw new Error('Unauthorized')
+        },
+      },
+    },
+  },
+})
+
+const yoga = createYoga({ schema })
+const server = createServer(yoga)
+server.listen(4000)
+```
+
+### 2. Client — Type-Safe Queries
+
+```ts
+import { createDrizzleClient } from 'drizzle-graphql-suite/client'
+import * as schema from './db/schema'
+
+const client = createDrizzleClient({
+  schema,
+  config: { suffixes: { list: 's' } },
+  url: '/api/graphql',
+})
+
+const users = await client.entity('user').query({
+  select: {
+    id: true,
+    name: true,
+    posts: { id: true, title: true },
+  },
+  where: { name: { ilike: '%john%' } },
+  limit: 10,
+})
+```
+
+### 3. React — Query Hooks
+
+```tsx
+import { GraphQLProvider, useEntity, useEntityList } from 'drizzle-graphql-suite/query'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <GraphQLProvider client={graphqlClient}>
+        <UserList />
+      </GraphQLProvider>
+    </QueryClientProvider>
+  )
+}
+
+function UserList() {
+  const user = useEntity('user')
+  const { data, isLoading } = useEntityList(user, {
+    select: { id: true, name: true, email: true },
+    limit: 20,
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  return <ul>{data?.map((u) => <li key={u.id}>{u.name}</li>)}</ul>
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "drizzle-graphql-suite",
+  "version": "0.5.0",
+  "description": "Auto-generated GraphQL CRUD, type-safe clients, and React Query hooks from Drizzle PostgreSQL schemas",
+  "author": "https://github.com/dmythro",
+  "license": "MIT",
+  "keywords": [
+    "drizzle",
+    "graphql",
+    "orm",
+    "postgresql",
+    "postgres",
+    "typescript",
+    "crud",
+    "react",
+    "react-query",
+    "tanstack",
+    "type-safe",
+    "schema",
+    "api"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/annexare/drizzle-graphql-suite.git"
+  },
+  "homepage": "https://github.com/annexare/drizzle-graphql-suite#readme",
+  "bugs": {
+    "url": "https://github.com/annexare/drizzle-graphql-suite/issues"
+  },
+  "type": "module",
+  "files": [
+    "packages/schema/dist",
+    "packages/client/dist",
+    "packages/query/dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./schema": {
+      "import": "./packages/schema/dist/index.js",
+      "types": "./packages/schema/dist/index.d.ts"
+    },
+    "./client": {
+      "import": "./packages/client/dist/index.js",
+      "types": "./packages/client/dist/index.d.ts"
+    },
+    "./query": {
+      "import": "./packages/query/dist/index.js",
+      "types": "./packages/query/dist/index.d.ts"
+    }
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "build": "bun run --filter '@drizzle-graphql-suite/schema' --filter '@drizzle-graphql-suite/client' build && bun run --filter '@drizzle-graphql-suite/query' build",
+    "check-types": "bun run --filter '*' check-types",
+    "test": "bun run --filter '*' test",
+    "lint": "bunx @biomejs/biome check --write .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "check": "bun run check-types && bun run lint:check && bun run test",
+    "ci": "bun run check-types && bun run lint:check && bun run test",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "prepare-publish": "bun run scripts/prepare-publish.ts",
+    "release": "bun run build && bun run prepare-publish && changeset publish"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.4",
+    "@changesets/cli": "2.29.8",
+    "typescript": "5.9.3"
+  }
+}

package/packages/client/README.md

@@ -0,0 +1,236 @@
+# @drizzle-graphql-suite/client
+
+Type-safe GraphQL client auto-generated from Drizzle schemas, with full TypeScript inference for queries, mutations, filters, and relations.
+
+## Quick Start
+
+### From Drizzle Schema (recommended)
+
+Use `createDrizzleClient` to create a client that infers all types directly from your Drizzle schema module — no code generation needed.
+
+```ts
+import { createDrizzleClient } from 'drizzle-graphql-suite/client'
+import * as schema from './db/schema'
+
+const client = createDrizzleClient({
+  schema,
+  config: {
+    suffixes: { list: 's' },
+    tables: { exclude: ['session', 'verification'] },
+  },
+  url: '/api/graphql',
+  headers: { Authorization: 'Bearer ...' },
+})
+```
+
+### From Schema Descriptor
+
+Use `createClient` with a codegen-generated schema descriptor when you want to decouple from the Drizzle schema at runtime (e.g., in a frontend bundle that shouldn't import server-side schema files).
+
+```ts
+import { createClient } from 'drizzle-graphql-suite/client'
+import { schema, type EntityDefs } from './generated/entity-defs'
+
+const client = createClient<typeof schema, EntityDefs>({
+  schema,
+  url: '/api/graphql',
+})
+```
+
+## EntityClient API
+
+Access a typed entity client via `client.entity('name')`:
+
+```ts
+const user = client.entity('user')
+```
+
+Each entity client provides the following methods:
+
+### `query(params)`
+
+Fetch a list of records with optional filtering, pagination, and ordering. Returns `T[]`.
+
+```ts
+const users = await user.query({
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    posts: {
+      id: true,
+      title: true,
+      comments: { id: true, body: true },
+    },
+  },
+  where: { email: { ilike: '%@example.com' } },
+  orderBy: { name: { direction: 'asc', priority: 1 } },
+  limit: 20,
+  offset: 0,
+})
+```
+
+### `querySingle(params)`
+
+Fetch a single record. Returns `T | null`.
+
+```ts
+const found = await user.querySingle({
+  select: { id: true, name: true, email: true },
+  where: { id: { eq: 'some-uuid' } },
+})
+```
+
+### `count(params?)`
+
+Count matching records. Returns `number`.
+
+```ts
+const total = await user.count({
+  where: { role: { eq: 'admin' } },
+})
+```
+
+### `insert(params)`
+
+Insert multiple records. Returns `T[]` of inserted rows.
+
+```ts
+const created = await user.insert({
+  values: [
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' },
+  ],
+  returning: { id: true, name: true },
+})
+```
+
+### `insertSingle(params)`
+
+Insert a single record. Returns `T | null`.
+
+```ts
+const created = await user.insertSingle({
+  values: { name: 'Alice', email: 'alice@example.com' },
+  returning: { id: true, name: true },
+})
+```
+
+### `update(params)`
+
+Update records matching a filter. Returns `T[]` of updated rows.
+
+```ts
+const updated = await user.update({
+  set: { role: 'admin' },
+  where: { id: { eq: 'some-uuid' } },
+  returning: { id: true, role: true },
+})
+```
+
+### `delete(params)`
+
+Delete records matching a filter. Returns `T[]` of deleted rows.
+
+```ts
+const deleted = await user.delete({
+  where: { deletedAt: { isNotNull: true } },
+  returning: { id: true },
+})
+```
+
+## Schema Descriptor
+
+A `SchemaDescriptor` is a runtime object mapping entity names to their operation names, fields, and relations. It tells the client how to build GraphQL queries.
+
+### `buildSchemaDescriptor(schema, config?)`
+
+Builds a `SchemaDescriptor` from a Drizzle schema module. This is called internally by `createDrizzleClient`, but can be used directly if you need the descriptor.
+
+```ts
+import { buildSchemaDescriptor } from 'drizzle-graphql-suite/client'
+import * as schema from './db/schema'
+
+const descriptor = buildSchemaDescriptor(schema, {
+  suffixes: { list: 's' },
+  tables: { exclude: ['session'] },
+  pruneRelations: { 'user.sessions': false },
+})
+```
+
+Config options mirror the schema package: `mutations`, `suffixes`, `tables.exclude`, and `pruneRelations`.
+
+## Type Inference
+
+The client provides end-to-end type inference from Drizzle schema to query results:
+
+### `InferEntityDefs<TSchema, TConfig>`
+
+Infers the complete entity type definitions from a Drizzle schema module, including fields (with Date → string wire conversion), relations, filters, insert inputs, update inputs, and orderBy types.
+
+```ts
+import type { InferEntityDefs } from 'drizzle-graphql-suite/client'
+import type * as schema from './db/schema'
+
+type MyEntityDefs = InferEntityDefs<typeof schema, { tables: { exclude: ['session'] } }>
+```
+
+### `InferResult<TDefs, TEntity, TSelect>`
+
+Infers the return type of a query from the `select` object. Only selected scalar fields and relations are included in the result type. Relations resolve to arrays or `T | null` based on their cardinality.
+
+### `SelectInput<TDefs, TEntity>`
+
+Describes the valid shape of a `select` parameter — `true` for scalar fields, nested objects for relations.
+
+## Dynamic URL and Headers
+
+Both `url` and `headers` support static values or functions (sync or async) that are called per-request:
+
+```ts
+const client = createDrizzleClient({
+  schema,
+  config: {},
+  // Dynamic URL
+  url: () => `${getApiBase()}/graphql`,
+  // Async headers (e.g., refresh token)
+  headers: async () => ({
+    Authorization: `Bearer ${await getAccessToken()}`,
+  }),
+})
+```
+
+## Error Handling
+
+The client throws two error types:
+
+### `GraphQLClientError`
+
+Thrown when the server returns GraphQL errors in the response body.
+
+- **`errors`** — `Array<{ message, locations?, path?, extensions? }>` — individual GraphQL errors
+- **`status`** — HTTP status code (usually `200`)
+- **`message`** — concatenated error messages
+
+### `NetworkError`
+
+Thrown when the HTTP request fails (network error or non-2xx status).
+
+- **`status`** — HTTP status code (`0` for network failures)
+- **`message`** — error description
+
+```ts
+import { GraphQLClientError, NetworkError } from 'drizzle-graphql-suite/client'
+
+try {
+  const users = await client.entity('user').query({
+    select: { id: true, name: true },
+  })
+} catch (e) {
+  if (e instanceof GraphQLClientError) {
+    console.error('GraphQL errors:', e.errors)
+  } else if (e instanceof NetworkError) {
+    console.error('Network error:', e.status, e.message)
+  }
+}
+```

package/packages/client/dist/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.