bun-query-builder 0.1.10 → 0.1.12

package/dist/browser.d.ts

@@ -0,0 +1,288 @@
+import type { BrowserConfig } from './types';
+import type { Faker } from 'ts-mocker';
+export type { BrowserModelInstance, BrowserModelQueryBuilder };
+/**
+ * Configure the browser query client
+ */
+export declare function configureBrowser(config: Partial<BrowserConfig>): void;
+/**
+ * Get the current browser configuration
+ */
+export declare function getBrowserConfig(): BrowserConfig;
+/**
+ * Check if we're in a browser environment
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Create a browser query builder for a table
+ */
+export declare function browserQuery<T = any>(table: string): BrowserQueryBuilder<T>;
+/**
+ * Shorthand for common tables - creates a factory function
+ */
+export declare function createBrowserDb<Tables extends Record<string, any>>(): {
+  [K in keyof Tables]: () => BrowserQueryBuilder<Tables[K]>
+};
+/**
+ * Create a browser model from a definition with full type inference
+ *
+ * @example
+ * ```ts
+ * const roles = ['admin', 'user', 'moderator'] as const
+ *
+ * const User = createBrowserModel({
+ *   name: 'User',
+ *   table: 'users',
+ *   traits: {
+ *     useTimestamps: true,
+ *     useApi: { uri: 'users' }
+ *   },
+ *   attributes: {
+ *     name: { fillable: true, factory: () => 'John' },
+ *     email: { fillable: true, factory: () => 'john@example.com' },
+ *     role: { fillable: true, factory: (): typeof roles[number] => 'user' },
+ *   }
+ * } as const)
+ *
+ * // Full type inference:
+ * const user = await User.find(1)
+ * user?.get('role') // type: 'admin' | 'user' | 'moderator'
+ *
+ * const roles = await User.pluck('role')
+ * // type: ('admin' | 'user' | 'moderator')[]
+ * ```
+ */
+export declare function createBrowserModel<const TDef extends BrowserModelDefinition>(definition: TDef): void;
+/**
+ * Auth helpers for browser
+ */
+export declare const browserAuth: {
+  /**
+   * Login and store token
+   */
+  async login(credentials: { email: string, password: string }): () => unknown;
+  /**
+   * Register a new user
+   */
+  async register(data: { name: string, email: string, password: string }): () => unknown;
+  /**
+   * Logout and clear token
+   */
+  async logout(): unknown;
+  /**
+   * Get current authenticated user
+   */
+  async user(): unknown;
+  /**
+   * Check if user is authenticated
+   */
+  async check(): unknown;
+  /**
+   * Get the current token
+   */
+  getToken: unknown
+};
+// Attribute definition with explicit type
+export declare interface BrowserTypedAttribute<T = unknown> {
+  type?: T
+  order?: number
+  fillable?: boolean
+  unique?: boolean
+  hidden?: boolean
+  guarded?: boolean
+  nullable?: boolean
+  default?: InferType<T>
+  validation?: {
+    rule: unknown
+    message?: Record<string, string>
+  }
+  factory?: (faker: Faker) => InferType<T>
+}
+// Base model definition for browser
+export declare interface BrowserModelDefinition {
+  name: string
+  table: string
+  primaryKey?: string
+  traits?: {
+    readonly useUuid?: boolean
+    readonly useTimestamps?: boolean
+    readonly useSoftDeletes?: boolean
+    readonly useApi?: {
+      readonly uri: string
+      readonly routes?: readonly string[]
+    }
+  }
+  attributes: {
+    readonly [key: string]: BrowserTypedAttribute<unknown>
+  }
+}
+declare interface QueryState {
+  table: string
+  wheres: WhereClause[]
+  orderBy: OrderByClause[]
+  limitValue?: number
+  offsetValue?: number
+  selectColumns: string[]
+  withRelations: string[]
+}
+// Primitive type mappings
+declare type PrimitiveTypeMap = {
+  string: string
+  number: number
+  boolean: boolean
+  date: Date
+  json: Record<string, unknown>
+}
+// Infer the actual TS type from attribute type definition
+declare type InferType<T> = T extends keyof PrimitiveTypeMap ? PrimitiveTypeMap[T] :
+  T extends readonly (infer U)[] ? U :
+  T extends (infer U)[] ? U :
+  unknown
+// Extract attribute keys from definition
+declare type BrowserAttributeKeys<TDef extends BrowserModelDefinition> = keyof TDef['attributes'] & string
+// Infer single attribute type
+declare type InferBrowserAttributeType<TAttr> = TAttr extends { type: infer T } ? InferType<T> :
+  TAttr extends { factory: (faker: unknown) => infer R } ? R :
+  unknown
+// Build the full attributes type from definition
+declare type InferBrowserModelAttributes<TDef extends BrowserModelDefinition> = {
+  [K in BrowserAttributeKeys<TDef>]: InferBrowserAttributeType<TDef['attributes'][K]>
+}
+// System fields added by traits
+declare type BrowserSystemFields<TDef extends BrowserModelDefinition> = { id: number } &
+  (TDef['traits'] extends { useUuid: true } ? { uuid: string } : {}) &
+  (TDef['traits'] extends { useTimestamps: true } ? { created_at: string; updated_at: string } : {}) &
+  (TDef['traits'] extends { useSoftDeletes: true } ? { deleted_at: string | null } : {})
+// Complete model type
+declare type BrowserModelAttributes<TDef extends BrowserModelDefinition> = InferBrowserModelAttributes<TDef> & BrowserSystemFields<TDef>
+// All valid column names
+declare type BrowserColumnName<TDef extends BrowserModelDefinition> = | BrowserAttributeKeys<TDef>
+  | 'id'
+  | (TDef['traits'] extends { useUuid: true } ? 'uuid' : never)
+  | (TDef['traits'] extends { useTimestamps: true } ? 'created_at' | 'updated_at' : never)
+  | (TDef['traits'] extends { useSoftDeletes: true } ? 'deleted_at' : never)
+// Hidden fields
+declare type BrowserHiddenKeys<TDef extends BrowserModelDefinition> = {
+  [K in BrowserAttributeKeys<TDef>]: TDef['attributes'][K] extends { hidden: true } ? K : never
+}[BrowserAttributeKeys<TDef>]
+// Fillable fields
+declare type BrowserFillableKeys<TDef extends BrowserModelDefinition> = {
+  [K in BrowserAttributeKeys<TDef>]: TDef['attributes'][K] extends { fillable: true } ? K : never
+}[BrowserAttributeKeys<TDef>]
+// Types for query building
+export type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'in' | 'not in' | 'is' | 'is not'
+/**
+ * Custom error class for browser query errors
+ */
+export declare class BrowserQueryError extends Error {
+  status: number;
+  constructor(message: string, status: number);
+}
+/**
+ * Browser Query Builder
+ * Fluent API that builds queries and executes them via fetch
+ */
+export declare class BrowserQueryBuilder<T = any> {
+  private state: QueryState;
+  constructor(table: string);
+  select(columns: string[]): this;
+  where(column: string, operatorOrValue: WhereOperator | any, value?: any): this;
+  orWhere(column: string, operatorOrValue: WhereOperator | any, value?: any): this;
+  andWhere(column: string, operatorOrValue: WhereOperator | any, value?: any): this;
+  whereNull(column: string): this;
+  whereNotNull(column: string): this;
+  whereIn(column: string, values: any[]): this;
+  whereNotIn(column: string, values: any[]): this;
+  orderBy(column: string, direction?: 'asc' | 'desc'): this;
+  orderByDesc(column: string): this;
+  latest(column?: string): this;
+  oldest(column?: string): this;
+  limit(count: number): this;
+  offset(count: number): this;
+  skip(count: number): this;
+  take(count: number): this;
+  with(relations: string[]): this;
+  private buildQueryParams(): URLSearchParams;
+  private buildUrl(path?: string | number): string;
+  get(): Promise<T[]>;
+  first(): Promise<T | null>;
+  firstOrFail(): Promise<T>;
+  find(id: number | string): Promise<T | null>;
+  findOrFail(id: number | string): Promise<T>;
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
+  create(data: Partial<T>): Promise<T>;
+  insert(data: Partial<T>): Promise<T>;
+  update(id: number | string, data: Partial<T>): Promise<T>;
+  delete(id: number | string): Promise<boolean>;
+  destroy(id: number | string): Promise<boolean>;
+  paginate(page?: number, perPage?: number): Promise<{
+    data: T[]
+    total: number
+    page: number
+    perPage: number
+    lastPage: number
+  }>;
+  toState(): QueryState;
+}
+/**
+ * Browser Model Instance - represents a single record with type-safe access
+ */
+declare class BrowserModelInstance<TDef extends BrowserModelDefinition, TSelected extends BrowserColumnName<TDef> = BrowserColumnName<TDef>> {
+  private _attributes: Record<string, unknown>;
+  private _definition: TDef;
+  constructor(definition: TDef, attributes?: Partial<BrowserModelAttributes<TDef>>);
+  get<K extends TSelected>(key: K): K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : never;
+  set<K extends BrowserAttributeKeys<TDef>>(key: K, value: BrowserModelAttributes<TDef>[K]): void;
+  toJSON(): Omit<Pick<BrowserModelAttributes<TDef>, TSelected & keyof BrowserModelAttributes<TDef>>, BrowserHiddenKeys<TDef>>;
+}
+/**
+ * Typed Browser Query Builder with precise type narrowing
+ */
+declare class BrowserModelQueryBuilder<TDef extends BrowserModelDefinition, TSelected extends BrowserColumnName<TDef> = BrowserColumnName<TDef>> {
+  private _definition: TDef;
+  private _wheres: { column: string; operator: WhereOperator; value: unknown; boolean: 'and' | 'or' }[];
+  private _orderBy: { column: string; direction: 'asc' | 'desc' }[];
+  private _limit?: number;
+  private _offset?: number;
+  private _select: string[];
+  private _withRelations: string[];
+  constructor(definition: TDef);
+  private getTablePath(): string;
+  where<K extends BrowserColumnName<TDef>>(column: K, operatorOrValue: WhereOperator | (K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown), value?: K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown): BrowserModelQueryBuilder<TDef, TSelected>;
+  orWhere<K extends BrowserColumnName<TDef>>(column: K, operatorOrValue: WhereOperator | (K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown), value?: K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown): BrowserModelQueryBuilder<TDef, TSelected>;
+  whereIn<K extends BrowserColumnName<TDef>>(column: K, values: (K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown)[]): BrowserModelQueryBuilder<TDef, TSelected>;
+  whereNotIn<K extends BrowserColumnName<TDef>>(column: K, values: (K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown)[]): BrowserModelQueryBuilder<TDef, TSelected>;
+  whereNull<K extends BrowserColumnName<TDef>>(column: K): BrowserModelQueryBuilder<TDef, TSelected>;
+  whereNotNull<K extends BrowserColumnName<TDef>>(column: K): BrowserModelQueryBuilder<TDef, TSelected>;
+  whereLike<K extends BrowserColumnName<TDef>>(column: K, pattern: string): BrowserModelQueryBuilder<TDef, TSelected>;
+  orderBy<K extends BrowserColumnName<TDef>>(column: K, direction?: 'asc' | 'desc'): BrowserModelQueryBuilder<TDef, TSelected>;
+  orderByDesc<K extends BrowserColumnName<TDef>>(column: K): BrowserModelQueryBuilder<TDef, TSelected>;
+  orderByAsc<K extends BrowserColumnName<TDef>>(column: K): BrowserModelQueryBuilder<TDef, TSelected>;
+  limit(count: number): BrowserModelQueryBuilder<TDef, TSelected>;
+  take(count: number): BrowserModelQueryBuilder<TDef, TSelected>;
+  offset(count: number): BrowserModelQueryBuilder<TDef, TSelected>;
+  skip(count: number): BrowserModelQueryBuilder<TDef, TSelected>;
+  select<K extends BrowserColumnName<TDef>>(columns: K[]): BrowserModelQueryBuilder<TDef, K>;
+  with(relations: string[]): BrowserModelQueryBuilder<TDef, TSelected>;
+  latest(column?: BrowserColumnName<TDef>): BrowserModelQueryBuilder<TDef, TSelected>;
+  oldest(column?: BrowserColumnName<TDef>): BrowserModelQueryBuilder<TDef, TSelected>;
+  private buildQueryParams(): URLSearchParams;
+  private buildUrl(path?: string | number): string;
+  get(): Promise<BrowserModelInstance<TDef, TSelected>[]>;
+  first(): Promise<BrowserModelInstance<TDef, TSelected> | null>;
+  firstOrFail(): Promise<BrowserModelInstance<TDef, TSelected>>;
+  find(id: number | string): Promise<BrowserModelInstance<TDef, TSelected> | null>;
+  findOrFail(id: number | string): Promise<BrowserModelInstance<TDef, TSelected>>;
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
+  pluck<K extends BrowserColumnName<TDef>>(column: K): Promise<(K extends keyof BrowserModelAttributes<TDef> ? BrowserModelAttributes<TDef>[K] : unknown)[]>;
+  paginate(page?: any, perPage?: any): Promise<{
+    data: BrowserModelInstance<TDef, TSelected>[]
+    total: number
+    page: number
+    perPage: number
+    lastPage: number
+  }>;
+}
+export default browserQuery;

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { config } from './config';
+import { resetConnection } from './db';
 import type { DatabaseSchema } from './schema';
 import type { SchemaMeta } from './meta';
 export declare function createQueryBuilder<DB extends DatabaseSchema<any>>(state?: Partial<InternalState>): QueryBuilder<DB>;
