workers-qb 1.11.1 → 1.12.0

package/README.md

@@ -35,18 +35,18 @@ workers-qb is a lightweight query builder designed specifically for Cloudflare W
 
 ## Supported Databases
 
-- ☁️ [Cloudflare D1](https://workers-qb.massadas.com/databases/cloudflare-d1/)
-- 💾 [Cloudflare Durable Objects](https://workers-qb.massadas.com/databases/cloudflare-do/)
+- ☁️ [Cloudflare D1](https://workers-qb.massadas.com/databases/d1/)
+- 💾 [Cloudflare Durable Objects](https://workers-qb.massadas.com/databases/do/)
 - 🐘 [PostgreSQL (via node-postgres)](https://workers-qb.massadas.com/databases/postgresql/)
-- 🔌 [Bring Your Own Database](https://workers-qb.massadas.com/databases/bring-your-own-database/)
+- 🔌 [Bring Your Own Database](https://workers-qb.massadas.com/databases/byodb/)
 
 ## Features
 
 ### Core Features
 - Zero dependencies
 - Full TypeScript support
+- Schema-aware type inference with autocomplete
 - Database schema migrations
-- Type checking for data reads
 - Lazy row loading
 
 ### Query Operations
@@ -110,6 +110,39 @@ export default {
 }
 ```
 
+### Schema-Aware Type Inference
+
+Define your database schema once and get autocomplete for table names, column names, and automatic result type inference:
+
+```typescript
+import { D1QB } from 'workers-qb'
+
+// Define your schema
+type Schema = {
+  employees: {
+    id: number
+    name: string
+    role: string
+    active: boolean
+  }
+}
+
+// Initialize with schema type
+const qb = new D1QB<Schema>(env.DB)
+
+// Get full autocomplete and type inference
+const employees = await qb.fetchAll({
+  tableName: 'employees',     // Autocomplete: 'employees'
+  fields: ['id', 'name'],     // Autocomplete: 'id' | 'name' | 'role' | 'active'
+  orderBy: { name: 'ASC' },   // Keys autocomplete to column names
+}).execute()
+
+// Result type is automatically inferred as { id: number; name: string }[]
+employees.results?.forEach(emp => {
+  console.log(emp.id, emp.name)  // Fully typed!
+})
+```
+
 ### Cloudflare Durable Objects
 
 ```typescript

package/dist/index.d.mts

@@ -19,6 +19,73 @@ declare enum JoinTypes {
     CROSS = "CROSS"
 }
 
+/**
+ * Schema-aware type utilities for type-safe query building.
+ *
+ * Define your database schema as a type and pass it to the query builder
+ * to get autocomplete for table names, column names, and inferred result types.
+ *
+ * @example
+ * ```typescript
+ * type Schema = {
+ *   users: {
+ *     id: number
+ *     name: string
+ *     email: string
+ *   }
+ *   posts: {
+ *     id: number
+ *     user_id: number
+ *     title: string
+ *   }
+ * }
+ *
+ * const qb = new D1QB<Schema>(env.DB)
+ *
+ * // Now get autocomplete for tableName, fields, orderBy, etc.
+ * const users = await qb.fetchAll({
+ *   tableName: 'users',      // autocomplete: 'users' | 'posts'
+ *   fields: ['id', 'name'],  // autocomplete: 'id' | 'name' | 'email'
+ * }).execute()
+ * ```
+ */
+/**
+ * Base type for database schemas.
+ * A schema is a record of table names to their column types.
+ */
+type TableSchema = Record<string, Record<string, unknown>>;
+/**
+ * Extract table names from a schema.
+ */
+type TableName<S extends TableSchema> = keyof S & string;
+/**
+ * Extract column names for a specific table.
+ */
+type ColumnName<S extends TableSchema, T extends TableName<S>> = keyof S[T] & string;
+/**
+ * Pick specific columns from a table's type.
+ */
+type SelectColumns<S extends TableSchema, T extends TableName<S>, F extends ColumnName<S, T>> = Pick<S[T], F>;
+/**
+ * Type for INSERT data - all columns are optional to allow partial inserts.
+ * In practice, required columns will be enforced by the database.
+ */
+type InsertData<S extends TableSchema, T extends TableName<S>> = Partial<S[T]>;
+/**
+ * Type for UPDATE data - all columns are optional.
+ */
+type UpdateData<S extends TableSchema, T extends TableName<S>> = Partial<S[T]>;
+/**
+ * Helper to check if a schema is empty (for backwards compatibility).
+ * When Schema = {}, we fall back to loose types.
+ */
+type IsEmptySchema<S extends TableSchema> = keyof S extends never ? true : false;
+/**
+ * Conditional type that returns strict types when schema is provided,
+ * or loose types when schema is empty.
+ */
+type SchemaAware<S extends TableSchema, Strict, Loose> = IsEmptySchema<S> extends true ? Loose : Strict;
+
 declare class Raw {
     isRaw: boolean;
     content: any;
@@ -43,24 +110,24 @@ declare function trimQuery(query: string): string;
 interface SelectExecuteOptions {
     lazy?: boolean;
 }
-declare class SelectBuilder<GenericResultWrapper, GenericResult = DefaultReturnObject, IsAsync extends boolean = true> {
+declare class SelectBuilder<Schema extends TableSchema = {}, GenericResultWrapper = unknown, GenericResult = DefaultReturnObject, IsAsync extends boolean = true> {
     _debugger: boolean;
     _options: Partial<SelectAll>;
     _fetchAll: (params: SelectAll) => QueryWithExtra<GenericResultWrapper, any, IsAsync>;
     _fetchOne: (params: SelectOne) => QueryWithExtra<GenericResultWrapper, any, IsAsync>;
     constructor(options: Partial<SelectAll>, fetchAll: (params: SelectAll) => QueryWithExtra<GenericResultWrapper, any, IsAsync>, fetchOne: (params: SelectOne) => QueryWithExtra<GenericResultWrapper, any, IsAsync>);
     setDebugger(state: boolean): void;
-    tableName(tableName: SelectAll['tableName']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    fields(fields: SelectAll['fields']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    where(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    whereIn<T extends string | Array<string>, P extends T extends Array<string> ? Primitive[][] : Primitive[]>(fields: T, values: P): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    join(join: SelectAll['join']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    groupBy(groupBy: SelectAll['groupBy']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    having(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    orderBy(orderBy: SelectAll['orderBy']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    offset(offset: SelectAll['offset']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    limit(limit: SelectAll['limit']): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
-    _parseArray(fieldName: string, option: any, value: any): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
+    tableName(tableName: SelectAll['tableName']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    fields(fields: SelectAll['fields']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    where(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    whereIn<T extends string | Array<string>, P extends T extends Array<string> ? Primitive[][] : Primitive[]>(fields: T, values: P): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    join(join: SelectAll['join']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    groupBy(groupBy: SelectAll['groupBy']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    having(conditions: string | Array<string>, params?: Primitive | Primitive[]): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    orderBy(orderBy: SelectAll['orderBy']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    offset(offset: SelectAll['offset']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    limit(limit: SelectAll['limit']): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
+    _parseArray(fieldName: string, option: any, value: any): SelectBuilder<Schema, GenericResultWrapper, GenericResult, IsAsync>;
     getQueryAll<P extends SelectExecuteOptions = SelectExecuteOptions>(options?: P): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync, P extends {
         lazy: true;
     } ? true : false>, IsAsync>;
@@ -90,7 +157,7 @@ type SimpleMerge<Destination, Source> = {
 } & Source;
 type Merge<Destination, Source> = Simplify<SimpleMerge<PickIndexSignature<Destination>, PickIndexSignature<Source>> & SimpleMerge<OmitIndexSignature<Destination>, OmitIndexSignature<Source>>>;
 
-type Primitive = null | string | number | boolean | bigint | Raw | SelectAll | SelectBuilder<any, any, any>;
+type Primitive = null | string | number | boolean | bigint | ArrayBuffer | Raw | SelectAll | SelectBuilder<any, any, any>;
 type QueryLoggerMeta = {
     duration?: number;
 };
@@ -98,7 +165,7 @@ type QueryBuilderOptions<IsAsync extends boolean = true> = {
     logger?: (query: RawQuery, meta: QueryLoggerMeta) => MaybeAsync<IsAsync, void>;
 };
 type DefaultObject = Record<string, Primitive>;
-type DefaultReturnObject = Record<string, null | string | number | boolean | bigint>;
+type DefaultReturnObject = Record<string, null | string | number | boolean | bigint | ArrayBuffer>;
 type Where = {
     conditions: string | Array<string>;
     params?: Primitive | Primitive[];
@@ -157,7 +224,6 @@ type InsertMultiple = Omit<Insert, 'data' | 'returning'> & {
     returning: string | Array<string>;
 };
 type InsertWithoutReturning = Omit<Insert, 'returning'>;
-type test<I extends Insert = Insert> = I;
 type Update = {
     tableName: string;
     data: DefaultObject;
@@ -230,12 +296,69 @@ type CountResult<GenericResultWrapper> = OneResult<GenericResultWrapper, {
 type AsyncType<T> = Promise<T>;
 type SyncType<T> = T;
 type MaybeAsync<IsAsync extends boolean, T> = IsAsync extends true ? AsyncType<T> : SyncType<T>;
+/**
+ * Schema-aware SELECT parameters.
+ * When a schema is provided, tableName and fields get autocomplete.
+ */
+type TypedSelectOne<S extends TableSchema, T extends TableName<S>, F extends ColumnName<S, T> = ColumnName<S, T>> = {
+    tableName: T;
+    fields?: F[] | F | '*';
+    where?: Where;
+    join?: Join | Array<Join>;
+    groupBy?: ColumnName<S, T> | ColumnName<S, T>[] | string | string[];
+    having?: Where;
+    orderBy?: Partial<Record<ColumnName<S, T>, OrderTypes | string>> | string | string[];
+    offset?: number;
+};
+/**
+ * Schema-aware SELECT ALL parameters (includes limit and lazy).
+ */
+type TypedSelectAll<S extends TableSchema, T extends TableName<S>, F extends ColumnName<S, T> = ColumnName<S, T>> = TypedSelectOne<S, T, F> & {
+    limit?: number;
+    lazy?: boolean;
+};
+/**
+ * Schema-aware INSERT parameters.
+ */
+type TypedInsert<S extends TableSchema, T extends TableName<S>> = {
+    tableName: T;
+    data: Partial<S[T]> | Array<Partial<S[T]>>;
+    returning?: ColumnName<S, T>[] | ColumnName<S, T> | '*';
+    onConflict?: string | ConflictTypes | ConflictUpsert;
+};
+/**
+ * Schema-aware UPDATE parameters.
+ */
+type TypedUpdate<S extends TableSchema, T extends TableName<S>> = {
+    tableName: T;
+    data: Partial<S[T]>;
+    where?: Where;
+    returning?: ColumnName<S, T>[] | ColumnName<S, T> | '*';
+    onConflict?: string | ConflictTypes;
+};
+/**
+ * Schema-aware DELETE parameters.
+ */
+type TypedDelete<S extends TableSchema, T extends TableName<S>> = {
+    tableName: T;
+    where: Where;
+    returning?: ColumnName<S, T>[] | ColumnName<S, T> | '*';
+    orderBy?: Partial<Record<ColumnName<S, T>, OrderTypes | string>> | string | string[];
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Infer the result type based on selected fields.
+ * If fields is '*' or undefined, returns full table type.
+ * If fields is an array, returns Pick of those fields.
+ */
+type InferResult<S extends TableSchema, T extends TableName<S>, F> = F extends '*' ? S[T] : F extends ColumnName<S, T>[] ? Pick<S[T], F[number]> : F extends ColumnName<S, T> ? Pick<S[T], F> : S[T];
 
 declare function defaultLogger(query: RawQuery, meta: QueryLoggerMeta): any;
 declare function asyncLoggerWrapper<Async extends boolean = true>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: CallableFunction | undefined, innerFunction: () => any): Promise<any>;
 declare function syncLoggerWrapper<Async extends boolean = false>(query: Query<any, Async> | Query<any, Async>[], loggerFunction: CallableFunction | undefined, innerFunction: () => any): any;
 
-declare class QueryBuilder<GenericResultWrapper, IsAsync extends boolean = true> {
+declare class QueryBuilder<Schema extends TableSchema = {}, GenericResultWrapper = unknown, IsAsync extends boolean = true> {
     protected options: QueryBuilderOptions<IsAsync>;
     loggerWrapper: typeof asyncLoggerWrapper;
     constructor(options?: QueryBuilderOptions<IsAsync>);
@@ -252,19 +375,27 @@ declare class QueryBuilder<GenericResultWrapper, IsAsync extends boolean = true>
         tableName: string;
         ifExists?: boolean;
     }): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync>, IsAsync>;
-    select<GenericResult = DefaultReturnObject>(tableName: string): SelectBuilder<GenericResultWrapper, GenericResult, IsAsync>;
+    select<T extends TableName<Schema>>(tableName: T): SelectBuilder<Schema, GenericResultWrapper, Schema[T], IsAsync>;
+    select<GenericResult = DefaultReturnObject>(tableName: string): SelectBuilder<{}, GenericResultWrapper, GenericResult, IsAsync>;
+    fetchOne<T extends TableName<Schema>, F extends ColumnName<Schema, T> = ColumnName<Schema, T>>(params: TypedSelectOne<Schema, T, F>): QueryWithExtra<GenericResultWrapper, OneResult<GenericResultWrapper, InferResult<Schema, T, F[] | undefined>>, IsAsync>;
     fetchOne<GenericResult = DefaultReturnObject>(params: SelectOne): QueryWithExtra<GenericResultWrapper, OneResult<GenericResultWrapper, GenericResult>, IsAsync>;
+    fetchAll<T extends TableName<Schema>, F extends ColumnName<Schema, T> = ColumnName<Schema, T>, P extends TypedSelectAll<Schema, T, F> = TypedSelectAll<Schema, T, F>>(params: P): QueryWithExtra<GenericResultWrapper, ArrayResult<GenericResultWrapper, InferResult<Schema, T, F[] | undefined>, IsAsync, P extends {
+        lazy: true;
+    } ? true : false>, IsAsync>;
     fetchAll<GenericResult = DefaultReturnObject, P extends SelectAll = SelectAll>(params: P): QueryWithExtra<GenericResultWrapper, ArrayResult<GenericResultWrapper, GenericResult, IsAsync, P extends {
         lazy: true;
     } ? true : false>, IsAsync>;
     raw<GenericResult = DefaultReturnObject>(params: RawQueryFetchOne): Query<OneResult<GenericResultWrapper, GenericResult>, IsAsync>;
     raw<GenericResult = DefaultReturnObject>(params: RawQueryFetchAll): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync>, IsAsync>;
     raw<GenericResult = DefaultReturnObject>(params: RawQueryWithoutFetching): Query<GenericResultWrapper, IsAsync>;
+    insert<T extends TableName<Schema>>(params: TypedInsert<Schema, T>): Query<GenericResultWrapper, IsAsync>;
     insert<GenericResult = DefaultReturnObject>(params: InsertOne): Query<OneResult<GenericResultWrapper, GenericResult>, IsAsync>;
     insert<GenericResult = DefaultReturnObject>(params: InsertMultiple): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync>, IsAsync>;
     insert<GenericResult = DefaultReturnObject>(params: InsertWithoutReturning): Query<GenericResultWrapper, IsAsync>;
+    update<T extends TableName<Schema>>(params: TypedUpdate<Schema, T>): Query<GenericResultWrapper, IsAsync>;
     update<GenericResult = DefaultReturnObject>(params: UpdateReturning): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync>, IsAsync>;
     update<GenericResult = DefaultReturnObject>(params: UpdateWithoutReturning): Query<GenericResultWrapper, IsAsync>;
+    delete<T extends TableName<Schema>>(params: TypedDelete<Schema, T>): Query<GenericResultWrapper, IsAsync>;
     delete<GenericResult = DefaultReturnObject>(params: DeleteReturning): Query<ArrayResult<GenericResultWrapper, GenericResult, IsAsync>, IsAsync>;
     delete<GenericResult = DefaultReturnObject>(params: DeleteWithoutReturning): Query<GenericResultWrapper, IsAsync>;
     protected _parse_arguments(row: DefaultObject): Array<any>;
@@ -311,20 +442,20 @@ type MigrationOptions = {
     tableName?: string;
 };
 declare class syncMigrationsBuilder<GenericResultWrapper> {
-    _builder: QueryBuilder<GenericResultWrapper, false>;
+    _builder: QueryBuilder<any, GenericResultWrapper, false>;
     _migrations: Array<Migration>;
     _tableName: string;
-    constructor(options: MigrationOptions, builder: QueryBuilder<GenericResultWrapper, false>);
+    constructor(options: MigrationOptions, builder: QueryBuilder<any, GenericResultWrapper, false>);
     initialize(): void;
     getApplied(): Array<MigrationEntry>;
     getUnapplied(): Array<Migration>;
     apply(): Array<Migration>;
 }
 declare class asyncMigrationsBuilder<GenericResultWrapper> {
-    _builder: QueryBuilder<GenericResultWrapper, true>;
+    _builder: QueryBuilder<any, GenericResultWrapper, true>;
     _migrations: Array<Migration>;
     _tableName: string;
-    constructor(options: MigrationOptions, builder: QueryBuilder<GenericResultWrapper, true>);
+    constructor(options: MigrationOptions, builder: QueryBuilder<any, GenericResultWrapper, true>);
     initialize(): Promise<void>;
     getApplied(): Promise<Array<MigrationEntry>>;
     getUnapplied(): Promise<Array<Migration>>;
@@ -336,7 +467,7 @@ interface D1Database {
     batch: any;
     exec: any;
 }
-declare class D1QB extends QueryBuilder<D1Result> {
+declare class D1QB<Schema extends TableSchema = {}> extends QueryBuilder<Schema, D1Result, true> {
     db: any;
     constructor(db: D1Database, options?: QueryBuilderOptions);
     migrations(options: MigrationOptions): asyncMigrationsBuilder<D1Result>;
@@ -344,23 +475,13 @@ declare class D1QB extends QueryBuilder<D1Result> {
     batchExecute(queryArray: Query[]): Promise<any>;
 }
 
-declare class PGQB extends QueryBuilder<PGResult> {
-    db: any;
-    _migrationsBuilder: typeof asyncMigrationsBuilder;
-    constructor(db: any, options?: QueryBuilderOptions);
-    migrations(options: MigrationOptions): asyncMigrationsBuilder<PGResult>;
-    connect(): Promise<void>;
-    close(): Promise<void>;
-    execute(query: Query): Promise<any>;
-}
-
 interface SqlStorage {
     exec: any;
-    prepare: any;
+    get databaseSize(): number;
     Cursor: any;
     Statement: any;
 }
-declare class DOQB extends QueryBuilder<DOResult, false> {
+declare class DOQB<Schema extends TableSchema = {}> extends QueryBuilder<Schema, DOResult, false> {
     db: SqlStorage;
     loggerWrapper: typeof syncLoggerWrapper;
     constructor(db: SqlStorage, options?: QueryBuilderOptions<false>);
@@ -369,4 +490,14 @@ declare class DOQB extends QueryBuilder<DOResult, false> {
     lazyExecute(query: Query<any, false>): Iterable<any>;
 }
 
-export { type ArrayResult, type AsyncType, ConflictTypes, type ConflictUpsert, type CountResult, type D1Meta, D1QB, type D1Result, DOQB, type DOResult, type DefaultObject, type DefaultReturnObject, type Delete, type DeleteReturning, type DeleteWithoutReturning, FetchTypes, type FullArrayResult, type Insert, type InsertMultiple, type InsertOne, type InsertWithoutReturning, type IterableResult, type Join, JoinTypes, type MaybeAsync, type Migration, type MigrationEntry, type MigrationOptions, type OneResult, OrderTypes, PGQB, type PGResult, type Primitive, Query, QueryBuilder, type QueryBuilderOptions, type QueryLoggerMeta, QueryWithExtra, Raw, type RawQuery, type RawQueryFetchAll, type RawQueryFetchOne, type RawQueryWithoutFetching, type SelectAll, type SelectOne, type SyncType, type Update, type UpdateReturning, type UpdateWithoutReturning, type Where, asyncLoggerWrapper, asyncMigrationsBuilder, defaultLogger, syncLoggerWrapper, syncMigrationsBuilder, type test, trimQuery };
+declare class PGQB<Schema extends TableSchema = {}> extends QueryBuilder<Schema, PGResult, true> {
+    db: any;
+    _migrationsBuilder: typeof asyncMigrationsBuilder;
+    constructor(db: any, options?: QueryBuilderOptions);
+    migrations(options: MigrationOptions): asyncMigrationsBuilder<PGResult>;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    execute(query: Query): Promise<any>;
+}
+
+export { type ArrayResult, type AsyncType, type ColumnName, ConflictTypes, type ConflictUpsert, type CountResult, type D1Meta, D1QB, type D1Result, DOQB, type DOResult, type DefaultObject, type DefaultReturnObject, type Delete, type DeleteReturning, type DeleteWithoutReturning, FetchTypes, type FullArrayResult, type InferResult, type Insert, type InsertData, type InsertMultiple, type InsertOne, type InsertWithoutReturning, type IsEmptySchema, type IterableResult, type Join, JoinTypes, type MaybeAsync, type Migration, type MigrationEntry, type MigrationOptions, type OneResult, OrderTypes, PGQB, type PGResult, type Primitive, Query, QueryBuilder, type QueryBuilderOptions, type QueryLoggerMeta, QueryWithExtra, Raw, type RawQuery, type RawQueryFetchAll, type RawQueryFetchOne, type RawQueryWithoutFetching, type SchemaAware, type SelectAll, type SelectColumns, type SelectOne, type SyncType, type TableName, type TableSchema, type TypedDelete, type TypedInsert, type TypedSelectAll, type TypedSelectOne, type TypedUpdate, type Update, type UpdateData, type UpdateReturning, type UpdateWithoutReturning, type Where, asyncLoggerWrapper, asyncMigrationsBuilder, defaultLogger, syncLoggerWrapper, syncMigrationsBuilder, trimQuery };