drizzle-graphql-suite 0.5.0

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

@@ -0,0 +1,19 @@
+import { type EntityClient } from './entity';
+import type { InferEntityDefs } from './infer';
+import { type ClientSchemaConfig } from './schema-builder';
+import type { AnyEntityDefs, ClientConfig, SchemaDescriptor } from './types';
+export declare class GraphQLClient<TSchema extends SchemaDescriptor, TDefs extends AnyEntityDefs = AnyEntityDefs> {
+    private url;
+    private schema;
+    private headers?;
+    constructor(config: ClientConfig<TSchema>);
+    entity<TEntityName extends string & keyof TSchema & keyof TDefs>(entityName: TEntityName): EntityClient<TDefs, TDefs[TEntityName]>;
+    execute(query: string, variables?: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export type DrizzleClientConfig<TSchema extends Record<string, unknown>, TConfig extends ClientSchemaConfig> = {
+    schema: TSchema;
+    config: TConfig;
+    url: string | (() => string);
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+};
+export declare function createDrizzleClient<TSchema extends Record<string, unknown>, const TConfig extends ClientSchemaConfig>(options: DrizzleClientConfig<TSchema, TConfig>): GraphQLClient<SchemaDescriptor, InferEntityDefs<TSchema, TConfig>>;

package/packages/client/dist/entity.d.ts

@@ -0,0 +1,57 @@
+import type { AnyEntityDefs, EntityDef, EntityDescriptor, InferResult, SchemaDescriptor } from './types';
+export type EntityClient<TDefs extends AnyEntityDefs, TEntity extends EntityDef> = {
+    query<S extends Record<string, unknown>>(params: {
+        select: S;
+        where?: TEntity extends {
+            filters: infer F;
+        } ? F : never;
+        limit?: number;
+        offset?: number;
+        orderBy?: TEntity extends {
+            orderBy: infer O;
+        } ? O : never;
+    }): Promise<InferResult<TDefs, TEntity, S>[]>;
+    querySingle<S extends Record<string, unknown>>(params: {
+        select: S;
+        where?: TEntity extends {
+            filters: infer F;
+        } ? F : never;
+        offset?: number;
+        orderBy?: TEntity extends {
+            orderBy: infer O;
+        } ? O : never;
+    }): Promise<InferResult<TDefs, TEntity, S> | null>;
+    count(params?: {
+        where?: TEntity extends {
+            filters: infer F;
+        } ? F : never;
+    }): Promise<number>;
+    insert<S extends Record<string, unknown>>(params: {
+        values: TEntity extends {
+            insertInput: infer I;
+        } ? I[] : never;
+        returning?: S;
+    }): Promise<InferResult<TDefs, TEntity, S>[]>;
+    insertSingle<S extends Record<string, unknown>>(params: {
+        values: TEntity extends {
+            insertInput: infer I;
+        } ? I : never;
+        returning?: S;
+    }): Promise<InferResult<TDefs, TEntity, S> | null>;
+    update<S extends Record<string, unknown>>(params: {
+        set: TEntity extends {
+            updateInput: infer U;
+        } ? U : never;
+        where?: TEntity extends {
+            filters: infer F;
+        } ? F : never;
+        returning?: S;
+    }): Promise<InferResult<TDefs, TEntity, S>[]>;
+    delete<S extends Record<string, unknown>>(params: {
+        where?: TEntity extends {
+            filters: infer F;
+        } ? F : never;
+        returning?: S;
+    }): Promise<InferResult<TDefs, TEntity, S>[]>;
+};
+export declare function createEntityClient<TDefs extends AnyEntityDefs, TEntity extends EntityDef>(entityName: string, entityDef: EntityDescriptor, schema: SchemaDescriptor, executeGraphQL: (query: string, variables: Record<string, unknown>) => Promise<Record<string, unknown>>): EntityClient<TDefs, TEntity>;

package/packages/client/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export type GraphQLErrorLocation = {
+    line: number;
+    column: number;
+};
+export type GraphQLErrorEntry = {
+    message: string;
+    locations?: GraphQLErrorLocation[];
+    path?: (string | number)[];
+    extensions?: Record<string, unknown>;
+};
+export declare class GraphQLClientError extends Error {
+    readonly errors: GraphQLErrorEntry[];
+    readonly status: number;
+    constructor(errors: GraphQLErrorEntry[], status?: number);
+}
+export declare class NetworkError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}

package/packages/client/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { GraphQLClient } from './client';
+import type { AnyEntityDefs, ClientConfig, SchemaDescriptor } from './types';
+export declare function createClient<TSchema extends SchemaDescriptor, TDefs extends AnyEntityDefs = AnyEntityDefs>(config: ClientConfig<TSchema>): GraphQLClient<TSchema, TDefs>;
+export type { DrizzleClientConfig } from './client';
+export { createDrizzleClient, GraphQLClient } from './client';
+export type { EntityClient } from './entity';
+export { GraphQLClientError, NetworkError } from './errors';
+export type { InferEntityDefs } from './infer';
+export type { ClientSchemaConfig } from './schema-builder';
+export { buildSchemaDescriptor } from './schema-builder';
+export type { AnyEntityDefs, ClientConfig, EntityDef, EntityDescriptor, InferResult, SchemaDescriptor, SelectInput, } from './types';