bun-query-builder 0.2.27 → 0.2.29

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/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
@@ -228,14 +228,16 @@ declare type PrimitiveTypeMap = {
 declare type InferType<T> = T extends keyof PrimitiveTypeMap ? PrimitiveTypeMap[T] :
   T extends readonly (infer U)[] ? U :
   T extends (infer U)[] ? U :
-  T extends { validate: (value: infer U) => unknown } ? U :
-  T extends { test: (value: infer U) => unknown } ? U :
-  unknown;
+  T extends { getShape: () => infer TShape extends Readonly<Record<string, unknown>> }
+    ? { -readonly [TKey in keyof TShape]: InferType<TShape[TKey]> }
+    : T extends { test: (value: infer U) => unknown } ? U :
+      T extends { validate: (value: infer U) => unknown } ? U :
+        unknown;
 // Extract attribute keys from definition
 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
@@ -370,25 +372,35 @@ declare type NumericColumns<TDef extends ModelDefinition> = {
  * and would otherwise leak its own keys ('length', indices, ...) into the
  * relation-name union.
  */
-declare type RelationKeyOf<V> = V extends readonly (infer E)[]
-    ? E extends string ? Lowercase<E>
-      : E extends { model: infer M extends string } ? Lowercase<M>
-        : never
-    : V extends Readonly<Record<infer K, unknown>>
-      ? K & string
-      : never;
+declare type RelationKeyOf<V> = V extends string
+    ? Lowercase<V>
+    : V extends readonly (infer E)[]
+      ? E extends string ? Lowercase<E>
+        : E extends { model: infer M extends string } ? Lowercase<M>
+          : never
+      : V extends Readonly<Record<infer K, unknown>>
+        ? K & string
+        : never;
 declare type InferBelongsToNames<TDef> = TDef extends { belongsTo: infer V } ? RelationKeyOf<V> : never;
 declare type InferHasManyNames<TDef> = TDef extends { hasMany: infer V } ? RelationKeyOf<V> : never;
 declare type InferHasOneNames<TDef> = TDef extends { hasOne: infer V } ? RelationKeyOf<V> : never;
 declare type InferBelongsToManyNames<TDef> = TDef extends { belongsToMany: infer V } ? RelationKeyOf<V> : never;
 declare type InferHasOneThroughNames<TDef> = TDef extends { hasOneThrough: infer V } ? RelationKeyOf<V> : never;
 declare type InferHasManyThroughNames<TDef> = TDef extends { hasManyThrough: infer V } ? RelationKeyOf<V> : never;
+declare type InferMorphOneNames<TDef> = TDef extends { morphOne: infer V } ? RelationKeyOf<V> : never;
+declare type InferMorphManyNames<TDef> = TDef extends { morphMany: infer V } ? RelationKeyOf<V> : never;
+declare type InferMorphToManyNames<TDef> = TDef extends { morphToMany: infer V } ? RelationKeyOf<V> : never;
+declare type InferMorphedByManyNames<TDef> = TDef extends { morphedByMany: infer V } ? RelationKeyOf<V> : never;
 export type InferRelationNames<TDef> = | InferBelongsToNames<TDef>
   | InferHasManyNames<TDef>
   | InferHasOneNames<TDef>
   | InferBelongsToManyNames<TDef>
   | InferHasOneThroughNames<TDef>
-  | InferHasManyThroughNames<TDef>;
+  | InferHasManyThroughNames<TDef>
+  | InferMorphOneNames<TDef>
+  | InferMorphManyNames<TDef>
+  | InferMorphToManyNames<TDef>
+  | InferMorphedByManyNames<TDef>;
 /**
  * Cardinality-aware value of a loaded relation as returned by
  * `ModelInstance.getRelation()`. Relations declared as to-many (hasMany,

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
+}