@@ -168,6 +169,7 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   toSQL: () => string
   execute: () => Promise<SelectedRow<DB, TTable, TSelected>[]>
   executeTakeFirst: () => Promise<SelectedRow<DB, TTable, TSelected> | undefined>
+  executeTakeFirstOrThrow: () => Promise<SelectedRow<DB, TTable, TSelected>>
   get: () => Promise<SelectedRow<DB, TTable, TSelected>[]>
   first: () => Promise<SelectedRow<DB, TTable, TSelected> | undefined>
   firstOrFail: () => Promise<SelectedRow<DB, TTable, TSelected>>
@@ -202,21 +204,28 @@ export declare interface InsertQueryBuilder<DB extends DatabaseSchema<any>, TTab
   returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
   toSQL: () => string
   execute: () => Promise<number | DB[TTable]['columns'] | DB[TTable]['columns'][]>
+  returningAll: () => SelectQueryBuilder<DB, TTable, DB[TTable]['columns']>
+  executeTakeFirst: () => Promise<DB[TTable]['columns'] | undefined>
+  executeTakeFirstOrThrow: () => Promise<DB[TTable]['columns']>
 }
 export declare interface UpdateQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
   set: (values: Partial<DB[TTable]['columns']>) => UpdateQueryBuilder<DB, TTable>
