@zudojs/database 0.0.1 → 1.0.0

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

@@ -0,0 +1,497 @@
+const EMPTY_FILTER = Object.freeze({
+    conditions: Object.freeze([]),
+});
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Creates an equality filter.
+ */
+export function equals(field, value) {
+    return condition(field, "equals", value);
+}
+/**
+ * Creates a not-equal filter.
+ */
+export function notEquals(field, value) {
+    return condition(field, "not", value);
+}
+/**
+ * Creates an IN filter.
+ */
+export function inList(field, values) {
+    return condition(field, "in", [...values]);
+}
+/**
+ * Creates a NOT IN filter.
+ */
+export function notInList(field, values) {
+    return condition(field, "notIn", [...values]);
+}
+/**
+ * Creates a less-than filter.
+ */
+export function lessThan(field, value) {
+    return condition(field, "lt", value);
+}
+/**
+ * Creates a less-than-or-equal filter.
+ */
+export function lessThanOrEqual(field, value) {
+    return condition(field, "lte", value);
+}
+/**
+ * Creates a greater-than filter.
+ */
+export function greaterThan(field, value) {
+    return condition(field, "gt", value);
+}
+/**
+ * Creates a greater-than-or-equal filter.
+ */
+export function greaterThanOrEqual(field, value) {
+    return condition(field, "gte", value);
+}
+/**
+ * Creates a contains filter.
+ */
+export function contains(field, value) {
+    return condition(field, "contains", value);
+}
+/**
+ * Creates a starts-with filter.
+ */
+export function startsWith(field, value) {
+    return condition(field, "startsWith", value);
+}
+/**
+ * Creates an ends-with filter.
+ */
+export function endsWith(field, value) {
+    return condition(field, "endsWith", value);
+}
+/**
+ * Creates an IS NULL filter.
+ */
+export function isNull(field) {
+    return condition(field, "isNull");
+}
+/**
+ * Creates an IS NOT NULL filter.
+ */
+export function isNotNull(field) {
+    return condition(field, "isNotNull");
+}
+/**
+ * Combines filters using AND.
+ */
+export function and(...filters) {
+    return {
+        and: filters.map((filter) => cloneFilter(filter)),
+    };
+}
+/**
+ * Combines filters using OR.
+ */
+export function or(...filters) {
+    return {
+        or: filters.map((filter) => cloneFilter(filter)),
+    };
+}
+/**
+ * Negates a filter.
+ */
+export function not(filter) {
+    return {
+        not: cloneFilter(filter),
+    };
+}
+/**
+ * Creates a generic filter condition.
+ */
+export function condition(field, operator, value) {
+    validateField(field);
+    const result = {
+        field,
+        operator,
+    };
+    if (value !== undefined) {
+        result.value = cloneValue(value);
+    }
+    return {
+        conditions: [result],
+    };
+}
+/**
+ * Combines multiple filters with AND only when necessary.
+ */
+export function allOf(filters) {
+    const normalized = filters.filter(hasConditions).map((filter) => cloneFilter(filter));
+    if (normalized.length === 0) {
+        return EMPTY_FILTER;
+    }
+    if (normalized.length === 1) {
+        return normalized[0];
+    }
+    return {
+        and: normalized,
+    };
+}
+/**
+ * Combines multiple filters with OR only when necessary.
+ */
+export function anyOf(filters) {
+    const normalized = filters.filter(hasConditions).map((filter) => cloneFilter(filter));
+    if (normalized.length === 0) {
+        return EMPTY_FILTER;
+    }
+    if (normalized.length === 1) {
+        return normalized[0];
+    }
+    return {
+        or: normalized,
+    };
+}
+/**
+ * Creates a filter from a plain object.
+ *
+ * Every property becomes an equality condition.
+ */
+export function fromObject(values) {
+    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,
+    };
+}
+/**
+ * Creates filters for a date range.
+ */
+export function dateRange(field, options) {
+    validateField(field);
+    const conditions = [];
+    if (options.from) {
+        validateDate(options.from, "from");
+        conditions.push({
+            field,
+            operator: "gte",
+            value: new Date(options.from.getTime()),
+        });
+    }
+    if (options.to) {
+        validateDate(options.to, "to");
+        conditions.push({
+            field,
+            operator: "lte",
+            value: new Date(options.to.getTime()),
+        });
+    }
+    if (options.from && options.to && options.from.getTime() > options.to.getTime()) {
+        throw new RangeError("dateRange requires `from` to be on or before `to`.");
+    }
+    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 {
+        conditions: [
+            {
+                field,
+                operator: "gte",
+                value: cloneValue(from),
+            },
+            {
+                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),
+            },
+        ],
+    };
+}
+/**
+ * Creates a filter for a value being one of several options.
+ */
+export function oneOf(field, values) {
+    return inList(field, values);
+}
+/**
+ * Creates a filter for a value not being one of several options.
+ */
+export function noneOf(field, values) {
+    return notInList(field, values);
+}
+/**
+ * Creates an optional equality filter.
+ *
+ * Returns an empty filter when the value is undefined.
+ */
+export function optionalEquals(field, value) {
+    if (value === undefined) {
+        return {
+            conditions: [],
+        };
+    }
+    return equals(field, value);
+}
+/**
+ * Creates an optional text search filter.
+ */
+export function optionalContains(field, value) {
+    if (value === undefined || value === null || value.trim().length === 0) {
+        return {
+            conditions: [],
+        };
+    }
+    return contains(field, value.trim());
+}
+/**
+ * Checks whether a filter contains any actual constraints.
+ */
+export function hasConditions(filter) {
+    if (!filter) {
+        return false;
+    }
+    if (filter.conditions && filter.conditions.length > 0) {
+        return true;
+    }
+    if (filter.and?.some(hasConditions)) {
+        return true;
+    }
+    if (filter.or?.some(hasConditions)) {
+        return true;
+    }
+    return filter.not ? hasConditions(filter.not) : false;
+}
+/**
+ * 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));
+    }
+    for (const child of filter.and ?? []) {
+        result.push(...flattenAnd(child));
+    }
+    return result;
+}
+export function cloneFilter(filter) {
+    if (!filter) {
+        return undefined;
+    }
+    return {
+        conditions: filter.conditions
+            ? filter.conditions.map(cloneCondition)
+            : 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,
+    };
+}
+/**
+ * Clones a single condition.
+ */
+function cloneCondition(condition) {
+    return {
+        ...condition,
+        ...(condition.value !== undefined
+            ? {
+                value: cloneValue(condition.value),
+            }
+            : {}),
+    };
+}
+/**
+ * Clones supported filter values.
+ */
+function cloneValue(value) {
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (Array.isArray(value)) {
+        return value.map(cloneValue);
+    }
+    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.
+ */
+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.
+ */
+function validateDate(value, name) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new TypeError(`Invalid ${name} date.`);
+    }
+}
+//# sourceMappingURL=queryBuilder.filter.js.map