@warlock.js/cascade 4.0.47 → 4.0.58

package/cjs/expressions/aggregate-expressions.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Database-agnostic aggregation expressions.
+ *
+ * These helpers provide a unified API for building aggregate queries that work
+ * across different database types (MongoDB, PostgreSQL, MySQL, etc.).
+ *
+ * Each driver implementation translates these abstract expressions to their
+ * native format:
+ * - MongoDB: { $sum: 1 }, { $sum: "$field" }, etc.
+ * - SQL: COUNT(*), SUM(field), etc.
+ *
+ * @example
+ * ```typescript
+ * import { $agg } from '@warlock.js/cascade';
+ *
+ * // Works for both MongoDB and SQL
+ * Lesson.query()
+ *   .groupBy("type", {
+ *     count: $agg.count(),
+ *     total: $agg.sum("duration"),
+ *     avg: $agg.avg("rating")
+ *   })
+ *   .get();
+ * ```
+ */
+/**
+ * Abstract aggregate expression format.
+ *
+ * This format is database-agnostic and will be translated by each driver
+ * to their native syntax.
+ */
+export type AggregateExpression = {
+    /** The aggregate function type */
+    __agg: AggregateFunction;
+    /** The field to aggregate (null for count) */
+    __field: string | null;
+};
+/**
+ * Supported aggregate functions.
+ */
+export type AggregateFunction = "count" | "sum" | "avg" | "min" | "max" | "first" | "last" | "distinct" | "floor";
+/**
+ * Checks if a value is an abstract aggregate expression.
+ */
+export declare function isAggregateExpression(value: unknown): value is AggregateExpression;
+/**
+ * Database-agnostic aggregation expression helpers.
+ *
+ * These helpers create abstract expressions that each driver translates
+ * to their native format.
+ */
+export declare const $agg: {
+    /**
+     * Count documents in each group.
+     *
+     * @returns Abstract count expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   count: $agg.count()
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: 1 }`
+     * - SQL: `COUNT(*)`
+     */
+    count(): AggregateExpression;
+    /**
+     * Sum a numeric field across documents in each group.
+     *
+     * @param field - The field name to sum
+     * @returns Abstract sum expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   totalDuration: $agg.sum("duration")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: "$duration" }`
+     * - SQL: `SUM(duration)`
+     */
+    sum(field: string): AggregateExpression;
+    /**
+     * Calculate the average value of a field across documents in each group.
+     *
+     * @param field - The field name to average
+     * @returns Abstract average expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   avgRating: $agg.avg("rating")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $avg: "$rating" }`
+     * - SQL: `AVG(rating)`
+     */
+    avg(field: string): AggregateExpression;
+    /**
+     * Get the minimum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract min expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   minPrice: $agg.min("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $min: "$price" }`
+     * - SQL: `MIN(price)`
+     */
+    min(field: string): AggregateExpression;
+    /**
+     * Get the maximum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract max expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   maxPrice: $agg.max("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $max: "$price" }`
+     * - SQL: `MAX(price)`
+     */
+    max(field: string): AggregateExpression;
+    /**
+     * Get the distinct values of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract distinct expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   distinctColors: $agg.distinct("color")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $distinct: "$color" }`
+     * - SQL: `DISTINCT(color)`
+     */
+    distinct(field: string): AggregateExpression;
+    /**
+     * Get the floor value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract floor expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   floorPrice: $agg.floor("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $floor: "$price" }`
+     * - SQL: `FLOOR(price)`
+     */
+    floor(field: string): AggregateExpression;
+    /**
+     * Get the first value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract first expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   firstName: $agg.first("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $first: "$name" }`
+     * - SQL: `FIRST_VALUE(name) OVER (...)`
+     */
+    first(field: string): AggregateExpression;
+    /**
+     * Get the last value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract last expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   lastName: $agg.last("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $last: "$name" }`
+     * - SQL: `LAST_VALUE(name) OVER (...)`
+     */
+    last(field: string): AggregateExpression;
+};
+//# sourceMappingURL=aggregate-expressions.d.ts.map

