@zudojs/database 0.0.1 → 1.0.0

package/dist/queryBuilder/queryBuilder.core.d.ts

@@ -0,0 +1,178 @@
+import type { QueryOperator, QueryFilter, QueryBuilderState, PaginationInput, SortDirection, SortInput, QueryOptions } from "./queryBuilder.type.js";
+import { type PrismaQueryArgs, type ToPrismaArgsOptions } from "./queryBuilder.prisma.js";
+import { type RelationInclude } from "../relations/relations.definition.js";
+/**
+ * Query builder used to construct database-neutral query definitions.
+ *
+ * The builder does not execute queries. It produces a plain query
+ * definition that repositories or adapters can translate into their
+ * ORM-specific representation.
+ */
+export declare class QueryBuilder<TField extends string = string> {
+    private filterState?;
+    private paginationState?;
+    private sortState;
+    private selectState;
+    private offsetState?;
+    private includeState;
+    private _cachedBuild?;
+    private invalidateCache;
+    /**
+     * Adds an equality condition.
+     */
+    where(field: TField, value: unknown): this;
+    /**
+     * Adds a condition using a specific operator.
+     */
+    whereOperator(field: TField, operator: QueryOperator, value?: unknown): this;
+    /**
+     * Adds a not-equal condition.
+     */
+    whereNot(field: TField, value: unknown): this;
+    /**
+     * Adds an IN condition.
+     */
+    whereIn(field: TField, values: readonly unknown[]): this;
+    /**
+     * Adds a NOT IN condition.
+     */
+    whereNotIn(field: TField, values: readonly unknown[]): this;
+    /**
+     * Adds a less-than condition.
+     */
+    whereLessThan(field: TField, value: unknown): this;
+    /**
+     * Adds a less-than-or-equal condition.
+     */
+    whereLessThanOrEqual(field: TField, value: unknown): this;
+    /**
+     * Adds a greater-than condition.
+     */
+    whereGreaterThan(field: TField, value: unknown): this;
+    /**
+     * Adds a greater-than-or-equal condition.
+     */
+    whereGreaterThanOrEqual(field: TField, value: unknown): this;
+    /**
+     * Adds a contains condition.
+     */
+    whereContains(field: TField, value: string): this;
+    /**
+     * Adds a starts-with condition.
+     */
+    whereStartsWith(field: TField, value: string): this;
+    /**
+     * Adds an ends-with condition.
+     */
+    whereEndsWith(field: TField, value: string): this;
+    /**
+     * Adds an IS NULL condition.
+     */
+    whereNull(field: TField): this;
+    /**
+     * Adds an IS NOT NULL condition.
+     */
+    whereNotNull(field: TField): this;
+    /**
+     * Adds an AND group.
+     */
+    and(...filters: QueryFilter[]): this;
+    /**
+     * Adds an OR group.
+     */
+    or(...filters: QueryFilter[]): this;
+    /**
+     * Adds a NOT group.
+     */
+    not(filter: QueryFilter): this;
+    /**
+     * Sets the requested page.
+     */
+    page(page: number): this;
+    /**
+     * Sets the requested page size.
+     */
+    limit(limit: number): this;
+    /**
+     * Sets pagination.
+     */
+    paginate(pagination: PaginationInput): this;
+    /**
+     * Sets an explicit row offset. Takes precedence over `page()`.
+     */
+    offset(offset: number): this;
+    /**
+     * Adds relations to include. Accepts relation names or include
+     * definitions created with `includeRelation`.
+     */
+    include(...relations: readonly (string | RelationInclude)[]): this;
+    /**
+     * Sorts ascending by a field.
+     */
+    orderByAsc(field: TField): this;
+    /**
+     * Sorts descending by a field.
+     */
+    orderByDesc(field: TField): this;
+    /**
+     * Adds a sort definition.
+     */
+    orderBy(field: TField, direction?: SortDirection): this;
+    /**
+     * Replaces all sort definitions.
+     */
+    sort(sort: readonly SortInput<TField>[]): this;
+    /**
+     * Selects specific fields.
+     */
+    select(...fields: TField[]): this;
+    /**
+     * Clears all filters.
+     */
+    clearFilters(): this;
+    /**
+     * Clears pagination.
+     */
+    clearPagination(): this;
+    /**
+     * Clears sorting.
+     */
+    clearSort(): this;
+    /**
+     * Clears selected fields.
+     */
+    clearSelect(): this;
+    /**
+     * Clears included relations.
+     */
+    clearInclude(): this;
+    /**
+     * Resets the builder to its initial empty state.
+     */
+    reset(): this;
+    /**
+     * Returns the immutable query definition.
+     */
+    build(): QueryBuilderState<TField>;
+    /**
+     * Converts the builder into generic query options (pagination, sort and
+     * the built filter).
+     */
+    toQueryOptions(): QueryOptions<TField> & {
+        readonly filter?: QueryFilter;
+        readonly offset?: number;
+    };
+    /**
+     * Translates the builder into Prisma `findMany`-style arguments.
+     */
+    toPrismaArgs(options?: ToPrismaArgsOptions): PrismaQueryArgs;
+    /**
+     * Creates an independent copy of the builder.
+     */
+    clone(): QueryBuilder<TField>;
+    /**
+     * Adds a condition to the current filter.
+     */
+    private addCondition;
+}
+//# sourceMappingURL=queryBuilder.core.d.ts.map