-  where: (expr: WhereExpression<DB[TTable]['columns']>) => UpdateQueryBuilder<DB, TTable>
+  where: (expr: WhereExpression<DB[TTable]['columns']> | string, op?: WhereOperator, value?: any) => UpdateQueryBuilder<DB, TTable>
   returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
   toSQL: () => string
   execute: () => Promise<number>
-  executeTakeFirst?: () => Promise<{ numUpdatedRows?: number }>
+  returningAll: () => SelectQueryBuilder<DB, TTable, DB[TTable]['columns']>
+  executeTakeFirst: () => Promise<{ numUpdatedRows?: number }>
+  executeTakeFirstOrThrow: () => Promise<{ numUpdatedRows: number }>
 }
 export declare interface DeleteQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
-  where: (expr: WhereExpression<DB[TTable]['columns']>) => DeleteQueryBuilder<DB, TTable>
+  where: (expr: WhereExpression<DB[TTable]['columns']> | string, op?: WhereOperator, value?: any) => DeleteQueryBuilder<DB, TTable>
   returning: <K extends keyof DB[TTable]['columns'] & string>(...cols: K[]) => SelectQueryBuilder<DB, TTable, Pick<DB[TTable]['columns'], K>>
   toSQL: () => string
   execute: () => Promise<number>
