bun-query-builder 0.2.28 → 0.2.30

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserConfig } from './types';
-import type { Faker } from '@stacksjs/ts-faker';
+import type { FactoryFaker } from './faker-compat';
 // Export types for external use
 export type { BrowserModelInstance, BrowserModelQueryBuilder };
 /**
@@ -115,7 +115,7 @@ export declare interface BrowserTypedAttribute<T = unknown> {
     rule: unknown
     message?: Record<string, string>
   }
-  factory?: (faker: Faker) => InferType<T>
+  factory?: (faker: FactoryFaker) => InferType<T>
 }
 // Base model definition for browser
 export declare interface BrowserModelDefinition {

package/dist/client.d.ts

@@ -86,6 +86,13 @@ export declare interface BaseSelectQueryBuilder<DB extends DatabaseSchema<any>,
   whereNotILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   orWhereNotLike: (column: keyof DB[TTable]['columns'] & string, pattern: string, caseSensitive?: boolean) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   orWhereNotILike?: (column: keyof DB[TTable]['columns'] & string, pattern: string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  whereGroup: (callback: (builder: SelectQueryBuilder<DB, TTable, TSelected, TJoined>) => unknown) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereGroup: (callback: (builder: SelectQueryBuilder<DB, TTable, TSelected, TJoined>) => unknown) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNull: (column: keyof DB[TTable]['columns'] & string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereNotNull: (column: keyof DB[TTable]['columns'] & string) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereBetween: (column: keyof DB[TTable]['columns'] & string, start: any, end: any) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereExists: (subquery: { toSQL: () => any }) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
+  orWhereRaw: (fragment: SqlFragment) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   whereAny: <K extends keyof DB[TTable]['columns'] & string>(columns: K[], op: WhereOperator, value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   whereAll: <K extends keyof DB[TTable]['columns'] & string>(columns: K[], op: WhereOperator, value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>
   whereNone: <K extends keyof DB[TTable]['columns'] & string>(columns: K[], op: WhereOperator, value: DB[TTable]['columns'][K]) => SelectQueryBuilder<DB, TTable, TSelected, TJoined>

package/dist/db.d.ts

@@ -1,6 +1,35 @@
 import { Database } from 'bun:sqlite';
 import { SQL } from 'bun';
 import type { DatabaseConfig, PoolConfig, SupportedDialect } from './types';
+/**
+ * SQLite wrapper that provides a SQL-like tagged template literal interface
+ * using bun:sqlite's Database class for better compiled binary support.
+ */
+/**
+ * Give `$1`-style placeholders their Postgres meaning on SQLite: `$n` is the
+ * n-th value, wherever it appears and however often.
+ *
+ * bun:sqlite treats `$1` as a NAME, not an index. Handed an array it binds the
+ * values to those names in ORDER OF FIRST APPEARANCE and ignores the numbers
+ * entirely, so a query whose placeholders are not already in ascending order
+ * binds the wrong values and says nothing:
+ *
+ *   sql.unsafe('SELECT $2 AS a, $1 AS b', ['ONE', 'TWO'])
+ *   -> { a: 'ONE', b: 'TWO' }        // both backwards, no error
+ *
+ * Every caller writing `$n` means the Postgres semantics, because the same
+ * query text is expected to run on both drivers. The failure is silent, and it
+ * lands hardest in exactly the queries that repeat a parameter - authorisation
+ * checks of the shape "owner_id = $2 OR EXISTS (... user_id = $2)" - where the
+ * result is a permission answer computed from the wrong values.
+ *
+ * Rewritten to ordinal `?` here, once, at the only place both `query` and `run`
+ * pass through. Placeholders inside string literals, quoted identifiers and
+ * comments are left alone: `'$1'` is data, not a parameter. SQL with no
+ * numbered placeholders is returned untouched, so `?` queries and Bun's own
+ * tagged-template output are unaffected.
+ */
+export declare function bindNumberedPlaceholders(sql: string, params: any[]): { sql: string, params: any[] };
 export declare function splitSqlStatements(sql: string): string[];
 /**
  * Creates a database connection string based on the configured dialect and database settings.
@@ -98,10 +127,6 @@ export declare interface DriverConnection {
 }
 /** An `unsafe(...)` result: a query object that is ALSO directly awaitable. */
 export type AwaitableDriverQuery = DriverQuery & PromiseLike<any>;