package/cjs/expressions/aggregate-expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-expressions.d.ts","sourceRoot":"","sources":["../../src/expressions/aggregate-expressions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,kCAAkC;IAClC,KAAK,EAAE,iBAAiB,CAAC;IACzB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,KAAK,GACL,KAAK,GACL,KAAK,GACL,KAAK,GACL,OAAO,GACP,MAAM,GACN,UAAU,GACV,OAAO,CAAC;AAEZ;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAOlF;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;;OAeG;aACM,mBAAmB;IAI5B;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;eACQ,MAAM,GAAG,mBAAmB;IAIvC;;;;;;;;;;;;;;;;OAgBG;oBACa,MAAM,GAAG,mBAAmB;IAI5C;;;;;;;;;;;;;;;;OAgBG;iBACU,MAAM,GAAG,mBAAmB;IAIzC;;;;;;;;;;;;;;;;OAgBG;iBACU,MAAM,GAAG,mBAAmB;IAIzC;;;;;;;;;;;;;;;;OAgBG;gBACS,MAAM,GAAG,mBAAmB;CAGzC,CAAC"}

package/cjs/expressions/aggregate-expressions.js

@@ -0,0 +1,221 @@
+'use strict';/**
+ * Database-agnostic aggregation expressions.
+ *
+ * These helpers provide a unified API for building aggregate queries that work
+ * across different database types (MongoDB, PostgreSQL, MySQL, etc.).
+ *
+ * Each driver implementation translates these abstract expressions to their
+ * native format:
+ * - MongoDB: { $sum: 1 }, { $sum: "$field" }, etc.
+ * - SQL: COUNT(*), SUM(field), etc.
+ *
+ * @example
+ * ```typescript
+ * import { $agg } from '@warlock.js/cascade';
+ *
+ * // Works for both MongoDB and SQL
+ * Lesson.query()
+ *   .groupBy("type", {
+ *     count: $agg.count(),
+ *     total: $agg.sum("duration"),
+ *     avg: $agg.avg("rating")
+ *   })
+ *   .get();
+ * ```
+ */
+/**
+ * Checks if a value is an abstract aggregate expression.
+ */
+function isAggregateExpression(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "__field" in value &&
+        typeof value.__agg === "string");
+}
+/**
+ * Database-agnostic aggregation expression helpers.
+ *
+ * These helpers create abstract expressions that each driver translates
+ * to their native format.
+ */
+const $agg = {
+    /**
+     * Count documents in each group.
+     *
+     * @returns Abstract count expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   count: $agg.count()
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: 1 }`
+     * - SQL: `COUNT(*)`
+     */
+    count() {
+        return { __agg: "count", __field: null };
+    },
+    /**
+     * Sum a numeric field across documents in each group.
+     *
+     * @param field - The field name to sum
+     * @returns Abstract sum expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   totalDuration: $agg.sum("duration")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $sum: "$duration" }`
+     * - SQL: `SUM(duration)`
+     */
+    sum(field) {
+        return { __agg: "sum", __field: field };
+    },
+    /**
+     * Calculate the average value of a field across documents in each group.
+     *
+     * @param field - The field name to average
+     * @returns Abstract average expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   avgRating: $agg.avg("rating")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $avg: "$rating" }`
+     * - SQL: `AVG(rating)`
+     */
+    avg(field) {
+        return { __agg: "avg", __field: field };
+    },
+    /**
+     * Get the minimum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract min expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   minPrice: $agg.min("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $min: "$price" }`
+     * - SQL: `MIN(price)`
+     */
+    min(field) {
+        return { __agg: "min", __field: field };
+    },
+    /**
+     * Get the maximum value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract max expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   maxPrice: $agg.max("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $max: "$price" }`
+     * - SQL: `MAX(price)`
+     */
+    max(field) {
+        return { __agg: "max", __field: field };
+    },
+    /**
+     * Get the distinct values of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract distinct expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   distinctColors: $agg.distinct("color")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $distinct: "$color" }`
+     * - SQL: `DISTINCT(color)`
+     */
+    distinct(field) {
+        return { __agg: "distinct", __field: field };
+    },
+    /**
+     * Get the floor value of a field across documents in each group.
+     *
+     * @param field - The field name
+     * @returns Abstract floor expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   floorPrice: $agg.floor("price")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $floor: "$price" }`
+     * - SQL: `FLOOR(price)`
+     */
+    floor(field) {
+        return { __agg: "floor", __field: field };
+    },
+    /**
+     * Get the first value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract first expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   firstName: $agg.first("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $first: "$name" }`
+     * - SQL: `FIRST_VALUE(name) OVER (...)`
+     */
+    first(field) {
+        return { __agg: "first", __field: field };
+    },
+    /**
+     * Get the last value of a field in each group (order-dependent).
+     *
+     * @param field - The field name
+     * @returns Abstract last expression
+     *
+     * @example
+     * ```typescript
+     * query.groupBy("type", {
+     *   lastName: $agg.last("name")
+     * });
+     * ```
+     *
+     * Translates to:
+     * - MongoDB: `{ $last: "$name" }`
+     * - SQL: `LAST_VALUE(name) OVER (...)`
+     */
+    last(field) {
+        return { __agg: "last", __field: field };
+    },
+};exports.$agg=$agg;exports.isAggregateExpression=isAggregateExpression;//# sourceMappingURL=aggregate-expressions.js.map

