@bunyad/orm 0.1.0-alpha.0

package/dist/model-query.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Fluent query builder returned by Model.query() / newQuery().
+ */
+import type { DateInput, QueryBuilder } from "@bunyad/database";
+import { CursorPaginator, LengthAwarePaginator, Paginator } from "@bunyad/database";
+import { Collection } from "@bunyad/common";
+import { OrmCollection } from "./orm-collection.js";
+import { type CastDefinition } from "./casts.js";
+import { Model, type ModelClass, type ModelQueryOptions } from "./model.js";
+/**
+ * Local-scope Proxy exposes this so callers can reach the real `ModelQuery`
+ * (private fields are not accessible through a Proxy).
+ */
+export declare const MODEL_QUERY_TARGET: unique symbol;
+/** Unwrap a local-scope Proxy to the underlying `ModelQuery` instance. */
+export declare function unwrapModelQuery<Q extends ModelQuery>(query: Q): Q;
+export declare class ModelQuery<T extends Model = Model, TResult extends "model" | "row" = "model"> {
+    #private;
+    private model;
+    constructor(model: ModelClass, options?: ModelQueryOptions);
+    /** `get()` returns plain row objects. Models are not built. */
+    rows(): ModelQuery<T, "row">;
+    /** Laravel `withoutGlobalScopes`. */
+    withoutGlobalScopes(names?: string[]): this;
+    /** Laravel `withoutGlobalScope`. */
+    withoutGlobalScope(name: string): this;
+    /** Laravel `withTrashed()`. */
+    withTrashed(): this;
+    /** Laravel `onlyTrashed()`. */
+    onlyTrashed(): this;
+    /** Laravel `withoutTrashed()`. */
+    withoutTrashed(): this;
+    /**
+     * Laravel `Builder::withAttributes` — pending attrs for `create()`, and
+     * matching `where` conditions when `asConditions` is true (default).
+     */
+    withAttributes(attributes: Record<string, unknown> | string, valueOrAsConditions?: unknown, asConditions?: boolean): this;
+    /** Laravel `withCasts` — merge query-time casts for hydration. */
+    withCasts(casts: Record<string, CastDefinition>): this;
+    /** Laravel `has`. */
+    has(relation: string): this;
+    /** Laravel `doesntHave`. */
+    doesntHave(relation: string): this;
+    /** Laravel `whereHas`. */
+    whereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    /** Laravel `orWhereHas`. */
+    orWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    /** Laravel `whereDoesntHave`. */
+    whereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
+    /** Laravel `orWhereDoesntHave`. */
+    orWhereDoesntHave(relation: string, callback?: (query: ModelQuery) => void): this;
+    /**
+     * Laravel `whereRelation($relation, $column, $operator = null, $value = null)`.
+     * Convenience wrapper around `whereHas` with a column constraint.
+     */
+    whereRelation(relation: string, column: string, opOrValue: unknown, value?: unknown): this;
+    /** Laravel `orWhereRelation`. */
+    orWhereRelation(relation: string, column: string, opOrValue: unknown, value?: unknown): this;
+    /** Laravel `orHas`. */
+    orHas(relation: string): this;
+    /** Laravel `orDoesntHave`. */
+    orDoesntHave(relation: string): this;
+    /**
+     * Laravel `whereBelongsTo($model, $relationshipName = null)`.
+     * Constrains by the foreign key of a belongsTo relation.
+     */
+    whereBelongsTo(related: Model, relationName?: string): this;
+    /** Laravel `orWhereBelongsTo`. */
+    orWhereBelongsTo(related: Model, relationName?: string): this;
+    /**
+     * Laravel `whereMorphedTo($relation, $model)`.
+     */
+    whereMorphedTo(relation: string, model: Model): this;
+    orWhereMorphedTo(relation: string, model: Model): this;
+    whereNotMorphedTo(relation: string, model: Model): this;
+    orWhereNotMorphedTo(relation: string, model: Model): this;
+    /**
+     * Laravel `whereMorphRelation($relation, $types, $column, …)` — simplified:
+     * `whereMorphRelation('commentable', TypeModel, column, op?, value?)`.
+     */
+    whereMorphRelation(relation: string, type: ModelClass, column: string, opOrValue: unknown, value?: unknown): this;
+    orWhereMorphRelation(relation: string, type: ModelClass, column: string, opOrValue: unknown, value?: unknown): this;
+    /**
+     * Laravel `whereHasMorph($relation, $types, $callback?)`.
+     * `$types` may be a single model class or an array.
+     */
+    whereHasMorph(relation: string, types: ModelClass | ModelClass[], callback?: (query: ModelQuery) => void): this;
+    orWhereHasMorph(relation: string, types: ModelClass | ModelClass[], callback?: (query: ModelQuery) => void): this;
+    whereDoesntHaveMorph(relation: string, types: ModelClass | ModelClass[], callback?: (query: ModelQuery) => void): this;
+    orWhereDoesntHaveMorph(relation: string, types: ModelClass | ModelClass[], callback?: (query: ModelQuery) => void): this;
+    hasMorph(relation: string, types: ModelClass | ModelClass[]): this;
+    doesntHaveMorph(relation: string, types: ModelClass | ModelClass[]): this;
+    /**
+     * Laravel `withWhereHas($relation, $callback?)` — whereHas + eager with same constraint.
+     */
+    withWhereHas(relation: string, callback?: (query: ModelQuery) => void): this;
+    /** Laravel `whereAny` (forwarded to query builder). */
+    whereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
+    orWhereAny(columns: string[], opOrValue: unknown, value?: unknown): this;
+    whereAll(columns: string[], opOrValue: unknown, value?: unknown): this;
+    orWhereAll(columns: string[], opOrValue: unknown, value?: unknown): this;
+    whereNone(columns: string[], opOrValue: unknown, value?: unknown): this;
+    orWhereNone(columns: string[], opOrValue: unknown, value?: unknown): this;
+    /** Laravel `whereKey($id)` / `whereKey([$ids])`. */
+    whereKey(id: string | number | Array<string | number>): this;
+    /** Laravel `whereKeyNot`. */
+    whereKeyNot(id: string | number | Array<string | number>): this;
+    /** Laravel `whereUuid($column, $uuid)`. */
+    whereUuid(column: string, value: string): this;
+    /** Laravel `whereUlid($column, $ulid)`. */
+    whereUlid(column: string, value: string): this;
+    /** Laravel `whereNot(closure)` nested group. */
+    whereNot(callback: (query: ModelQuery<T>) => void): this;
+    orWhereNot(callback: (query: ModelQuery<T>) => void): this;
+    /** Laravel `firstWhere`. */
+    firstWhere(column: string, value: unknown): T | null | Promise<T | null>;
+    firstWhere(column: string, op: string, value: unknown): T | null | Promise<T | null>;
+    /** Laravel `findMany`. */
+    findMany(ids: Array<string | number>): OrmCollection<T> | Promise<OrmCollection<T>>;
+    /** Laravel `findOr($id, $callback)`. */
+    findOr(id: string | number, callback: () => T | Promise<T>): Promise<T>;
+    /** Laravel `findOrNew`. */
+    findOrNew(id: string | number): Promise<T>;
+    /** Laravel `firstOr($callback)`. */
+    firstOr(callback: () => T | Promise<T>): Promise<T>;
+    /** Laravel `valueOrFail`. */
+    valueOrFail(column: string): Promise<unknown>;
+    /** Laravel `soleValue`. */
+    soleValue(column: string): Promise<unknown>;
+    /** `withCount` — `'posts'`, `'posts as post_total'`, a string list, or `{ products: { as: 'productsCount' } }`. */
+    withCount(...relations: Array<string | string[] | Record<string, true | string | ((query: ModelQuery) => void) | {
+        as?: string;
+    }>>): this;
+    /** Laravel `withSum($relation, $column)`. */
+    withSum(relation: string, column: string): this;
+    withAvg(relation: string, column: string): this;
+    withMin(relation: string, column: string): this;
+    withMax(relation: string, column: string): this;
+    /** Laravel `withExists($relation)`. */
+    withExists(...relations: string[]): this;
+    /** Laravel `withAggregate($relation, $column, $function)`. */
+    withAggregate(relation: string, column: string, fn: "count" | "sum" | "avg" | "min" | "max"): this;
+    /** Laravel Eloquent `join` (hydrated models still from the base table). */
+    join(table: string, first: string, op: string, second: string): this;
+    /** Laravel `leftJoin`. */
+    leftJoin(table: string, first: string, op: string, second: string): this;
+    /** Laravel `rightJoin`. */
+    rightJoin(table: string, first: string, op: string, second: string): this;
+    where(callback: (query: ModelQuery<T>) => void): this;
+    where(column: string, value: unknown): this;
+    where(column: string, op: string, value: unknown): this;
+    orWhere(callback: (query: ModelQuery<T>) => void): this;
+    orWhere(column: string, value: unknown): this;
+    orWhere(column: string, op: string, value: unknown): this;
+    whereIn(column: string, values: unknown[]): this;
+    orWhereIn(column: string, values: unknown[]): this;
+    whereNotIn(column: string, values: unknown[]): this;
+    orWhereNotIn(column: string, values: unknown[]): this;
+    whereNull(column: string): this;
+    orWhereNull(column: string): this;
+    whereNotNull(column: string): this;
+    orWhereNotNull(column: string): this;
+    whereBetween(column: string, values: [unknown, unknown]): this;
+    orWhereBetween(column: string, values: [unknown, unknown]): this;
+    whereNotBetween(column: string, values: [unknown, unknown]): this;
+    orWhereNotBetween(column: string, values: [unknown, unknown]): this;
+    whereColumn(first: string, second: string): this;
+    whereColumn(first: string, op: string, second: string): this;
+    orWhereColumn(first: string, second: string): this;
+    orWhereColumn(first: string, op: string, second: string): this;
+    whereRaw(sql: string, bindings?: unknown[]): this;
+    orWhereRaw(sql: string, bindings?: unknown[]): this;
+    whereLike(column: string, value: string, caseSensitive?: boolean): this;
+    orWhereLike(column: string, value: string, caseSensitive?: boolean): this;
+    whereNotLike(column: string, value: string, caseSensitive?: boolean): this;
+    orWhereNotLike(column: string, value: string, caseSensitive?: boolean): this;
+    /** Laravel `whereDate` — same on SQLite / Postgres / MySQL. */
+    whereDate(column: string, value: DateInput): this;
+    whereDate(column: string, op: string, value: DateInput): this;
+    whereYear(column: string, value: number): this;
+    whereMonth(column: string, value: number): this;
+    whereDay(column: string, value: number): this;
+    select(...columns: string[]): this;
+    addSelect(...columns: string[]): this;
+    selectRaw(expression: string, bindings?: unknown[]): this;
+    distinct(value?: boolean): this;
+    orderBy(column: string, direction?: "asc" | "desc"): this;
+    orderByDesc(column: string): this;
+    orderByRaw(sql: string): this;
+    /** Karobar / dialect alias for `orderByRaw`. */
+    orderBySql(sql: string): this;
+    reorder(column?: string, direction?: "asc" | "desc"): this;
+    inRandomOrder(): this;
+    latest(column?: string): this;
+    oldest(column?: string): this;
+    groupBy(...columns: string[]): this;
+    having(column: string, op: string, value: unknown): this;
+    havingRaw(sql: string, bindings?: unknown[]): this;
+    limit(value: number): this;
+    take(value: number): this;
+    offset(value: number): this;
+    skip(value: number): this;
+    forPage(page: number, perPage?: number): this;
+    lockForUpdate(): this;
+    sharedLock(): this;
+    when(condition: unknown, callback: (query: this) => void, defaultCallback?: (query: this) => void): this;
+    /**
+     * OR `LIKE %term%` across columns (Karobar list `search`).
+     * Empty/whitespace term is a no-op.
+     */
+    search(columns: string[], term: string): this;
+    unless(condition: unknown, callback: (query: this) => void, defaultCallback?: (query: this) => void): this;
+    tap(callback: (query: this) => void): this;
+    clone(): ModelQuery<T, TResult>;
+    with(...relations: Array<string | string[] | Record<string, unknown>>): this;
+    /** Underlying query builder (fresh compile each call). */
+    toBase(): QueryBuilder;
+    /** Compiled SQL (bindings via `getBindings()`). */
+    toSql(): string;
+    /** SQL with bindings interpolated for debugging. */
+    toRawSql(): string;
+    getBindings(): unknown[];
+    dump(): this;
+    dd(): never;
+    /**
+     * Prefix unqualified columns with `table.` (BelongsTo whereHas → JOIN path).
+     */
+    qualifyColumns(table: string): this;
+    /** Apply this query's wheres onto a QueryBuilder (exists subqueries). */
+    applyConstraintsTo(q: QueryBuilder): QueryBuilder;
+    first(): T | null | Promise<T | null>;
+    /** Laravel `firstOrFail`. */
+    firstOrFail(): Promise<T>;
+    /**
+     * Fetch matching models as an {@link OrmCollection}.
+     * After {@link rows}, returns plain row objects and does not build models.
+     * For synchronous SQLite reads, use {@link getSync}.
+     */
+    get(): TResult extends "row" ? Record<string, unknown>[] | Promise<Record<string, unknown>[]> : OrmCollection<T> | Promise<OrmCollection<T>>;
+    /**
+     * SQLite-only synchronous `get()`.
+     * No `with()` / retrieved events — for desktop hot paths that cannot await.
+     */
+    getSync(): TResult extends "row" ? Record<string, unknown>[] : OrmCollection<T>;
+    /** SQLite-only synchronous `first()`. */
+    firstSync(): T | null;
+    /** SQLite-only synchronous `find($id)`. */
+    findSync(id: string | number): T | null;
+    /** Laravel `Builder::create` — insert on this query's connection. */
+    create(attributes: Record<string, unknown>): Promise<T>;
+    paginate(perPage?: number, page?: number, options?: {
+        path?: string;
+        pageName?: string;
+    }): Promise<LengthAwarePaginator<T>>;
+    /** No total count; extra row is used to detect a next page. */
+    simplePaginate(perPage?: number, page?: number, options?: {
+        path?: string;
+        pageName?: string;
+    }): Promise<Paginator<T>>;
+    /** Laravel `chunk($count, $callback)`. */
+    chunk(count: number, callback: (models: OrmCollection<T>) => void | Promise<void>): Promise<void>;
+    /** Laravel `lazy($chunkSize)`. */
+    lazy(chunkSize?: number): AsyncGenerator<T, void, unknown>;
+    /** Laravel `chunkById`. */
+    chunkById(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
+    chunkByIdDesc(count: number, callback: (models: OrmCollection<T>) => void | boolean | Promise<void | boolean>, column?: string): Promise<boolean>;
+    /** Laravel `lazyById`. */
+    lazyById(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
+    lazyByIdDesc(chunkSize?: number, column?: string): AsyncGenerator<T, void, unknown>;
+    increment(column: string, amount?: number): Promise<void>;
+    decrement(column: string, amount?: number): Promise<void>;
+    /** Laravel `cursorPaginate`. */
+    cursorPaginate(perPage?: number, cursor?: string | null, options?: {
+        path?: string;
+        cursorName?: string;
+    }): Promise<CursorPaginator<T>>;
+    /** Laravel `Builder::count($columns = '*')` — honors `distinct()` for non-`*`. */
+    count(column?: string): Promise<number>;
+    exists(): Promise<boolean>;
+    doesntExist(): Promise<boolean>;
+    /** Find by primary key within this query. */
+    find(id: string | number): Promise<T | null>;
+    findOrFail(id: string | number): Promise<T>;
+    /** Exactly one matching model, or throw. */
+    sole(): Promise<T>;
+    value(column: string): Promise<unknown>;
+    /**
+     * Laravel `Builder::pluck($column, $key = null)`.
+     * One column → list {@link Collection}. With `key`, selects both columns and
+     * returns a keyed plain object via {@link Collection.pluck} (Laravel assoc map).
+     */
+    pluck(column: string): Promise<Collection<unknown>>;
+    pluck(column: string, key: string): Promise<Record<string, unknown>>;
+    sum(column: string): Promise<number>;
+    avg(column: string): Promise<number | null>;
+    min(column: string): Promise<unknown>;
+    max(column: string): Promise<unknown>;
+    /**
+     * Bulk insert. When the model uses timestamps, stamps `created_at`/`updated_at`
+     * (row values win). Does not fire creating/created events.
+     */
+    insert(values: Record<string, unknown> | Record<string, unknown>[]): Promise<boolean>;
+    /**
+     * Laravel `Builder::upsert` — insert or update on unique conflict.
+     * When the model uses timestamps, stamps `created_at`/`updated_at` like Eloquent
+     * (row values win; `updated_at` is always included in the update column list).
+     */
+    upsert(values: Record<string, unknown> | Record<string, unknown>[], uniqueBy: string | string[], update?: string[] | null): Promise<number>;
+    update(values: Record<string, unknown>): Promise<number>;
+    delete(): Promise<number>;
+    forceDelete(): Promise<number>;
+}