-/**
- * 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[];

package/dist/faker-compat.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Wrap a ts-faker instance in the surface factories are written against.
+ *
+ * Returned as `FactoryFaker` rather than as the underlying type, because the
+ * point of the wrapper is that it is a different shape - a caller typed against
+ * ts-faker would be told `helpers.arrayElement` does not exist, which is the
+ * error this module exists to remove.
+ */
+export declare function createFakerCompatLayer(underlying: Record<string, any>): FactoryFaker;
+/**
+ * The faker a factory is actually handed.
+ *
+ * Model factories in this ecosystem are written in the faker-js dialect - it is
+ * what every example, every scaffolded model and a decade of muscle memory
+ * produce:
+ *
+ * ```ts
+ * factory: faker => faker.helpers.arrayElement(['draft', 'published']),
+ * factory: faker => faker.string.alphanumeric(12),
+ * factory: faker => faker.datatype.number({ min: 1, max: 10 }),
+ * ```
+ *
+ * `@stacksjs/ts-faker` is a different, smaller surface: no `helpers.arrayElement`,
+ * no `datatype`, `address` rather than `location`, `catchphrase` rather than
+ * `catchPhrase`, and options objects where faker-js takes a bare number. Handing
+ * a factory the raw instance means `arrayElement is not a function` at seed
+ * time - and it is a *runtime* failure in the one code path nobody runs until
+ * they are setting up a new environment.
+ *
+ * So this module adapts one to the other, and exports the adapted shape as a
+ * type. Both halves matter: without the proxy the calls throw, and without the
+ * type every one of those factories is a type error in a codebase that
+ * typechecks.
+ *
+ * **Everything here is a translation, never an invention.** Where ts-faker has
+ * no equivalent at all the method is built from what it does have (a slug from
+ * `lorem.slug`, a registration from `vehicle.registration`), because a factory
+ * that returns a plausible wrong-shaped string is better than a seeder that
+ * stops.
+ */
+/** What faker-js calls a string generator's options, and what ts-faker wants. */
+export declare interface CompatStringOptions {
+  length?: number
+  casing?: 'upper' | 'lower' | 'mixed'
+}
+/** What faker-js passes to a number generator. */
+export declare interface CompatNumberOptions {
+  min?: number
+  max?: number
+  fractionDigits?: number
+  multipleOf?: number
+}
+/**
+ * The faker-js-shaped surface a factory receives.
+ *
+ * Deliberately loose on the modules this file does not translate: they are
+ * forwarded to ts-faker untouched, and describing them here would be a second
+ * copy of ts-faker's own types that goes stale on its next release. What is
+ * spelled out is exactly what the compat layer adds or changes.
+ */
+export declare interface FactoryFaker {
+  [module: string]: any
+  location: Record<string, (...args: any[]) => any>
+  datatype: {
+    boolean: (options?: number | { probability?: number }) => boolean
+    number: (options?: number | CompatNumberOptions) => number
+    float: (options?: CompatNumberOptions) => number
+    uuid: () => string
+    string: (length?: number) => string
+    hexadecimal: (options?: number | CompatStringOptions) => string
+    array: (length?: number) => unknown[]
+    json: () => string
+  }
+  helpers: {
+    arrayElement: <T>(items: readonly T[]) => T
+    arrayElements: <T>(items: readonly T[], count?: number) => T[]
+    shuffle: <T>(items: readonly T[]) => T[]
+    maybe: <T>(produce: () => T, options?: { probability?: number }) => T | undefined
+    slugify: (text: string) => string
+    replaceSymbols: (pattern: string) => string
+    [method: string]: any
+  }
+}

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from './dynamodb-single-table';
 export * from './dynamodb-tooling-adapter';
 export * from './dynamodb/index';
 export * from './factory';
+export * from './faker-compat';
 export * from './inflect';
 export * from './loader';
 export * from './meta';

package/dist/orm.d.ts

@@ -1,5 +1,5 @@
 import { Database, type SQLQueryBindings } from 'bun:sqlite';
-import type { Faker } from '@stacksjs/ts-faker';
+import type { FactoryFaker } from './faker-compat';
 import type { RelationCardinality } from './type-inference';
 import type { SupportedDialect } from './types';
 export type {
@@ -56,7 +56,7 @@ export declare interface TypedAttribute<T = unknown> {
     rule: unknown
     message?: Record<string, string>
   }
-  factory?: (faker: Faker) => InferType<T>
+  factory?: (faker: FactoryFaker) => InferType<T>
 }
 /** Structural type for model instances passed to lifecycle hooks. */
 // eslint-disable-next-line ts/no-empty-object-type