-  executeTakeFirst?: () => Promise<{ numDeletedRows?: number }>
+  returningAll: () => SelectQueryBuilder<DB, TTable, DB[TTable]['columns']>
+  executeTakeFirst: () => Promise<{ numDeletedRows?: number }>
+  executeTakeFirstOrThrow: () => Promise<{ numDeletedRows: number }>
 }
 export declare interface TableQueryBuilder<DB extends DatabaseSchema<any>, TTable extends keyof DB & string> {
   insert: (data: Partial<DB[TTable]['columns']> | Partial<DB[TTable]['columns']>[]) => InsertQueryBuilder<DB, TTable>
@@ -486,4 +495,5 @@ declare class QueryCache {
   set(key: string, data: any, ttlMs: number): void;
   clear(): void;
   setMaxSize(size: number): void;
-}
+}
+export { resetConnection };

package/dist/config.d.ts

@@ -1,4 +1,22 @@
 import type { QueryBuilderConfig } from './types';
+/**
+ * Get the placeholder format for the current dialect.
+ * PostgreSQL uses $1, $2, $3... while MySQL and SQLite use ?
+ */
+export declare function getPlaceholder(index: number): string;
+/**
+ * Generate placeholders for an array of values.
+ * PostgreSQL: $1, $2, $3
+ * MySQL/SQLite: ?, ?, ?
+ */
+export declare function getPlaceholders(count: number, startIndex?: any): string;
+export declare function getConfig(): Promise<QueryBuilderConfig>;
+/**
+ * Programmatically set/override the query builder configuration.
+ * This is useful when you want to configure bun-query-builder from
+ * your application code rather than using a config file.
+ */
+export declare function setConfig(userConfig: Partial<QueryBuilderConfig>): void;
 export declare const defaultConfig: QueryBuilderConfig;
