bun-query-builder 0.1.16 → 0.1.18

package/dist/browser.d.ts

@@ -62,11 +62,11 @@ export declare const browserAuth: {
   /**
    * Login and store token
    */
-  async login: (credentials: { email: string, password: string }) => Promise<;
+  async login: (credentials: { email: string, password: string }) => Promise<BrowserAuthResponse>;
   /**
    * Register a new user
    */
-  async register: (data: { name: string, email: string, password: string }) => Promise<;
+  async register: (data: { name: string, email: string, password: string }) => Promise<BrowserAuthResponse>;
   /**
    * Logout and clear token
    */
@@ -159,6 +159,18 @@ declare interface QueryState {
   selectColumns: string[]
   withRelations: string[]
 }
+/**
+ * Response shape returned by `browserAuth.login` / `browserAuth.register`.
+ * Lifted to a named type so the generated `.d.ts` doesn't carry a nested
+ * inline object literal in the return position — bun-plugin-dtsx has a
+ * bug where `Promise<{ ... }>` in that position emits as `Promise<;`,
+ * breaking downstream typecheck for any consumer that imports from
+ * `bun-query-builder/browser`.
+ */
+export declare interface BrowserAuthResponse {
+  user: Record<string, unknown>
+  token: string
+}
 // Primitive type mappings
 declare type PrimitiveTypeMap = {
   string: string
@@ -247,7 +259,7 @@ declare type BrowserRelationNames<TDef> = | BrowserBelongsToNames<TDef>
   | BrowserHasOneThroughNames<TDef>
   | BrowserHasManyThroughNames<TDef>;
 // Types for query building
-export type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'in' | 'not in' | 'is' | 'is not';
+export type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'not like' | 'in' | 'not in' | 'is' | 'is not';
 /**
  * Custom error class for browser query errors
  */

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { config } from './config';
 import { resetConnection } from './db';
 import type { DatabaseSchema } from './schema';
 import type { SchemaMeta } from './meta';
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function createQueryBuilder<DB extends DatabaseSchema<any>>(state?: Partial<InternalState>): QueryBuilder<DB>;
 /**
  * # `clearQueryCache()`
@@ -119,6 +120,11 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   whereJsonLength?: (path: string, opOrLen: WhereOperator | number, len?: number) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   with?: (...relations: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
   withPivot?: (relation: string, ...columns: string[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivot?: (relation: string, column: string, opOrValue: any, value?: any) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotIn?: (relation: string, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNotIn?: (relation: string, column: string, values: any[]) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNull?: (relation: string, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
+  wherePivotNotNull?: (relation: string, column: string) => SelectQueryBuilder<DB, TTable, TSelected, any>
   applyPivotColumns?: () => SelectQueryBuilder<DB, TTable, TSelected, any>
   lockForUpdate: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   sharedLock: () => SelectQueryBuilder<DB, TTable, TSelected, TJoined>

package/dist/db.d.ts

@@ -0,0 +1,31 @@
+import { Database } from 'bun:sqlite';
+import { SQL } from 'bun';
+/**
+ * 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?: boolean): 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 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 {
+  constructor(filename: string);
+  query(sql: string, params?: any[]): any[];
+  run(sql: string, params?: any[]): any;
+  close(): void;
+  get database(): Database;
+}
+// Also export the SQL class for advanced usage
+export { SQL } from 'bun';

package/dist/dynamodb-single-table.d.ts

@@ -9,7 +9,6 @@ export declare function createSingleTableManager(config: SingleTableConfig): Sin
  */
 export declare function createRepository<T extends Record<string, any>>(manager: SingleTableManager, entityName: string, options: DynamoDBQueryBuilderOptions): SingleTableRepository<T>;
 /**
- * Common single table design patterns
  * @defaultValue
  * ```ts
  * {
@@ -17,11 +16,11 @@ export declare function createRepository<T extends Record<string, any>>(manager:
  *   oneToMany: (parentEntity: string,
  *     childEntity: string,
  *     parentIdField?: string,
- *     childIdField?: string,) => { parent: SingleTableEntity, child: SingleTableEntity },
+ *     childIdField?: string,) => OneToManyPattern,
  *   manyToMany: (entityName: string,
  *     relationName: string,
  *     idField?: string,
- *     relatedIdField?: string,) => { entity: SingleTableEntity, relation: SingleTableEntity },
+ *     relatedIdField?: string,) => ManyToManyPattern,
  *   hierarchical: (entityName: string, rootIdField?: string, pathField?: string) => SingleTableEntity
  * }
  * ```
@@ -38,20 +37,14 @@ export declare const SingleTablePatterns: {
    * Parent: PK=PARENT#<parentId>, SK=METADATA
    * Child: PK=PARENT#<parentId>, SK=CHILD#<childId>
    */
-  oneToMany: (parentEntity: string,
-    childEntity: string,
-    parentIdField?: string,
-    childIdField?: string,) => ;
+  oneToMany: (parentEntity: string, childEntity: string, parentIdField?: string, childIdField?: string,) => OneToManyPattern;
   /**
    * Many-to-many relationship pattern using adjacency list
    * Entity: PK=ENTITY#<entityId>, SK=METADATA
    * Relationship: PK=ENTITY#<entityId>, SK=RELATED#<relatedId>
    * Inverse: PK=ENTITY#<relatedId>, SK=RELATED#<entityId> (via GSI)
    */
-  manyToMany: (entityName: string,
-    relationName: string,
-    idField?: string,
-    relatedIdField?: string,) => ;
+  manyToMany: (entityName: string, relationName: string, idField?: string, relatedIdField?: string,) => ManyToManyPattern;
   /**
    * Hierarchical data pattern (e.g., org chart, file system)
    * PK: ROOT#<rootId>
@@ -92,6 +85,33 @@ export declare interface SingleTableConfig {
   }[]
   entities: SingleTableEntity[]
 }
+export declare interface OneToManyPattern {
+  parent: SingleTableEntity
+  child: SingleTableEntity
+}
+export declare interface ManyToManyPattern {
+  entity: SingleTableEntity
+  relation: SingleTableEntity
+}
+/**
+ * Common single table design patterns
+ */
+/**
+ * Result shapes for relationship pattern helpers. Lifted to named
+ * interfaces so the generated `.d.ts` doesn't carry an inline object
+ * literal in the return position — bun-plugin-dtsx has a bug where
+ * `(...) => { ... }` in that position emits as `=> ;`, breaking
+ * downstream typecheck for any consumer importing from
+ * `bun-query-builder/dynamodb-single-table`.
+ */
+export declare interface OneToManyPattern {
+  parent: SingleTableEntity
+  child: SingleTableEntity
+}
+export declare interface ManyToManyPattern {
+  entity: SingleTableEntity
+  relation: SingleTableEntity
+}
 /**
  * Single Table Design Manager
  *

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export type {
   InferColumnNames,
   InferHiddenKeys,
   InferGuardedKeys,
+  InferPivotColumns,
   ModelRow,
   ModelRowLoose,
   ModelCreateData,
@@ -35,6 +36,7 @@ export * from './factory';
 export * from './loader';
 export * from './meta';
 export * from './migrations';
+export * from './pivot';
 export * from './orm';
 export * from './schema';
 export * from './seeder';

package/dist/meta.d.ts

@@ -1,4 +1,4 @@
-import type { ModelRecord } from './schema';
+import type { BelongsToManyConfig, ModelRecord } from './schema';
 export declare function buildSchemaMeta(models: ModelRecord): SchemaMeta;
 export declare interface SchemaMeta {
   modelToTable: Record<string, string>
@@ -8,7 +8,7 @@ export declare interface SchemaMeta {
     hasOne?: Record<string, string>
     hasMany?: Record<string, string>
     belongsTo?: Record<string, string>
-    belongsToMany?: Record<string, string>
+    belongsToMany?: Record<string, string | BelongsToManyConfig>
     hasOneThrough?: Record<string, { through: string, target: string }>
     hasManyThrough?: Record<string, { through: string, target: string }>
     morphOne?: Record<string, string>
@@ -18,4 +18,5 @@ export declare interface SchemaMeta {
     morphedByMany?: Record<string, string>
   }>
   scopes?: Record<string, Record<string, (qb: any, value?: any) => any>>
+  models?: ModelRecord
 }

package/dist/migrations.d.ts

@@ -42,6 +42,7 @@ export declare interface IndexPlan {
   name: string
   columns: string[]
   type: 'index' | 'unique'
+  where?: string
 }
 export declare interface TablePlan {
   table: string

package/dist/orm.d.ts

@@ -119,6 +119,31 @@ export declare interface ModelDefinition {
     readonly afterDelete?: (model: ModelHookInstance) => void | Promise<void>
   }
 }
+/**
+ * Resolve a relation from its name and the parent model's definition.
+ * Uses the model registry to find the related model's definition.
+ *
+ * Supports both syntaxes:
+ *   Array syntax:  hasMany: ['Order']        → relation name is 'order', model is 'Order'
+ *   Object syntax: hasMany: { orders: 'Order' } → relation name is 'orders', model is 'Order'
+ */
+/**
+ * Resolved-relation shape returned by `resolveRelation`. Pivot fields are
+ * populated only for `belongsToMany` relations.
+ */
+declare interface ResolvedRelation {
+  type: 'hasMany' | 'hasOne' | 'belongsTo' | 'belongsToMany'
+  relatedModelName: string
+  relatedTable: string
+  foreignKey: string
+  localKey: string
+  pivotTable?: string
+  pivotFkParent?: string
+  pivotFkRelated?: string
+  pivotColumns?: string[]
+  pivotModelName?: string
+  pivotTimestamps?: boolean
+}
 // Binding helper type for SQL queries
 declare type Bindings = SQLQueryBindings[];
 // Primitive type mappings
@@ -208,7 +233,7 @@ export type InferRelationNames<TDef> = | InferBelongsToNames<TDef>
   | InferBelongsToManyNames<TDef>
   | InferHasOneThroughNames<TDef>
   | InferHasManyThroughNames<TDef>;
-declare type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'in' | 'not in';
+declare type WhereOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like' | 'not like' | 'in' | 'not in';
 /**
  * Model instance - represents a single database record
  */
@@ -220,7 +245,6 @@ declare class ModelInstance<TDef extends ModelDefinition, TSelected extends Colu
   set<K extends ColumnName<TDef>>(key: K, value: K extends keyof ModelAttributes<TDef> ? ModelAttributes<TDef>[K] : unknown): void;
   only<K extends TSelected>(keys: ReadonlyArray<K>): Partial<ModelAttributes<TDef>>;
   except<K extends TSelected>(keys: ReadonlyArray<K>): Partial<ModelAttributes<TDef>>;
-  toArray(): Record<string, unknown>;
   getRelation(name: string): ModelInstance<any, any>[] | ModelInstance<any, any> | null | undefined;
   setRelation(name: string, data: ModelInstance<any, any>[] | ModelInstance<any, any> | null): void;
   getLoadedRelations(): Record<string, ModelInstance<any, any>[] | ModelInstance<any, any> | null>;
@@ -238,8 +262,41 @@ declare class ModelInstance<TDef extends ModelDefinition, TSelected extends Colu
   delete(): boolean;
   refresh(): this | null;
   replicate(): ModelInstance<TDef, TSelected>;
+  toArray(): Record<string, unknown>;
   toJSON(): Omit<Pick<ModelAttributes<TDef>, TSelected & keyof ModelAttributes<TDef>>, HiddenKeys<TDef>>;
-  toArray(): Omit<Pick<ModelAttributes<TDef>, TSelected & keyof ModelAttributes<TDef>>, HiddenKeys<TDef>>;
+}
+/**
+ * # `BelongsToManyRelationBuilder`
+ *
+ * Per-instance relation builder returned by callable accessors on a
+ * `ModelInstance`. Combines a query side (read pivot-joined related rows,
+ * filter by pivot columns) with a mutation side (attach/detach/sync/
+ * updateExistingPivot/toggle).
+ *
+ * Constructed lazily — `coach.athletes` returns a function that, when called,
+ * returns a fresh builder; chained methods return `this` so a single builder
+ * is reused per call.
+ */
+export declare class BelongsToManyRelationBuilder<TRel extends ModelDefinition> {
+  constructor(parent: ModelInstance<any, any>, parentDef: ModelDefinition, resolved: ResolvedRelation, relatedDef: TRel);
+  where(column: string, opOrValue: unknown, value?: unknown): this;
+  wherePivot(column: string, opOrValue: unknown, value?: unknown): this;
+  wherePivotIn(column: string, values: unknown[]): this;
+  wherePivotNotIn(column: string, values: unknown[]): this;
+  wherePivotNull(column: string): this;
+  wherePivotNotNull(column: string): this;
+  orderBy(column: string, direction?: 'asc' | 'desc'): this;
+  limit(n: number): this;
+  offset(n: number): this;
+  get(): ModelInstance<TRel, any>[];
+  first(): ModelInstance<TRel, any> | undefined;
+  count(): number;
+  exists(): boolean;
+  attach(idOrIds: unknown | unknown[], extras?: Record<string, unknown>): number;
+  detach(idOrIds?: unknown | unknown[]): number;
+  updateExistingPivot(relatedId: unknown, extras: Record<string, unknown>): number;
+  sync(items: Array<unknown | { id: unknown, [key: string]: unknown }>): { attached: unknown[], detached: unknown[], updated: unknown[] };
+  toggle(idOrIds: unknown | unknown[]): { attached: unknown[], detached: unknown[] };
 }
 /**
  * Query builder with precise type narrowing

package/dist/pivot.d.ts

@@ -0,0 +1,29 @@
+import type { ModelRecord, PivotColumnAttribute } from './schema';
+import type { SchemaMeta } from './meta';
+/**
+ * Resolve a `belongsToMany` relation entry to a `ResolvedPivot`. Returns null
+ * when the relation key is absent or not a `belongsToMany` on the parent.
+ */
+export declare function resolvePivot(meta: SchemaMeta, parentTable: string, relationKey: string, options?: ResolvePivotOptions): ResolvedPivot | null;
+/**
+ * Iterate every declared `belongsToMany` relation across all parent tables and
+ * yield each as a `ResolvedPivot`. Useful for migration emission and CLI
+ * introspection.
+ */
+export declare function iterateAllPivots(meta: SchemaMeta, options?: ResolvePivotOptions): Generator<{ parentTable: string, relationKey: string, resolved: ResolvedPivot }>;
+export declare interface ResolvedPivot {
+  pivotTable: string
+  fkParent: string
+  fkRelated: string
+  pivotColumns: string[]
+  pivotColumnDefs: Record<string, PivotColumnAttribute>
+  pivotModelName?: string
+  timestamps: boolean
+  relatedModelName: string
+  relatedTable: string
+  hasConfig: boolean
+}
+export declare interface ResolvePivotOptions {
+  singularize?: (s: string) => string
+  models?: ModelRecord
+}

package/dist/schema.d.ts

@@ -75,14 +75,59 @@ export declare interface AttributesElements {
  *
  * @example
  * ```ts
- * { name: 'user_email_unique', columns: ['email'] }
+ * { name: 'user_email_unique', columns: ['email'], unique: true }
+ * { name: 'one_primary_per_athlete', columns: ['athlete_id'], unique: true, where: "role = 'primary'" }
  * ```
  */
 export declare interface CompositeIndex {
   name: string
   columns: string[]
+  unique?: boolean
+  where?: string
 }
 export declare interface Base {}
+/**
+ * # `PivotColumnAttribute`
+ *
+ * Inline declaration of an extra column on the pivot table (Option A). When the
+ * pivot is declared via a `through` model (Option B), columns are read from
+ * that model's `attributes` instead.
+ */
+export declare interface PivotColumnAttribute {
+  default?: string | number | boolean | Date
+  nullable?: boolean
+  validation?: {
+    rule: ValidationType
+    message?: ValidatorMessage
+  }
+}
+/**
+ * # `PivotConfig`
+ *
+ * Inline pivot configuration (Option A). Used when the pivot does not have its
+ * own model in the registry. Migrations will auto-emit a table for this pivot.
+ */
+export declare interface PivotConfig {
+  columns?: Record<string, PivotColumnAttribute>
+  timestamps?: boolean
+  uniques?: string[][]
+}
+/**
+ * # `BelongsToManyConfig<T>`
+ *
+ * Object form of a `belongsToMany` relation declaration. Either `through`
+ * (Option B — pivot is a registered model) or `pivot.columns` (Option A —
+ * inline metadata) supplies the pivot column metadata. When neither is
+ * supplied the relation behaves exactly like the legacy string form.
+ */
+export declare interface BelongsToManyConfig<T extends string = string> {
+  model: T
+  through?: T
+  table?: string
+  foreignKey?: string
+  relatedKey?: string
+  pivot?: PivotConfig
+}
 /**
  * # `ModelOptions`
  *
@@ -156,7 +201,7 @@ export type ModelNames = string;
 export type HasOne<T extends string> = Record<string, T>;
 export type HasMany<T extends string> = Record<string, T>;
 export type BelongsTo<T extends string> = Record<string, T>;
-export type BelongsToMany<T extends string> = Record<string, T>;
+export type BelongsToMany<T extends string> = Record<string, T | BelongsToManyConfig<T>>;
 export type HasOneThrough<T extends string> = Record<string, { through: T, target: T }>;
 export type HasManyThrough<T extends string> = Record<string, { through: T, target: T }>;
 export type MorphOne<T extends string> = Record<string, T>;