@@ -237,7 +237,7 @@ declare type InferType<T> = T extends keyof PrimitiveTypeMap ? PrimitiveTypeMap[
 declare type AttributeKeys<TDef extends ModelDefinition> = keyof TDef['attributes'] & string;
 // Infer single attribute type
 declare type InferAttributeType<TAttr> = TAttr extends { type: infer T } ? InferType<T> :
-  TAttr extends { factory: (faker: Faker) => infer R }
+  TAttr extends { factory: (faker: FactoryFaker) => infer R }
     ? [Exclude<R, null | undefined>] extends [never]
       ? TAttr extends { validation: { rule: infer V } } ? InferType<V> | Extract<R, null | undefined> : R
       : R

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-import type { Faker } from '@stacksjs/ts-faker';
+import type { FactoryFaker } from './faker-compat';
 /**
  * # `defineModel(model)`
  *
@@ -62,7 +62,7 @@ export declare interface Attribute {
   fillable?: boolean
   guarded?: boolean
   foreignKey?: boolean | ForeignKeyConfig
-  factory?: (faker: Faker) => unknown
+  factory?: (faker: FactoryFaker) => unknown
   validation: {
     rule: ValidationType
     message?: ValidatorMessage

package/dist/sql-fragments.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Render a WHERE body (without the `WHERE` keyword) from an ordered term list.
+ *
+ * Each MAXIMAL RUN of `OR` terms is bracketed together with the term that opens
+ * it, so a chain groups the way it reads:
+ *
+ *     .where(a).where(b).orWhere(c)   ->  a AND (b OR c)
+ *     .where(a).orWhere(b).where(c)   ->  (a OR b) AND c
+ *
+ * In effect `OR` binds TIGHTER than `AND` in chain order — the inverse of raw
+ * SQL. That is a deliberate choice for a fluent builder, and it is already what
+ * `whereAny`/`whereAll`/`whereNone` and the ORM's `whereGroup` do; `orWhere`
+ * was the odd one out. Previously the terms were concatenated as flat text and
+ * SQL's precedence re-associated `a AND b OR c` to `(a AND b) OR c`, so the
+ * first filter stopped applying to any row the `OR` matched — silently, and in
+ * the direction that returns MORE rows.
+ *
+ * The brackets are omitted when the body has a single top-level piece, so a
+ * plain two-term `.where(a).orWhere(b)` and any all-`AND` chain still render
+ * byte-for-byte as before. The escape hatch for the one shape this rule can no
+ * longer express directly — `(a AND b) OR c` — is `whereGroup(cb)`.
+ */
+export declare function renderWhereTerms(terms: readonly WhereTerm[]): string;
+/**
+ * Render `col IN (…)` / `col NOT IN (…)`, including the empty case.
+ *
+ * An empty `IN` is FALSE (nothing is a member of the empty set) and an empty
+ * `NOT IN` is TRUE (everything is a non-member). Those constants are not
+ * interchangeable and the mirror is easy to get backwards: writing FALSE for
+ * `NOT IN` would silently drop every row from any query whose exclusion list
+ * happened to come back empty — the same shape of silent, widening-or-narrowing
+ * failure as the `IN ()` bug itself.
+ */
+export declare function renderInPredicate(column: string, values: any[], negated: boolean, placeholders: string): string;
+/**
+ * Constant predicates, for the cases where a collection is empty.
+ *
+ * `1 = 0` and `1 = 1` take no parameters and parse identically on SQLite,
+ * Postgres and MySQL, which is the point: the alternatives are engine-specific.
+ * `IN ()` is the example that motivated these — SQLite parses it and matches
+ * nothing, while Postgres and MySQL reject it as a syntax error, so the same
+ * call site behaved differently depending on where it ran.
+ */
+export declare const FALSE_PREDICATE: '1 = 0';
+export declare const TRUE_PREDICATE: '1 = 1';
+/**
+ * SQL fragment renderers shared by the select builder (`client.ts`) and the ORM
+ * query builder (`orm.ts`).
+ *
+ * They live here rather than in either builder because the two had independent
+ * copies of the same defect: both joined their WHERE terms as flat text, so
+ * `orWhere` produced an ungrouped `OR` and SQL's native precedence silently
+ * re-associated the chain. Two implementations of one rule is how they drifted;
+ * one implementation is how they stop.
+ *
+ * See stacksjs/bun-query-builder#1083.
+ */
+/**
+ * A single WHERE predicate plus the connector the CALLER asked for.
+ *
+ * The connector belongs to the term rather than sitting between terms because
+ * the first term's connector is meaningless — nothing precedes it — and
+ * carrying it anyway is what lets a leading `.orWhere(x)` render as `WHERE x`
+ * instead of the `FROM t OR x` syntax error it used to emit.
+ */
+export declare interface WhereTerm {
+  conn: 'AND' | 'OR'
+  sql: string
+}