package/dist/queryBuilder/queryBuilder.core.js

@@ -0,0 +1,420 @@
+import { cloneFilter } from "./queryBuilder.filter.js";
+import { toPrismaArgs, } from "./queryBuilder.prisma.js";
+import { includeRelation, } from "../relations/relations.definition.js";
+/**
+ * Query builder used to construct database-neutral query definitions.
+ *
+ * The builder does not execute queries. It produces a plain query
+ * definition that repositories or adapters can translate into their
+ * ORM-specific representation.
+ */
+export class QueryBuilder {
+    filterState;
+    paginationState;
+    sortState = [];
+    selectState = [];
+    offsetState;
+    includeState = [];
+    _cachedBuild;
+    invalidateCache() {
+        this._cachedBuild = undefined;
+    }
+    /**
+     * Adds an equality condition.
+     */
+    where(field, value) {
+        return this.addCondition({
+            field,
+            operator: "equals",
+            value,
+        });
+    }
+    /**
+     * Adds a condition using a specific operator.
+     */
+    whereOperator(field, operator, value) {
+        return this.addCondition({
+            field,
+            operator,
+            value,
+        });
+    }
+    /**
+     * Adds a not-equal condition.
+     */
+    whereNot(field, value) {
+        return this.whereOperator(field, "not", value);
+    }
+    /**
+     * Adds an IN condition.
+     */
+    whereIn(field, values) {
+        return this.whereOperator(field, "in", [...values]);
+    }
+    /**
+     * Adds a NOT IN condition.
+     */
+    whereNotIn(field, values) {
+        return this.whereOperator(field, "notIn", [...values]);
+    }
+    /**
+     * Adds a less-than condition.
+     */
+    whereLessThan(field, value) {
+        return this.whereOperator(field, "lt", value);
+    }
+    /**
+     * Adds a less-than-or-equal condition.
+     */
+    whereLessThanOrEqual(field, value) {
+        return this.whereOperator(field, "lte", value);
+    }
+    /**
+     * Adds a greater-than condition.
+     */
+    whereGreaterThan(field, value) {
+        return this.whereOperator(field, "gt", value);
+    }
+    /**
+     * Adds a greater-than-or-equal condition.
+     */
+    whereGreaterThanOrEqual(field, value) {
+        return this.whereOperator(field, "gte", value);
+    }
+    /**
+     * Adds a contains condition.
+     */
+    whereContains(field, value) {
+        return this.whereOperator(field, "contains", value);
+    }
+    /**
+     * Adds a starts-with condition.
+     */
+    whereStartsWith(field, value) {
+        return this.whereOperator(field, "startsWith", value);
+    }
+    /**
+     * Adds an ends-with condition.
+     */
+    whereEndsWith(field, value) {
+        return this.whereOperator(field, "endsWith", value);
+    }
+    /**
+     * Adds an IS NULL condition.
+     */
+    whereNull(field) {
+        return this.whereOperator(field, "isNull");
+    }
+    /**
+     * Adds an IS NOT NULL condition.
+     */
+    whereNotNull(field) {
+        return this.whereOperator(field, "isNotNull");
+    }
+    /**
+     * Adds an AND group.
+     */
+    and(...filters) {
+        const existing = this.filterState;
+        const group = {
+            and: filters,
+        };
+        this.filterState = existing
+            ? {
+                and: [existing, group],
+            }
+            : group;
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Adds an OR group.
+     */
+    or(...filters) {
+        const existing = this.filterState;
+        const group = {
+            or: filters,
+        };
+        this.filterState = existing
+            ? {
+                and: [existing, group],
+            }
+            : group;
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Adds a NOT group.
+     */
+    not(filter) {
+        const existing = this.filterState;
+        const group = {
+            not: filter,
+        };
+        this.filterState = existing
+            ? {
+                and: [existing, group],
+            }
+            : group;
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Sets the requested page.
+     */
+    page(page) {
+        this.paginationState = {
+            ...this.paginationState,
+            page,
+        };
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Sets the requested page size.
+     */
+    limit(limit) {
+        this.paginationState = {
+            ...this.paginationState,
+            limit,
+        };
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Sets pagination.
+     */
+    paginate(pagination) {
+        this.paginationState = {
+            ...pagination,
+        };
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Sets an explicit row offset. Takes precedence over `page()`.
+     */
+    offset(offset) {
+        if (!Number.isFinite(offset) || offset < 0) {
+            throw new TypeError("Query offset must be a non-negative number.");
+        }
+        this.offsetState = Math.floor(offset);
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Adds relations to include. Accepts relation names or include
+     * definitions created with `includeRelation`.
+     */
+    include(...relations) {
+        for (const relation of relations) {
+            const include = typeof relation === "string" ? includeRelation(relation) : relation;
+            if (!include || typeof include.relation !== "string") {
+                throw new TypeError("A relation include is required.");
+            }
+            if (!this.includeState.some((e) => e.relation === include.relation)) {
+                this.includeState.push(include);
+            }
+        }
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Sorts ascending by a field.
+     */
+    orderByAsc(field) {
+        return this.orderBy(field, "asc");
+    }
+    /**
+     * Sorts descending by a field.
+     */
+    orderByDesc(field) {
+        return this.orderBy(field, "desc");
+    }
+    /**
+     * Adds a sort definition.
+     */
+    orderBy(field, direction = "asc") {
+        this.sortState.push({
+            field,
+            direction,
+        });
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Replaces all sort definitions.
+     */
+    sort(sort) {
+        this.sortState = [...sort];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Selects specific fields.
+     */
+    select(...fields) {
+        this.selectState = [...new Set(fields)];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Clears all filters.
+     */
+    clearFilters() {
+        this.filterState = undefined;
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Clears pagination.
+     */
+    clearPagination() {
+        this.paginationState = undefined;
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Clears sorting.
+     */
+    clearSort() {
+        this.sortState = [];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Clears selected fields.
+     */
+    clearSelect() {
+        this.selectState = [];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Clears included relations.
+     */
+    clearInclude() {
+        this.includeState = [];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Resets the builder to its initial empty state.
+     */
+    reset() {
+        this.filterState = undefined;
+        this.paginationState = undefined;
+        this.offsetState = undefined;
+        this.sortState = [];
+        this.selectState = [];
+        this.includeState = [];
+        this.invalidateCache();
+        return this;
+    }
+    /**
+     * Returns the immutable query definition.
+     */
+    build() {
+        if (this._cachedBuild) {
+            return this._cachedBuild;
+        }
+        const result = deepFreeze({
+            filter: cloneFilter(this.filterState),
+            pagination: this.paginationState
+                ? { ...this.paginationState }
+                : undefined,
+            offset: this.offsetState,
+            sort: this.sortState.length > 0
+                ? this.sortState.map((entry) => ({ ...entry }))
+                : undefined,
+            select: this.selectState.length > 0 ? [...this.selectState] : undefined,
+            include: this.includeState.length > 0 ? [...this.includeState] : undefined,
+        });
+        this._cachedBuild = result;
+        return result;
+    }
+    /**
+     * Converts the builder into generic query options (pagination, sort and
+     * the built filter).
+     */
+    toQueryOptions() {
+        return {
+            filter: cloneFilter(this.filterState),
+            pagination: this.paginationState
+                ? { ...this.paginationState }
+                : undefined,
+            offset: this.offsetState,
+            sort: this.sortState.length > 0 ? [...this.sortState] : undefined,
+        };
+    }
+    /**
+     * Translates the builder into Prisma `findMany`-style arguments.
+     */
+    toPrismaArgs(options) {
+        return toPrismaArgs(this.build(), options);
+    }
+    /**
+     * Creates an independent copy of the builder.
+     */
+    clone() {
+        const builder = new QueryBuilder();
+        builder.filterState = cloneFilter(this.filterState);
+        builder.paginationState = this.paginationState
+            ? {
+                ...this.paginationState,
+            }
+            : undefined;
+        builder.offsetState = this.offsetState;
+        builder.sortState = this.sortState.map((entry) => ({ ...entry }));
+        builder.selectState = [...this.selectState];
+        builder.includeState = [...this.includeState];
+        return builder;
+    }
+    /**
+     * Adds a condition to the current filter.
+     */
+    addCondition(condition) {
+        const existing = this.filterState;
+        if (!existing) {
+            this.filterState = {
+                conditions: [condition],
+            };
+            this.invalidateCache();
+            return this;
+        }
+        if (existing.conditions && !existing.and && !existing.or && !existing.not) {
+            this.filterState = {
+                conditions: [...existing.conditions, condition],
+            };
+            this.invalidateCache();
+            return this;
+        }
+        this.filterState = {
+            and: [
+                existing,
+                {
+                    conditions: [condition],
+                },
+            ],
+        };
+        this.invalidateCache();
+        return this;
+    }
+}
+/**
+ * Recursively freezes plain objects and arrays.
+ */
+function deepFreeze(value) {
+    if (value === null || typeof value !== "object" || Object.isFrozen(value)) {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const entry of Object.values(value)) {
+        deepFreeze(entry);
+    }
+    return value;
+}
+//# sourceMappingURL=queryBuilder.core.js.map

package/dist/queryBuilder/queryBuilder.factory.d.ts

@@ -0,0 +1,6 @@
+import { QueryBuilder } from "./queryBuilder.core.js";
+/**
+ * Creates a new query builder.
+ */
+export declare function createQueryBuilder<TField extends string = string>(): QueryBuilder<TField>;
+//# sourceMappingURL=queryBuilder.factory.d.ts.map

package/dist/queryBuilder/queryBuilder.factory.js

@@ -0,0 +1,8 @@
+import { QueryBuilder } from "./queryBuilder.core.js";
+/**
+ * Creates a new query builder.
+ */
+export function createQueryBuilder() {
+    return new QueryBuilder();
+}
+//# sourceMappingURL=queryBuilder.factory.js.map