package/cjs/expressions/aggregate-expressions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-expressions.js","sources":["../../src/expressions/aggregate-expressions.ts"],"sourcesContent":[null],"names":[],"mappings":"aAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBG;AA6BH;;AAEG;AACG,SAAU,qBAAqB,CAAC,KAAc,EAAA;AAClD,IAAA,QACE,OAAO,KAAK,KAAK,QAAQ;AACzB,QAAA,KAAK,KAAK,IAAI;AACd,QAAA,SAAS,IAAI,KAAK;AAClB,QAAA,OAAQ,KAA6B,CAAC,KAAK,KAAK,QAAQ,EACxD;AACJ,CAAC;AAED;;;;;AAKG;AACU,MAAA,IAAI,GAAG;AAClB;;;;;;;;;;;;;;;AAeG;IACH,KAAK,GAAA;QACH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;KAC1C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,GAAG,CAAC,KAAa,EAAA;QACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzC;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,QAAQ,CAAC,KAAa,EAAA;QACpB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC9C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,KAAK,CAAC,KAAa,EAAA;QACjB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC3C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,KAAK,CAAC,KAAa,EAAA;QACjB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC3C;AAED;;;;;;;;;;;;;;;;AAgBG;AACH,IAAA,IAAI,CAAC,KAAa,EAAA;QAChB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC1C;"}

package/cjs/expressions/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./aggregate-expressions";
+//# sourceMappingURL=index.d.ts.map

package/cjs/expressions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/expressions/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/cjs/index.d.ts

@@ -0,0 +1,41 @@
+export * from "./context/database-data-source-context";
+export * from "./context/database-transaction-context";
+export * from "./contracts/database-driver.contract";
+export * from "./contracts/database-id-generator.contract";
+export * from "./contracts/database-remover.contract";
+export * from "./contracts/database-restorer.contract";
+export * from "./contracts/database-writer.contract";
+export * from "./contracts/migration-driver.contract";
+export * from "./contracts/query-builder.contract";
+export * from "./contracts/sync-adapter.contract";
+export * from "./data-source/data-source";
+export * from "./data-source/data-source-registry";
+export * from "./errors/missing-data-source.error";
+export * from "./database-dirty-tracker";
+export * from "./events/model-events";
+export * from "./model/model";
+export * from "./model/register-model";
+export * from "./remover/database-remover";
+export * from "./restorer/database-restorer";
+export * from "./types";
+export * from "./validation";
+export * from "./writer/database-writer";
+export * from "./expressions";
+export * from "./drivers/mongo/mongo-id-generator";
+export * from "./drivers/mongo/mongo-query-builder";
+export * from "./drivers/mongo/mongo-sync-adapter";
+export * from "./drivers/mongo/mongodb-driver";
+export * from "./drivers/mongo/types";
+export type { MongoClientOptions, TransactionOptions } from "mongodb";
+export { modelSync } from "./sync/model-sync";
+export { ModelSyncOperation } from "./sync/model-sync-operation";
+export { DEFAULT_MAX_SYNC_DEPTH, SyncContextManager } from "./sync/sync-context";
+export { SyncManager } from "./sync/sync-manager";
+export type { EmbedKey, ModelSyncConfig, ModelSyncContract, ModelSyncOperationContract, SyncConfig, SyncContext, SyncEventPayload, SyncInstruction, SyncInstructionOptions, SyncResult, } from "./sync/types";
+export * from "./utils/connect-to-database";
+export * from "./utils/database-writer.utils";
+export * from "./utils/define-model";
+export * from "./utils/once-connected";
+export * from "./migration";
+export { MongoMigrationDriver } from "./drivers/mongo/mongo-migration-driver";
+//# sourceMappingURL=index.d.ts.map

package/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AAGvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAGlD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AAGnD,cAAc,oCAAoC,CAAC;AAGnD,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AAGzC,cAAc,eAAe,CAAC;AAG9B,cAAc,oCAAoC,CAAC;AACnD,cAAc,qCAAqC,CAAC;AACpD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AAGtC,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,YAAY,EACV,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,0BAA0B,EAC1B,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,UAAU,GACX,MAAM,cAAc,CAAC;AAGtB,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC"}