-// eslint-disable-next-line antfu/no-top-level-await
+// For backwards compatibility - synchronous access with default fallback
 export declare const config: QueryBuilderConfig;

package/dist/db.d.ts

@@ -1,11 +1,30 @@
 import { SQL } from 'bun';
+import { Database } from 'bun:sqlite';
 /**
  * Returns a Bun SQL instance configured for the current dialect and database settings.
+ * For SQLite, uses bun:sqlite directly for better compiled binary support.
  * Handles connection errors gracefully by falling back to in-memory SQLite.
  */
 export declare function getBunSql(): SQL;
 export declare function getOrCreateBunSql(forceNew?: any): SQL;
+/**
+ * Resets the cached database connection.
+ * Call this after changing config via setConfig() to ensure the new config is used.
+ */
+export declare function resetConnection(): void;
 // Wrapper that catches "Connection closed" errors and retries with a fresh connection
 export declare function withFreshConnection<T>(fn: (sql: SQL) => Promise<T>): Promise<T>;
-export declare const bunSql: unknown;
+// Export a lazy proxy - no connection is made until first use
+export declare const bunSql: SQL;
+/**
+ * SQLite wrapper that provides a SQL-like tagged template literal interface
+ * using bun:sqlite's Database class for better compiled binary support.
+ */
+declare class SQLiteWrapper {
+  private db: Database;
+  constructor(filename: string);
+  query(sql: string, params?: any[]): any[];
+  run(sql: string, params?: any[]): any;
+  close(): void;
+}
 export { SQL } from 'bun';