@justscale/core 0.1.0

package/dist/models/query.js

@@ -0,0 +1,701 @@
+/**
+ * Query System
+ *
+ * Provides type-safe field expressions for building queries.
+ *
+ * @example
+ * ```typescript
+ * const { status, createdAt, author } = Post.fields;
+ *
+ * await postRepo.find({
+ *   where: q.and(
+ *     status.eq('published'),
+ *     createdAt.after(lastWeek),
+ *     author.eq(currentUser),
+ *   ),
+ * });
+ * ```
+ */
+import { isReference } from './reference/reference.js';
+import { ADAPTER_KEY } from './symbols.js';
+// ============================================================================
+// Condition Types (AST)
+// ============================================================================
+/** Symbol to mark a condition */
+export const CONDITION = Symbol('models:condition');
+// ============================================================================
+// Condition Factories
+// ============================================================================
+function createCondition(cond) {
+    return { [CONDITION]: true, ...cond };
+}
+/** Symbol to identify OrderByItem */
+export const ORDER_BY = Symbol('models:orderBy');
+/** Create an order by item */
+function createOrderBy(field, direction, nulls) {
+    return { __orderBy: true, field, direction, nulls };
+}
+/** Check if value is an OrderByItem */
+export function isOrderByItem(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '__orderBy' in value &&
+        value.__orderBy === true);
+}
+/** Base class for field expressions */
+class FieldExprBase {
+    fieldName;
+    fieldDef;
+    constructor(fieldName, fieldDef) {
+        this.fieldName = fieldName;
+        this.fieldDef = fieldDef;
+    }
+    /** The field name (for traversal and permission resolution) */
+    get fieldKey() { return this.fieldName; }
+    /** IS NULL */
+    isNull() {
+        return createCondition({ type: 'isNull', field: this.fieldName });
+    }
+    /** IS NOT NULL */
+    isNotNull() {
+        return createCondition({ type: 'isNotNull', field: this.fieldName });
+    }
+    /** Order ascending */
+    asc(nulls) {
+        return createOrderBy(this.fieldName, 'asc', nulls);
+    }
+    /** Order descending */
+    desc(nulls) {
+        return createOrderBy(this.fieldName, 'desc', nulls);
+    }
+}
+// ============================================================================
+// String Field Expression
+// ============================================================================
+/** Expression methods for string fields */
+export class StringFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** LIKE pattern (use % for wildcards) */
+    like(pattern) {
+        return createCondition({ type: 'like', field: this.fieldName, pattern });
+    }
+    /** Case-insensitive LIKE */
+    ilike(pattern) {
+        return createCondition({ type: 'ilike', field: this.fieldName, pattern });
+    }
+    /** Starts with prefix */
+    startsWith(prefix) {
+        return createCondition({ type: 'startsWith', field: this.fieldName, prefix });
+    }
+    /** Ends with suffix */
+    endsWith(suffix) {
+        return createCondition({ type: 'endsWith', field: this.fieldName, suffix });
+    }
+    /** Contains substring */
+    contains(substring) {
+        return createCondition({ type: 'contains', field: this.fieldName, substring });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// Number Field Expression
+// ============================================================================
+/** Expression methods for number fields (int, float, double, etc.) */
+export class NumberFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** Greater than */
+    gt(value) {
+        return createCondition({ type: 'gt', field: this.fieldName, value });
+    }
+    /** Greater than or equal */
+    gte(value) {
+        return createCondition({ type: 'gte', field: this.fieldName, value });
+    }
+    /** Less than */
+    lt(value) {
+        return createCondition({ type: 'lt', field: this.fieldName, value });
+    }
+    /** Less than or equal */
+    lte(value) {
+        return createCondition({ type: 'lte', field: this.fieldName, value });
+    }
+    /** Between min and max (inclusive) */
+    between(min, max) {
+        return createCondition({ type: 'between', field: this.fieldName, min, max });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// BigInt Field Expression
+// ============================================================================
+/** Expression methods for bigint fields */
+export class BigIntFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** Greater than */
+    gt(value) {
+        return createCondition({ type: 'gt', field: this.fieldName, value });
+    }
+    /** Greater than or equal */
+    gte(value) {
+        return createCondition({ type: 'gte', field: this.fieldName, value });
+    }
+    /** Less than */
+    lt(value) {
+        return createCondition({ type: 'lt', field: this.fieldName, value });
+    }
+    /** Less than or equal */
+    lte(value) {
+        return createCondition({ type: 'lte', field: this.fieldName, value });
+    }
+    /** Between min and max (inclusive) */
+    between(min, max) {
+        return createCondition({ type: 'between', field: this.fieldName, min, max });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// Decimal Field Expression (stored as string for precision)
+// ============================================================================
+/** Expression methods for decimal fields */
+export class DecimalFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** Greater than */
+    gt(value) {
+        return createCondition({ type: 'gt', field: this.fieldName, value });
+    }
+    /** Greater than or equal */
+    gte(value) {
+        return createCondition({ type: 'gte', field: this.fieldName, value });
+    }
+    /** Less than */
+    lt(value) {
+        return createCondition({ type: 'lt', field: this.fieldName, value });
+    }
+    /** Less than or equal */
+    lte(value) {
+        return createCondition({ type: 'lte', field: this.fieldName, value });
+    }
+    /** Between min and max (inclusive) */
+    between(min, max) {
+        return createCondition({ type: 'between', field: this.fieldName, min, max });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// Boolean Field Expression
+// ============================================================================
+/** Expression methods for boolean fields */
+export class BooleanFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Is true */
+    isTrue() {
+        return this.eq(true);
+    }
+    /** Is false */
+    isFalse() {
+        return this.eq(false);
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// Timestamp/Date Field Expression
+// ============================================================================
+/** Expression methods for timestamp/date fields */
+export class TimestampFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** Before date */
+    before(date) {
+        return createCondition({ type: 'before', field: this.fieldName, date });
+    }
+    /** After date */
+    after(date) {
+        return createCondition({ type: 'after', field: this.fieldName, date });
+    }
+    /** Between dates (inclusive) */
+    between(start, end) {
+        return createCondition({ type: 'between', field: this.fieldName, min: start, max: end });
+    }
+    /** Greater than */
+    gt(value) {
+        return createCondition({ type: 'gt', field: this.fieldName, value });
+    }
+    /** Greater than or equal */
+    gte(value) {
+        return createCondition({ type: 'gte', field: this.fieldName, value });
+    }
+    /** Less than */
+    lt(value) {
+        return createCondition({ type: 'lt', field: this.fieldName, value });
+    }
+    /** Less than or equal */
+    lte(value) {
+        return createCondition({ type: 'lte', field: this.fieldName, value });
+    }
+}
+// ============================================================================
+// UUID Field Expression
+// ============================================================================
+/** Expression methods for UUID fields */
+export class UuidFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values });
+    }
+}
+// ============================================================================
+// Enum Field Expression
+// ============================================================================
+/** Expression methods for enum fields */
+export class EnumFieldExpr extends FieldExprBase {
+    /** Equal to */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values });
+    }
+}
+/** Type guard for RefTraversal */
+export function isRefTraversal(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__isRefTraversal' in value &&
+        value.__isRefTraversal === true);
+}
+function makeRefTraversal(path) {
+    return {
+        __isRefTraversal: true,
+        path,
+        has(field) {
+            return makeRefTraversal([...path, field.fieldKey]);
+        },
+    };
+}
+// ============================================================================
+// Reference Field Expression
+// ============================================================================
+/**
+ * Extract the string identifier from any Ref<T> - Reference, Persistent entity, or string.
+ *
+ * @example
+ * ```typescript
+ * refId(ticket)          // Persistent<Ticket> → '123'
+ * refId(Ticket.ref('1')) // Reference<Ticket>  → '1'
+ * refId('abc')           // string             → 'abc'
+ * ```
+ */
+export function refId(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isReference(value))
+        return value.identifier;
+    // Persistent entity with adapter key
+    const adapterKey = value?.[ADAPTER_KEY];
+    if (adapterKey !== undefined)
+        return String(adapterKey);
+    throw new Error('Cannot extract key from value - pass a Reference, persistent entity, or string');
+}
+/** @internal Use refId() for the public API */
+const extractRefKey = refId;
+/** Expression methods for reference fields */
+export class RefFieldExpr extends FieldExprBase {
+    /** Equal to (accepts Reference, persistent entity, or id string) */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value: extractRefKey(value) });
+    }
+    /** Not equal to */
+    neq(value) {
+        return createCondition({ type: 'neq', field: this.fieldName, value: extractRefKey(value) });
+    }
+    /** In list of values */
+    in(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values: values.map(extractRefKey) });
+    }
+    /** Not in list of values */
+    notIn(values) {
+        return createCondition({ type: 'notIn', field: this.fieldName, values: values.map(extractRefKey) });
+    }
+    has(conditionOrField) {
+        if (conditionOrField instanceof RefFieldExpr) {
+            return makeRefTraversal([this.fieldName, conditionOrField.fieldKey]);
+        }
+        return createCondition({ type: 'has', field: this.fieldName, condition: conditionOrField });
+    }
+    /** Alias for has() with a Condition */
+    where(condition) {
+        return createCondition({ type: 'has', field: this.fieldName, condition });
+    }
+}
+// ============================================================================
+// References Field Expression (many-to-many)
+// ============================================================================
+/** Expression methods for refs fields (many-to-many) */
+export class RefsFieldExpr extends FieldExprBase {
+    /** Has any of the given references */
+    hasAny(values) {
+        return createCondition({ type: 'in', field: this.fieldName, values: values.map(extractRefKey) });
+    }
+    /** Has all of the given references */
+    hasAll(values) {
+        const ids = values.map(extractRefKey);
+        // Each ID must be present
+        const conditions = ids.map((id) => createCondition({ type: 'eq', field: this.fieldName, value: id }));
+        return createCondition({ type: 'and', conditions });
+    }
+    /** Has related entity matching condition (generates JOIN) */
+    has(condition) {
+        return createCondition({ type: 'has', field: this.fieldName, condition });
+    }
+}
+// ============================================================================
+// Array Field Expression
+// ============================================================================
+/** Expression methods for array fields */
+export class ArrayFieldExpr extends FieldExprBase {
+    /** Contains single element */
+    contains(value) {
+        return createCondition({
+            type: 'arrayContains',
+            field: this.fieldName,
+            value,
+        });
+    }
+    /** Has any of the given values */
+    hasAny(values) {
+        return createCondition({
+            type: 'arrayHasAny',
+            field: this.fieldName,
+            values,
+        });
+    }
+    /** Has all of the given values */
+    hasAll(values) {
+        return createCondition({
+            type: 'arrayHasAll',
+            field: this.fieldName,
+            values,
+        });
+    }
+    /** Array overlaps with values */
+    overlaps(values) {
+        return createCondition({
+            type: 'arrayOverlaps',
+            field: this.fieldName,
+            values,
+        });
+    }
+}
+// ============================================================================
+// JSON Field Expression
+// ============================================================================
+/** Expression methods for JSON/JSONB fields */
+export class JsonFieldExpr extends FieldExprBase {
+    /** Equal to (deep equality) */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Contains (JSONB @>) */
+    contains(value) {
+        return createCondition({
+            type: 'contains',
+            field: this.fieldName,
+            substring: JSON.stringify(value),
+        });
+    }
+}
+// ============================================================================
+// Object Field Expression
+// ============================================================================
+/** Expression methods for object fields with nested access */
+export class ObjectFieldExpr extends FieldExprBase {
+    objectShape;
+    constructor(fieldName, fieldDef, objectShape) {
+        super(fieldName, fieldDef);
+        this.objectShape = objectShape;
+    }
+    /** Equal to (deep equality) */
+    eq(value) {
+        return createCondition({ type: 'eq', field: this.fieldName, value });
+    }
+    /** Contains (partial match) */
+    contains(value) {
+        return createCondition({
+            type: 'contains',
+            field: this.fieldName,
+            substring: JSON.stringify(value),
+        });
+    }
+}
+// ============================================================================
+// Field Expression Factory
+// ============================================================================
+/**
+ * Create a Proxy wrapper for ObjectFieldExpr that allows nested property access.
+ * This enables syntax like `User.fields.settings.theme.eq('dark')`.
+ */
+function createObjectFieldExprProxy(fieldName, fieldDef, objectShape) {
+    const expr = new ObjectFieldExpr(fieldName, fieldDef, objectShape);
+    return new Proxy(expr, {
+        get(target, prop) {
+            // First check if the property is an own method/property of ObjectFieldExpr
+            if (prop in target) {
+                const value = target[prop];
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            // Then check if it's a nested field in the object shape
+            if (typeof prop === 'string' && prop in objectShape) {
+                const nestedFieldDef = objectShape[prop];
+                const nestedFieldName = `${fieldName}.${prop}`;
+                return createFieldExpr(nestedFieldName, nestedFieldDef);
+            }
+            return undefined;
+        },
+    });
+}
+/** Create a field expression for a given field definition */
+export function createFieldExpr(fieldName, fieldDef) {
+    switch (fieldDef.type) {
+        case 'string':
+        case 'text':
+            return new StringFieldExpr(fieldName, fieldDef);
+        case 'int':
+        case 'smallint':
+        case 'float':
+        case 'double':
+        case 'version':
+            return new NumberFieldExpr(fieldName, fieldDef);
+        case 'bigint':
+            return new BigIntFieldExpr(fieldName, fieldDef);
+        case 'decimal':
+            return new DecimalFieldExpr(fieldName, fieldDef);
+        case 'boolean':
+            return new BooleanFieldExpr(fieldName, fieldDef);
+        case 'timestamp':
+        case 'date':
+        case 'createdAt':
+        case 'updatedAt':
+        case 'deletedAt':
+            return new TimestampFieldExpr(fieldName, fieldDef);
+        case 'uuid':
+            return new UuidFieldExpr(fieldName, fieldDef);
+        case 'enum':
+            return new EnumFieldExpr(fieldName, fieldDef);
+        case 'ref':
+            return new RefFieldExpr(fieldName, fieldDef);
+        case 'refs':
+            return new RefsFieldExpr(fieldName, fieldDef);
+        case 'array':
+            return new ArrayFieldExpr(fieldName, fieldDef);
+        case 'json':
+        case 'jsonb':
+            return new JsonFieldExpr(fieldName, fieldDef);
+        case 'object':
+            if (fieldDef.objectShape) {
+                return createObjectFieldExprProxy(fieldName, fieldDef, fieldDef.objectShape);
+            }
+            return new JsonFieldExpr(fieldName, fieldDef);
+        case 'time':
+        case 'duration':
+        case 'bytes':
+        default:
+            return new StringFieldExpr(fieldName, fieldDef); // Fallback to string-like
+    }
+}
+// ============================================================================
+// Aggregation Types
+// ============================================================================
+/** Symbol to mark an aggregation */
+export const AGGREGATION = Symbol('models:aggregation');
+// ============================================================================
+// Query Helpers Namespace (q)
+// ============================================================================
+/**
+ * Query helpers namespace.
+ *
+ * @example
+ * ```typescript
+ * import { q } from '@justscale/core/models';
+ *
+ * // Logical operators
+ * q.and(status.eq('published'), createdAt.after(lastWeek))
+ * q.or(author.eq(user1), author.eq(user2))
+ * q.not(status.eq('draft'))
+ *
+ * // Aggregations
+ * q.count()
+ * q.sum(views)
+ * q.avg(rating)
+ * q.min(price)
+ * q.max(price)
+ * ```
+ */
+export const q = {
+    // ─── LOGICAL OPERATORS ───
+    /** AND condition - all must match */
+    and(...conditions) {
+        return createCondition({ type: 'and', conditions });
+    },
+    /** OR condition - any must match */
+    or(...conditions) {
+        return createCondition({ type: 'or', conditions });
+    },
+    /** NOT condition - negates the condition */
+    not(condition) {
+        return createCondition({ type: 'not', condition });
+    },
+    // ─── AGGREGATIONS ───
+    /** Count rows or distinct values */
+    count(field) {
+        const agg = {
+            [AGGREGATION]: true,
+            type: 'count',
+            field: field?.['fieldName'],
+        };
+        return Object.assign(agg, {
+            distinct() {
+                return { ...agg, distinct: true };
+            },
+        });
+    },
+    /** Sum of field values */
+    sum(field) {
+        return {
+            [AGGREGATION]: true,
+            type: 'sum',
+            field: field['fieldName'],
+        };
+    },
+    /** Average of field values */
+    avg(field) {
+        return {
+            [AGGREGATION]: true,
+            type: 'avg',
+            field: field['fieldName'],
+        };
+    },
+    /** Minimum value */
+    min(field) {
+        return {
+            [AGGREGATION]: true,
+            type: 'min',
+            field: field['fieldName'],
+        };
+    },
+    /** Maximum value */
+    max(field) {
+        return {
+            [AGGREGATION]: true,
+            type: 'max',
+            field: field['fieldName'],
+        };
+    },
+    // ─── RAW SQL (escape hatch) ───
+    /** Raw SQL condition */
+    raw(sql, ...values) {
+        return createCondition({ type: 'raw', sql, values });
+    },
+};
+// ============================================================================
+// Type Guards
+// ============================================================================
+/** Check if value is a Condition */
+export function isCondition(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        CONDITION in value &&
+        value[CONDITION] === true);
+}
+/** Check if value is an Aggregation */
+export function isAggregation(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        AGGREGATION in value &&
+        value[AGGREGATION] === true);
+}
+//# sourceMappingURL=query.js.map