@zudojs/database 0.1.0 → 1.0.0

package/dist/queryBuilder/queryBuilder.core.js

@@ -1,4 +1,6 @@
-import { cloneFilter } from "./queryBuilder.factory.js";
+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.
  *
@@ -11,11 +13,11 @@ export class QueryBuilder {
     paginationState;
     sortState = [];
     selectState = [];
-    _revision = 0;
+    offsetState;
+    includeState = [];
     _cachedBuild;
     invalidateCache() {
         this._cachedBuild = undefined;
-        this._revision++;
     }
     /**
      * Adds an equality condition.
@@ -189,6 +191,34 @@ export class QueryBuilder {
         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.
      */
@@ -260,6 +290,27 @@ export class QueryBuilder {
         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.
      */
@@ -267,32 +318,41 @@ export class QueryBuilder {
         if (this._cachedBuild) {
             return this._cachedBuild;
         }
-        const result = Object.freeze({
+        const result = deepFreeze({
             filter: cloneFilter(this.filterState),
             pagination: this.paginationState
-                ? Object.freeze({
-                    ...this.paginationState,
-                })
+                ? { ...this.paginationState }
                 : undefined,
+            offset: this.offsetState,
             sort: this.sortState.length > 0
-                ? Object.freeze([...this.sortState])
-                : undefined,
-            select: this.selectState.length > 0
-                ? Object.freeze([...this.selectState])
+                ? 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.
+     * Converts the builder into generic query options (pagination, sort and
+     * the built filter).
      */
     toQueryOptions() {
         return {
-            pagination: this.paginationState,
+            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.
      */
@@ -304,8 +364,10 @@ export class QueryBuilder {
                 ...this.paginationState,
             }
             : undefined;
-        builder.sortState = [...this.sortState];
+        builder.offsetState = this.offsetState;
+        builder.sortState = this.sortState.map((entry) => ({ ...entry }));
         builder.selectState = [...this.selectState];
+        builder.includeState = [...this.includeState];
         return builder;
     }
     /**
@@ -339,4 +401,20 @@ export class QueryBuilder {
         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

@@ -5,29 +5,4 @@ import { QueryBuilder } from "./queryBuilder.core.js";
 export function createQueryBuilder() {
     return new QueryBuilder();
 }
-/**
- * Clones a query filter without sharing mutable arrays.
- */
-export function cloneFilter(filter) {
-    if (!filter) {
-        return undefined;
-    }
-    return {
-        conditions: filter.conditions
-            ? filter.conditions.map((condition) => ({
-                ...condition,
-                ...(Array.isArray(condition.value)
-                    ? {
-                        value: [...condition.value],
-                    }
-                    : {}),
-            }))
-            : undefined,
-        and: filter.and
-            ? filter.and.map((child) => cloneFilter(child))
-            : undefined,
-        or: filter.or ? filter.or.map((child) => cloneFilter(child)) : undefined,
-        not: filter.not ? cloneFilter(filter.not) : undefined,
-    };
-}
 //# sourceMappingURL=queryBuilder.factory.js.map

package/dist/queryBuilder/queryBuilder.filter.d.ts

@@ -0,0 +1,170 @@
+import type { QueryCondition, QueryFilter, QueryOperator, RelationOperator } from "./queryBuilder.type.js";
+/**
+ * Creates an equality filter.
+ */
+export declare function equals(field: string, value: unknown): QueryFilter;
+/**
+ * Creates a not-equal filter.
+ */
+export declare function notEquals(field: string, value: unknown): QueryFilter;
+/**
+ * Creates an IN filter.
+ */
+export declare function inList(field: string, values: readonly unknown[]): QueryFilter;
+/**
+ * Creates a NOT IN filter.
+ */
+export declare function notInList(field: string, values: readonly unknown[]): QueryFilter;
+/**
+ * Creates a less-than filter.
+ */
+export declare function lessThan(field: string, value: unknown): QueryFilter;
+/**
+ * Creates a less-than-or-equal filter.
+ */
+export declare function lessThanOrEqual(field: string, value: unknown): QueryFilter;
+/**
+ * Creates a greater-than filter.
+ */
+export declare function greaterThan(field: string, value: unknown): QueryFilter;
+/**
+ * Creates a greater-than-or-equal filter.
+ */
+export declare function greaterThanOrEqual(field: string, value: unknown): QueryFilter;
+/**
+ * Creates a contains filter.
+ */
+export declare function contains(field: string, value: string): QueryFilter;
+/**
+ * Creates a starts-with filter.
+ */
+export declare function startsWith(field: string, value: string): QueryFilter;
+/**
+ * Creates an ends-with filter.
+ */
+export declare function endsWith(field: string, value: string): QueryFilter;
+/**
+ * Creates an IS NULL filter.
+ */
+export declare function isNull(field: string): QueryFilter;
+/**
+ * Creates an IS NOT NULL filter.
+ */
+export declare function isNotNull(field: string): QueryFilter;
+/**
+ * Combines filters using AND.
+ */
+export declare function and(...filters: readonly QueryFilter[]): QueryFilter;
+/**
+ * Combines filters using OR.
+ */
+export declare function or(...filters: readonly QueryFilter[]): QueryFilter;
+/**
+ * Negates a filter.
+ */
+export declare function not(filter: QueryFilter): QueryFilter;
+/**
+ * Creates a generic filter condition.
+ */
+export declare function condition(field: string, operator: QueryOperator, value?: unknown): QueryFilter;
+/**
+ * Combines multiple filters with AND only when necessary.
+ */
+export declare function allOf(filters: readonly QueryFilter[]): QueryFilter;
+/**
+ * Combines multiple filters with OR only when necessary.
+ */
+export declare function anyOf(filters: readonly QueryFilter[]): QueryFilter;
+/**
+ * Creates a filter from a plain object.
+ *
+ * Every property becomes an equality condition.
+ */
+export declare function fromObject<T extends Record<string, unknown>>(values: T): QueryFilter;
+/**
+ * Creates filters for a date range.
+ */
+export declare function dateRange(field: string, options: {
+    readonly from?: Date;
+    readonly to?: Date;
+}): QueryFilter;
+/**
+ * Creates an inclusive range filter (`field >= from AND field <= to`).
+ */
+export declare function between(field: string, from: number | string | Date | bigint, to: number | string | Date | bigint): QueryFilter;
+/**
+ * Creates a SQL-style pattern filter using `%` wildcards.
+ *
+ * Only leading and/or trailing wildcards are supported (`%abc%`, `abc%`,
+ * `%abc`); the pattern is translated to `contains`, `startsWith`,
+ * `endsWith` or `equals` when converted for an ORM.
+ */
+export declare function matchesPattern(field: string, pattern: string): QueryFilter;
+/**
+ * Creates a filter matching null or empty-string values.
+ */
+export declare function isEmpty(field: string): QueryFilter;
+/**
+ * Creates a filter matching values that are neither null nor empty.
+ */
+export declare function isNotEmpty(field: string): QueryFilter;
+/**
+ * Creates a filter matching any timestamp on the given UTC calendar day.
+ */
+export declare function dateOnly(field: string, date: Date): QueryFilter;
+/**
+ * Creates a filter for timestamps strictly before a date.
+ */
+export declare function isBefore(field: string, date: Date): QueryFilter;
+/**
+ * Creates a filter for timestamps strictly after a date.
+ */
+export declare function isAfter(field: string, date: Date): QueryFilter;
+/**
+ * Creates an inclusive date range filter.
+ */
+export declare function isBetween(field: string, from: Date, to: Date): QueryFilter;
+/**
+ * Creates a negated single condition.
+ */
+export declare function notCondition(field: string, operator: QueryOperator, value?: unknown): QueryFilter;
+/**
+ * Creates a filter on a related entity.
+ *
+ * `some` / `every` / `none` target collection relations; `is` / `isNot`
+ * target single relations.
+ */
+export declare function relational(relation: string, filter: QueryFilter, operator?: RelationOperator): QueryFilter;
+/**
+ * Creates a filter for a value being one of several options.
+ */
+export declare function oneOf<T>(field: string, values: readonly T[]): QueryFilter;
+/**
+ * Creates a filter for a value not being one of several options.
+ */
+export declare function noneOf<T>(field: string, values: readonly T[]): QueryFilter;
+/**
+ * Creates an optional equality filter.
+ *
+ * Returns an empty filter when the value is undefined.
+ */
+export declare function optionalEquals(field: string, value: unknown): QueryFilter;
+/**
+ * Creates an optional text search filter.
+ */
+export declare function optionalContains(field: string, value?: string | null): QueryFilter;
+/**
+ * Checks whether a filter contains any actual constraints.
+ */
+export declare function hasConditions(filter?: QueryFilter): boolean;
+/**
+ * Flattens an AND-only filter into individual conditions.
+ */
+export declare function flattenAnd(filter: QueryFilter): QueryCondition[];
+/**
+ * Deeply clones a filter (conditions, nested groups, Date/array/object
+ * values) so the copy shares no mutable state with the source.
+ */
+export declare function cloneFilter(filter: QueryFilter): QueryFilter;
+export declare function cloneFilter(filter?: QueryFilter): QueryFilter | undefined;
+//# sourceMappingURL=queryBuilder.filter.d.ts.map

package/dist/queryBuilder/queryBuilder.filter.js

@@ -1,3 +1,7 @@
+const EMPTY_FILTER = Object.freeze({
+    conditions: Object.freeze([]),
+});
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 /**
  * Creates an equality filter.
  */
@@ -81,7 +85,7 @@ export function isNotNull(field) {
  */
 export function and(...filters) {
     return {
-        and: filters.map(cloneFilter),
+        and: filters.map((filter) => cloneFilter(filter)),
     };
 }
 /**
@@ -89,7 +93,7 @@ export function and(...filters) {
  */
 export function or(...filters) {
     return {
-        or: filters.map(cloneFilter),
+        or: filters.map((filter) => cloneFilter(filter)),
     };
 }
 /**
@@ -120,11 +124,9 @@ export function condition(field, operator, value) {
  * Combines multiple filters with AND only when necessary.
  */
 export function allOf(filters) {
-    const normalized = filters.filter(Boolean).map(cloneFilter);
+    const normalized = filters.filter(hasConditions).map((filter) => cloneFilter(filter));
     if (normalized.length === 0) {
-        return {
-            conditions: [],
-        };
+        return EMPTY_FILTER;
     }
     if (normalized.length === 1) {
         return normalized[0];
@@ -137,11 +139,9 @@ export function allOf(filters) {
  * Combines multiple filters with OR only when necessary.
  */
 export function anyOf(filters) {
-    const normalized = filters.filter(Boolean).map(cloneFilter);
+    const normalized = filters.filter(hasConditions).map((filter) => cloneFilter(filter));
     if (normalized.length === 0) {
-        return {
-            conditions: [],
-        };
+        return EMPTY_FILTER;
     }
     if (normalized.length === 1) {
         return normalized[0];
@@ -156,11 +156,16 @@ export function anyOf(filters) {
  * Every property becomes an equality condition.
  */
 export function fromObject(values) {
-    const conditions = Object.entries(values).map(([field, value]) => ({
-        field,
-        operator: "equals",
-        value: cloneValue(value),
-    }));
+    if (values === null || typeof values !== "object" || Array.isArray(values)) {
+        throw new TypeError("fromObject requires a plain object.");
+    }
+    const conditions = [];
+    for (const [field, value] of Object.entries(values)) {
+        if (FORBIDDEN_KEYS.has(field)) {
+            throw new TypeError(`Invalid filter field "${field}".`);
+        }
+        conditions.push(...condition(field, "equals", value).conditions);
+    }
     return {
         conditions,
     };
@@ -187,20 +192,144 @@ export function dateRange(field, options) {
             value: new Date(options.to.getTime()),
         });
     }
-    if (conditions.length === 0) {
-        return {
-            conditions: [],
-        };
+    if (options.from && options.to && options.from.getTime() > options.to.getTime()) {
+        throw new RangeError("dateRange requires `from` to be on or before `to`.");
     }
-    if (conditions.length === 1) {
-        return {
-            conditions,
-        };
+    return {
+        conditions,
+    };
+}
+/**
+ * Creates an inclusive range filter (`field >= from AND field <= to`).
+ */
+export function between(field, from, to) {
+    validateField(field);
+    validateRangeBound(from, "from");
+    validateRangeBound(to, "to");
+    if (compareBounds(from, to) > 0) {
+        throw new RangeError("between requires `from` to be on or before `to`.");
     }
     return {
-        and: [
+        conditions: [
+            {
+                field,
+                operator: "gte",
+                value: cloneValue(from),
+            },
             {
-                conditions,
+                field,
+                operator: "lte",
+                value: cloneValue(to),
+            },
+        ],
+    };
+}
+/**
+ * Creates a SQL-style pattern filter using `%` wildcards.
+ *
+ * Only leading and/or trailing wildcards are supported (`%abc%`, `abc%`,
+ * `%abc`); the pattern is translated to `contains`, `startsWith`,
+ * `endsWith` or `equals` when converted for an ORM.
+ */
+export function matchesPattern(field, pattern) {
+    if (typeof pattern !== "string" || pattern.length === 0) {
+        throw new TypeError("A pattern is required.");
+    }
+    // The lookbehind pins the trailing match to the start of a `%` run; plain
+    // `%+$` retries from every `%` in an interior run, which is quadratic.
+    const inner = pattern.replace(/^%+/, "").replace(/(?<!%)%+$/, "");
+    if (inner.length === 0 || inner.includes("%") || inner.includes("_")) {
+        throw new TypeError("matchesPattern only supports leading and/or trailing % wildcards.");
+    }
+    return condition(field, "like", pattern);
+}
+/**
+ * Creates a filter matching null or empty-string values.
+ */
+export function isEmpty(field) {
+    return or(isNull(field), equals(field, ""));
+}
+/**
+ * Creates a filter matching values that are neither null nor empty.
+ */
+export function isNotEmpty(field) {
+    return and(isNotNull(field), notEquals(field, ""));
+}
+/**
+ * Creates a filter matching any timestamp on the given UTC calendar day.
+ */
+export function dateOnly(field, date) {
+    validateField(field);
+    validateDate(date, "date");
+    const start = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    const end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
+    return {
+        conditions: [
+            {
+                field,
+                operator: "gte",
+                value: start,
+            },
+            {
+                field,
+                operator: "lt",
+                value: end,
+            },
+        ],
+    };
+}
+/**
+ * Creates a filter for timestamps strictly before a date.
+ */
+export function isBefore(field, date) {
+    validateDate(date, "date");
+    return condition(field, "lt", date);
+}
+/**
+ * Creates a filter for timestamps strictly after a date.
+ */
+export function isAfter(field, date) {
+    validateDate(date, "date");
+    return condition(field, "gt", date);
+}
+/**
+ * Creates an inclusive date range filter.
+ */
+export function isBetween(field, from, to) {
+    validateDate(from, "from");
+    validateDate(to, "to");
+    return between(field, from, to);
+}
+/**
+ * Creates a negated single condition.
+ */
+export function notCondition(field, operator, value) {
+    return not(condition(field, operator, value));
+}
+/**
+ * Creates a filter on a related entity.
+ *
+ * `some` / `every` / `none` target collection relations; `is` / `isNot`
+ * target single relations.
+ */
+export function relational(relation, filter, operator = "some") {
+    if (operator !== "some" &&
+        operator !== "every" &&
+        operator !== "none" &&
+        operator !== "is" &&
+        operator !== "isNot") {
+        throw new TypeError(`Invalid relation operator "${String(operator)}".`);
+    }
+    if (!filter || typeof filter !== "object") {
+        throw new TypeError("A relation filter is required.");
+    }
+    validateField(relation);
+    return {
+        conditions: [
+            {
+                field: relation,
+                operator,
+                value: cloneFilter(filter),
             },
         ],
     };
@@ -263,6 +392,9 @@ export function hasConditions(filter) {
  * Flattens an AND-only filter into individual conditions.
  */
 export function flattenAnd(filter) {
+    if ((filter.or && filter.or.length > 0) || filter.not) {
+        throw new TypeError("flattenAnd only accepts AND-only filters; OR/NOT branches cannot be flattened.");
+    }
     const result = [];
     if (filter.conditions) {
         result.push(...filter.conditions.map(cloneCondition));
@@ -272,16 +404,16 @@ export function flattenAnd(filter) {
     }
     return result;
 }
-/**
- * Creates a new filter without mutating the source.
- */
 export function cloneFilter(filter) {
+    if (!filter) {
+        return undefined;
+    }
     return {
         conditions: filter.conditions
             ? filter.conditions.map(cloneCondition)
             : undefined,
-        and: filter.and ? filter.and.map(cloneFilter) : undefined,
-        or: filter.or ? filter.or.map(cloneFilter) : undefined,
+        and: filter.and ? filter.and.map((child) => cloneFilter(child)) : undefined,
+        or: filter.or ? filter.or.map((child) => cloneFilter(child)) : undefined,
         not: filter.not ? cloneFilter(filter.not) : undefined,
     };
 }
@@ -311,12 +443,38 @@ function cloneValue(value) {
     if (value && typeof value === "object") {
         const result = {};
         for (const [key, entry] of Object.entries(value)) {
+            if (FORBIDDEN_KEYS.has(key)) {
+                continue;
+            }
             result[key] = cloneValue(entry);
         }
         return result;
     }
     return value;
 }
+function validateRangeBound(value, name) {
+    if (value instanceof Date) {
+        validateDate(value, name);
+        return;
+    }
+    if (typeof value === "number" && Number.isNaN(value)) {
+        throw new TypeError(`Invalid ${name} bound.`);
+    }
+    if (typeof value !== "number" &&
+        typeof value !== "string" &&
+        typeof value !== "bigint") {
+        throw new TypeError(`Invalid ${name} bound.`);
+    }
+}
+function compareBounds(from, to) {
+    if (from instanceof Date && to instanceof Date) {
+        return from.getTime() - to.getTime();
+    }
+    if (typeof from === typeof to && from > to) {
+        return 1;
+    }
+    return 0;
+}
 /**
  * Validates a filter field.
  */
@@ -324,6 +482,9 @@ function validateField(field) {
     if (typeof field !== "string" || field.trim().length === 0) {
         throw new TypeError("A filter field is required.");
     }
+    if (FORBIDDEN_KEYS.has(field)) {
+        throw new TypeError(`Invalid filter field "${field}".`);
+    }
 }
 /**
  * Validates a date value.