monorise 1.1.0-dev.2 → 1.1.0-dev.3

package/dist/base/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { Entity as Entity$1, EntitySchemaMap as EntitySchemaMap$1 } from '@monorise/base';
 
 type WhereOperator = {
     $eq: string | number | boolean;
@@ -421,4 +422,55 @@ declare const createEntityConfig: <T extends Entity, B extends z.ZodRawShape, C
 };
 declare const createMutualConfig: <MD extends z.ZodRawShape>(config: MutualConfig<MD>) => MutualConfig<MD>;
 
-export { type AdjustmentCondition, type AdjustmentConditionFn, type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, type MutualConfig, type NumericFields, type UpdateCondition, type UpdateConditionFn, type WhereClause, type WhereConditions, type WhereOperator, createEntityConfig, createMutualConfig };
+type TransactionCreateEntity<T extends Entity$1 = Entity$1> = {
+    operation: 'createEntity';
+    entityType: T;
+    entityId?: string;
+    payload: EntitySchemaMap$1[T];
+};
+type TransactionUpdateEntity<T extends Entity$1 = Entity$1> = {
+    operation: 'updateEntity';
+    entityType: T;
+    entityId: string;
+    payload: Partial<EntitySchemaMap$1[T]>;
+    accountId?: string;
+    condition?: string;
+};
+type TransactionAdjustEntity<T extends Entity$1 = Entity$1> = {
+    operation: 'adjustEntity';
+    entityType: T;
+    entityId: string;
+    adjustments: Record<string, number>;
+    accountId?: string;
+    condition?: string;
+};
+type TransactionDeleteEntity<T extends Entity$1 = Entity$1> = {
+    operation: 'deleteEntity';
+    entityType: T;
+    entityId: string;
+};
+type TransactionOperation = TransactionCreateEntity | TransactionUpdateEntity | TransactionAdjustEntity | TransactionDeleteEntity;
+type TransactionResultEntry = {
+    operation: string;
+    entityType: Entity$1;
+    entityId: string;
+    data?: Record<string, unknown>;
+};
+type TransactionResult = {
+    results: TransactionResultEntry[];
+};
+
+declare const transactional: {
+    createEntity: <T extends Entity$1>(entityType: T, payload: EntitySchemaMap$1[T] & {
+        entityId?: string;
+    }) => TransactionCreateEntity<T>;
+    updateEntity: <T extends Entity$1>(entityType: T, entityId: string, payload: Partial<EntitySchemaMap$1[T]> & {
+        $condition?: string;
+    }) => TransactionUpdateEntity<T>;
+    adjustEntity: <T extends Entity$1>(entityType: T, entityId: string, adjustments: Record<string, number> & {
+        $condition?: string;
+    }) => TransactionAdjustEntity<T>;
+    deleteEntity: <T extends Entity$1>(entityType: T, entityId: string) => TransactionDeleteEntity<T>;
+};
+
+export { type AdjustmentCondition, type AdjustmentConditionFn, type CreatedEntity, type DraftEntity, Entity, type EntitySchemaMap, type MonoriseEntityConfig, type MutualConfig, type NumericFields, type TransactionAdjustEntity, type TransactionCreateEntity, type TransactionDeleteEntity, type TransactionOperation, type TransactionResult, type TransactionResultEntry, type TransactionUpdateEntity, type UpdateCondition, type UpdateConditionFn, type WhereClause, type WhereConditions, type WhereOperator, createEntityConfig, createMutualConfig, transactional };

package/dist/base/index.js

@@ -17,6 +17,18 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
 
 // types/monorise.type.ts
 var Entity = /* @__PURE__ */ ((Entity2) => {
@@ -38,9 +50,45 @@ var createEntityConfig = (config) => __spreadProps(__spreadValues({}, config), {
   finalSchema: makeSchema(config)
 });
 var createMutualConfig = (config) => config;
+
+// transactional.ts
+var transactional = {
+  createEntity: (entityType, payload) => {
+    const _a = payload, { entityId } = _a, rest = __objRest(_a, ["entityId"]);
+    return __spreadValues({
+      operation: "createEntity",
+      entityType,
+      payload: rest
+    }, entityId && { entityId });
+  },
+  updateEntity: (entityType, entityId, payload) => {
+    const _a = payload, { $condition } = _a, rest = __objRest(_a, ["$condition"]);
+    return __spreadValues({
+      operation: "updateEntity",
+      entityType,
+      entityId,
+      payload: rest
+    }, $condition && { condition: $condition });
+  },
+  adjustEntity: (entityType, entityId, adjustments) => {
+    const _a = adjustments, { $condition } = _a, rest = __objRest(_a, ["$condition"]);
+    return __spreadValues({
+      operation: "adjustEntity",
+      entityType,
+      entityId,
+      adjustments: rest
+    }, $condition && { condition: $condition });
+  },
+  deleteEntity: (entityType, entityId) => ({
+    operation: "deleteEntity",
+    entityType,
+    entityId
+  })
+};
 export {
   Entity,
   createEntityConfig,
-  createMutualConfig
+  createMutualConfig,
+  transactional
 };
 //# sourceMappingURL=index.js.map

package/dist/base/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../types/monorise.type.ts","../utils/index.ts"],"sourcesContent":["import type { z } from 'zod';\nimport type { WhereConditions } from './conditions.type';\n\nexport enum Entity {}\n\nexport interface EntitySchemaMap {\n  [key: string]: Record<string, any>;\n}\n\n/**\n * @description Configuration for a mutual relationship between two entities.\n * Defines the schema for mutualData validation. Define once, reference from both entity configs.\n *\n * @example\n * ```ts\n * const enrollmentMutual = createMutualConfig({\n *   entities: [Entity.STUDENT, Entity.COURSE],\n *   mutualDataSchema: z.object({\n *     role: z.enum(['student', 'auditor']),\n *     enrolledAt: z.string().datetime(),\n *   }),\n * });\n * ```\n */\nexport interface MutualConfig<\n  MD extends z.ZodRawShape = z.ZodRawShape,\n> {\n  entities: [Entity, Entity];\n  mutualDataSchema: z.ZodObject<MD>;\n}\n\nexport type DraftEntity<T extends Entity = Entity> =\n  T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n\nexport type NumericFields<T> = {\n  [K in keyof T as T[K] extends number ? K : never]?: number;\n};\n\nexport type CreatedEntity<T extends Entity = Entity> = {\n  entityId: string;\n  entityType: string;\n  data: T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n  createdAt: string;\n  updatedAt: string;\n};\n\n/**\n * @description Configuration for a monorise entity, a shared configuration that is used across frontend and backend.\n * This can be served as a single source of truth for the entity configuration.\n * It is used to define the schema, and mutual relationships between this entity and other entities.\n *\n * @example\n * ```ts\n * const baseSchema = z.object({\n *   title: z.string(),\n * }).partial();\n *\n * const createSchema = baseSchema.extend({\n *   title: z.string(),\n * })\n *\n * const config = createEntityConfig({\n *   name: 'learner',\n *   displayName: 'Learner',\n *   baseSchema,\n *   createSchema,\n * });\n * ```\n */\nexport interface MonoriseEntityConfig<\n  T extends Entity = Entity,\n  B extends z.ZodRawShape = z.ZodRawShape,\n  C extends z.ZodRawShape = z.ZodRawShape,\n  M extends z.ZodRawShape = z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n> {\n  /**\n   * @description Name of the entity. Must be in **lower-kebab-case** and **unique** across all entities\n   *\n   * @example `learner`, `learning-activity`\n   */\n  name: string | T;\n\n  /**\n   * @description Display name of the entity. It is not required to be unique\n   */\n  displayName: string;\n\n  /**\n   * @description (DEPRECATED) Use `uniqueFields` instead, Monorise should not handle auth mechanism\n   * @description (Optional) Specify the authentication method to be used for the entity\n   */\n  authMethod?: {\n    /**\n     * @description Authentication method using email\n     *\n     * Note: The email used for authentication is unique per entity.\n     * For example, if `johndoe@mail.com` is used for `learner` entity,\n     * it can be reused again on `admin` entity. However, the same email\n     * address cannot be repeated for the same entity.\n     */\n    email: {\n      /**\n       * @description Number of milliseconds before the token expires\n       */\n      tokenExpiresIn: number;\n    };\n  };\n\n  /**\n   * @description Base schema for the entity\n   */\n  baseSchema: z.ZodObject<B>;\n\n  /**\n   * @description Minimal schema required to create an entity\n   */\n  createSchema?: CO;\n  searchableFields?: (keyof B)[];\n  uniqueFields?: (keyof B)[];\n\n  /**\n   * @description Define mutual relationship of this entity with other entities\n   */\n  mutual?: {\n    /**\n     * @description Subscribes to update events from specified entities in the array.\n     * These events will be used to run prejoin processor.\n     */\n    subscribes?: { entityType: Entity }[];\n    /**\n     * @description Virtual schema for mutual relationship. The schema is only used for validation purpose, but these fields are not stored in the database\n     */\n    mutualSchema: MO;\n\n    /**\n     * @description Keys of `mutualFields` are fields defined in `mutualSchema`.\n     * Each field is a mutual relationship between this entity and another entity.\n     */\n    mutualFields: {\n      [key: string]: {\n        entityType: Entity;\n        toMutualIds?: (context: any) => string[];\n        /**\n         * @description (Optional) Custom function to process `mutualData`. If not provided, `mutualData` will be empty.\n         *\n         * @returns the final state of `mutualData` to be stored in the mutual record. Must be an object.\n         */\n        mutualDataProcessor?: (\n          mutualIds: string[],\n          currentMutual: any,\n          customContext?: Record<string, any>,\n        ) => Record<string, any>;\n        /**\n         * @description (Optional) Reference to a mutual config created by `createMutualConfig`.\n         * Provides mutualData schema validation for create/update operations on this mutual relationship.\n         */\n        mutual?: MutualConfig;\n      };\n    };\n\n    /**\n     * @description (Optional) Better known as tree processor\n     * This is used to prejoin entities that are not directly related as mutual.\n     * For example, if `learner` entity is related to `course` entity, and `course` entity is related to `module` entity,\n     * prejoins can be used to join `learner` and `module` entities.\n     * With this, the `learner` entity can access the `module` entity without having to go through the `course` entity,\n     * hence reducing the number of queries.\n     *\n     * DynamoDB best practices: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-normalization.html\n     *\n     */\n    prejoins?: {\n      mutualField: string;\n      targetEntityType: Entity;\n      entityPaths: {\n        skipCache?: boolean;\n        entityType: Entity;\n        processor?: (items: any[], context: Record<string, any>) => any;\n      }[];\n    }[];\n  };\n  /**\n   * Use this function to perform side effects on the final schema for example refine/superRefine the schema\n   *\n   * @param schema The final schema of the entity (the combination of `baseSchema`/`createSchema` and `mutualSchema` if specified)\n   * @returns void\n   *\n   * @example\n   * ```ts\n   * effect: (schema) => {\n   *   schema.refine(\n   *     // refinement logic here\n   *   )\n   * }\n   */\n  effect?: (\n    schema: z.ZodObject<z.ZodRawShape>,\n  ) => z.ZodEffects<z.ZodObject<z.ZodRawShape>>;\n\n  /**\n   * @description (Optional) Use tags to create additional access patterns for the entity.\n   * Time complexity for retrieving tagged entities is O(1).\n   *\n   * The following configuration will create a tag named `region` for the `organization` entity grouped by `region`.\n   * You would then be able to retrieve all organizations in a specific region by:\n   * GET `/core/tag/organization/region?group={region_name}`\n   *\n   * @example\n   *\n   * ```ts\n   * {\n   *   name: 'organization',\n   *   tags: [\n   *    {\n   *      name: 'region',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            group: entity.data.region\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   *\n   * @description\n   *\n   * The following configuration will create a tag named `dob` for the `user` entity sorted by `dob`.\n   * You would then be able to retrieve all users sorted by `dob` by:\n   * GET `/core/tag/user/dob?start=2000-01-01&end=2020-12-31`\n   *\n   * @example\n   * ```ts\n   * {\n   *   name: 'user',\n   *   tags: [\n   *    {\n   *      name: 'dob',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            sortValue: entity.data.dob\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   */\n  tags?: {\n    name: string;\n    processor: (entity: { entityId: string; entityType: string; data: Record<string, any>; createdAt: string; updatedAt: string }) => {\n      group?: string;\n      sortValue?: string;\n    }[];\n  }[];\n\n  /**\n   * @description (Optional) Constraints for `adjustEntity` operations.\n   * When adjusting numeric fields, these constraints are enforced at the database level.\n   * If an adjustment would violate a constraint, the operation is rejected.\n   *\n   * @deprecated Use `conditions` instead. Will be removed in a future version.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConstraints: {\n   *     // Static: same for all entities of this type\n   *     balance: { min: 0 },\n   *     credits: { min: 0, max: 10000 },\n   *\n   *     // Dynamic: reads constraint value from entity's own data\n   *     balance: { minField: 'minBalance' },\n   *     credits: { min: 0, maxField: 'creditLimit' },\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConstraints?: {\n    [fieldName: string]: {\n      /** Static minimum value */\n      min?: number;\n      /** Static maximum value */\n      max?: number;\n      /** Field name on the entity whose value is used as the minimum (must be a numeric field) */\n      minField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n      /** Field name on the entity whose value is used as the maximum (must be a numeric field) */\n      maxField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n    };\n  };\n\n  /**\n   * @description Named conditions for adjustEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data, adjustments) => WhereConditions` that receives the entity's current data\n   * and the adjustment deltas.\n   *\n   * When defined, `$condition` is **required** in the adjustEntity request body.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConditions: {\n   *     withdraw: (data, adjustments) => ({\n   *       balance: { $gte: (data.minBalance ?? 0) + Math.abs(adjustments?.balance ?? 0) },\n   *     }),\n   *     deposit: (data, adjustments) => ({\n   *       balance: { $lte: 1000000 - (adjustments.balance ?? 0) },\n   *     }),\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((\n          data: Partial<z.infer<z.ZodObject<B>>>,\n          adjustments: Record<string, number>,\n        ) => WhereConditions);\n  };\n\n  /**\n   * @description Named conditions for updateEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data) => WhereConditions` that receives the entity's current data.\n   *\n   * `$condition` is always **optional** for updateEntity.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression. Replaces raw `$where` (deprecated).\n   *\n   * @example\n   * ```ts\n   * {\n   *   updateConditions: {\n   *     publish: { status: { $eq: 'draft' } },\n   *     archive: (data) => ({ status: { $ne: 'archived' } }),\n   *   }\n   * }\n   * ```\n   */\n  updateConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((data: Partial<z.infer<z.ZodObject<B>>>) => WhereConditions);\n  };\n}\n","import type { Entity, MonoriseEntityConfig, MutualConfig } from '../types/monorise.type';\nimport { z } from 'zod';\n\nfunction makeSchema<\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(config: MonoriseEntityConfig<T, B, C, M, CO, MO>) {\n  const { baseSchema, createSchema, mutual, effect } = config;\n  const { mutualSchema } = mutual || {};\n\n  type FinalSchemaType = CO extends z.AnyZodObject\n    ? MO extends z.AnyZodObject\n      ? z.ZodObject<B & CO['shape'] & MO['shape']>\n      : z.ZodObject<B & CO['shape']>\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<B & MO['shape']>\n      : z.ZodObject<B>;\n\n  const finalSchema = z.object({\n    ...baseSchema.shape,\n    ...createSchema?.shape,\n    ...mutualSchema?.shape,\n  }) as FinalSchemaType;\n\n  if (effect) {\n    return effect(finalSchema) as z.ZodEffects<FinalSchemaType>;\n  }\n\n  return finalSchema;\n}\n\nconst createEntityConfig = <\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(\n  config: MonoriseEntityConfig<T, B, C, M, CO, MO>,\n) => ({\n  ...config,\n  finalSchema: makeSchema(config),\n});\n\nconst createMutualConfig = <MD extends z.ZodRawShape>(\n  config: MutualConfig<MD>,\n) => config;\n\nexport { createEntityConfig, createMutualConfig };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAGO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACFZ,SAAS,SAAS;AAElB,SAAS,WAOP,QAAkD;AAClD,QAAM,EAAE,YAAY,cAAc,QAAQ,OAAO,IAAI;AACrD,QAAM,EAAE,aAAa,IAAI,UAAU,CAAC;AAUpC,QAAM,cAAc,EAAE,OAAO,iDACxB,WAAW,QACX,6CAAc,QACd,6CAAc,MAClB;AAED,MAAI,QAAQ;AACV,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO;AACT;AAEA,IAAM,qBAAqB,CAQzB,WACI,iCACD,SADC;AAAA,EAEJ,aAAa,WAAW,MAAM;AAChC;AAEA,IAAM,qBAAqB,CACzB,WACG;","names":["Entity"]}
+{"version":3,"sources":["../types/monorise.type.ts","../utils/index.ts","../transactional.ts"],"sourcesContent":["import type { z } from 'zod';\nimport type { WhereConditions } from './conditions.type';\n\nexport enum Entity {}\n\nexport interface EntitySchemaMap {\n  [key: string]: Record<string, any>;\n}\n\n/**\n * @description Configuration for a mutual relationship between two entities.\n * Defines the schema for mutualData validation. Define once, reference from both entity configs.\n *\n * @example\n * ```ts\n * const enrollmentMutual = createMutualConfig({\n *   entities: [Entity.STUDENT, Entity.COURSE],\n *   mutualDataSchema: z.object({\n *     role: z.enum(['student', 'auditor']),\n *     enrolledAt: z.string().datetime(),\n *   }),\n * });\n * ```\n */\nexport interface MutualConfig<\n  MD extends z.ZodRawShape = z.ZodRawShape,\n> {\n  entities: [Entity, Entity];\n  mutualDataSchema: z.ZodObject<MD>;\n}\n\nexport type DraftEntity<T extends Entity = Entity> =\n  T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n\nexport type NumericFields<T> = {\n  [K in keyof T as T[K] extends number ? K : never]?: number;\n};\n\nexport type CreatedEntity<T extends Entity = Entity> = {\n  entityId: string;\n  entityType: string;\n  data: T extends keyof EntitySchemaMap ? EntitySchemaMap[T] : never;\n  createdAt: string;\n  updatedAt: string;\n};\n\n/**\n * @description Configuration for a monorise entity, a shared configuration that is used across frontend and backend.\n * This can be served as a single source of truth for the entity configuration.\n * It is used to define the schema, and mutual relationships between this entity and other entities.\n *\n * @example\n * ```ts\n * const baseSchema = z.object({\n *   title: z.string(),\n * }).partial();\n *\n * const createSchema = baseSchema.extend({\n *   title: z.string(),\n * })\n *\n * const config = createEntityConfig({\n *   name: 'learner',\n *   displayName: 'Learner',\n *   baseSchema,\n *   createSchema,\n * });\n * ```\n */\nexport interface MonoriseEntityConfig<\n  T extends Entity = Entity,\n  B extends z.ZodRawShape = z.ZodRawShape,\n  C extends z.ZodRawShape = z.ZodRawShape,\n  M extends z.ZodRawShape = z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n> {\n  /**\n   * @description Name of the entity. Must be in **lower-kebab-case** and **unique** across all entities\n   *\n   * @example `learner`, `learning-activity`\n   */\n  name: string | T;\n\n  /**\n   * @description Display name of the entity. It is not required to be unique\n   */\n  displayName: string;\n\n  /**\n   * @description (DEPRECATED) Use `uniqueFields` instead, Monorise should not handle auth mechanism\n   * @description (Optional) Specify the authentication method to be used for the entity\n   */\n  authMethod?: {\n    /**\n     * @description Authentication method using email\n     *\n     * Note: The email used for authentication is unique per entity.\n     * For example, if `johndoe@mail.com` is used for `learner` entity,\n     * it can be reused again on `admin` entity. However, the same email\n     * address cannot be repeated for the same entity.\n     */\n    email: {\n      /**\n       * @description Number of milliseconds before the token expires\n       */\n      tokenExpiresIn: number;\n    };\n  };\n\n  /**\n   * @description Base schema for the entity\n   */\n  baseSchema: z.ZodObject<B>;\n\n  /**\n   * @description Minimal schema required to create an entity\n   */\n  createSchema?: CO;\n  searchableFields?: (keyof B)[];\n  uniqueFields?: (keyof B)[];\n\n  /**\n   * @description Define mutual relationship of this entity with other entities\n   */\n  mutual?: {\n    /**\n     * @description Subscribes to update events from specified entities in the array.\n     * These events will be used to run prejoin processor.\n     */\n    subscribes?: { entityType: Entity }[];\n    /**\n     * @description Virtual schema for mutual relationship. The schema is only used for validation purpose, but these fields are not stored in the database\n     */\n    mutualSchema: MO;\n\n    /**\n     * @description Keys of `mutualFields` are fields defined in `mutualSchema`.\n     * Each field is a mutual relationship between this entity and another entity.\n     */\n    mutualFields: {\n      [key: string]: {\n        entityType: Entity;\n        toMutualIds?: (context: any) => string[];\n        /**\n         * @description (Optional) Custom function to process `mutualData`. If not provided, `mutualData` will be empty.\n         *\n         * @returns the final state of `mutualData` to be stored in the mutual record. Must be an object.\n         */\n        mutualDataProcessor?: (\n          mutualIds: string[],\n          currentMutual: any,\n          customContext?: Record<string, any>,\n        ) => Record<string, any>;\n        /**\n         * @description (Optional) Reference to a mutual config created by `createMutualConfig`.\n         * Provides mutualData schema validation for create/update operations on this mutual relationship.\n         */\n        mutual?: MutualConfig;\n      };\n    };\n\n    /**\n     * @description (Optional) Better known as tree processor\n     * This is used to prejoin entities that are not directly related as mutual.\n     * For example, if `learner` entity is related to `course` entity, and `course` entity is related to `module` entity,\n     * prejoins can be used to join `learner` and `module` entities.\n     * With this, the `learner` entity can access the `module` entity without having to go through the `course` entity,\n     * hence reducing the number of queries.\n     *\n     * DynamoDB best practices: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-general-normalization.html\n     *\n     */\n    prejoins?: {\n      mutualField: string;\n      targetEntityType: Entity;\n      entityPaths: {\n        skipCache?: boolean;\n        entityType: Entity;\n        processor?: (items: any[], context: Record<string, any>) => any;\n      }[];\n    }[];\n  };\n  /**\n   * Use this function to perform side effects on the final schema for example refine/superRefine the schema\n   *\n   * @param schema The final schema of the entity (the combination of `baseSchema`/`createSchema` and `mutualSchema` if specified)\n   * @returns void\n   *\n   * @example\n   * ```ts\n   * effect: (schema) => {\n   *   schema.refine(\n   *     // refinement logic here\n   *   )\n   * }\n   */\n  effect?: (\n    schema: z.ZodObject<z.ZodRawShape>,\n  ) => z.ZodEffects<z.ZodObject<z.ZodRawShape>>;\n\n  /**\n   * @description (Optional) Use tags to create additional access patterns for the entity.\n   * Time complexity for retrieving tagged entities is O(1).\n   *\n   * The following configuration will create a tag named `region` for the `organization` entity grouped by `region`.\n   * You would then be able to retrieve all organizations in a specific region by:\n   * GET `/core/tag/organization/region?group={region_name}`\n   *\n   * @example\n   *\n   * ```ts\n   * {\n   *   name: 'organization',\n   *   tags: [\n   *    {\n   *      name: 'region',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            group: entity.data.region\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   *\n   * @description\n   *\n   * The following configuration will create a tag named `dob` for the `user` entity sorted by `dob`.\n   * You would then be able to retrieve all users sorted by `dob` by:\n   * GET `/core/tag/user/dob?start=2000-01-01&end=2020-12-31`\n   *\n   * @example\n   * ```ts\n   * {\n   *   name: 'user',\n   *   tags: [\n   *    {\n   *      name: 'dob',\n   *      processor: (entity) => {\n   *        return [\n   *          {\n   *            sortValue: entity.data.dob\n   *          }\n   *        ]\n   *      },\n   *    }\n   *   ]\n   * }\n   * ```\n   */\n  tags?: {\n    name: string;\n    processor: (entity: { entityId: string; entityType: string; data: Record<string, any>; createdAt: string; updatedAt: string }) => {\n      group?: string;\n      sortValue?: string;\n    }[];\n  }[];\n\n  /**\n   * @description (Optional) Constraints for `adjustEntity` operations.\n   * When adjusting numeric fields, these constraints are enforced at the database level.\n   * If an adjustment would violate a constraint, the operation is rejected.\n   *\n   * @deprecated Use `conditions` instead. Will be removed in a future version.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConstraints: {\n   *     // Static: same for all entities of this type\n   *     balance: { min: 0 },\n   *     credits: { min: 0, max: 10000 },\n   *\n   *     // Dynamic: reads constraint value from entity's own data\n   *     balance: { minField: 'minBalance' },\n   *     credits: { min: 0, maxField: 'creditLimit' },\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConstraints?: {\n    [fieldName: string]: {\n      /** Static minimum value */\n      min?: number;\n      /** Static maximum value */\n      max?: number;\n      /** Field name on the entity whose value is used as the minimum (must be a numeric field) */\n      minField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n      /** Field name on the entity whose value is used as the maximum (must be a numeric field) */\n      maxField?: keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      } extends never ? string : keyof {\n        [K in keyof B as B[K] extends z.ZodNumber | z.ZodOptional<z.ZodNumber> ? K : never]: K;\n      };\n    };\n  };\n\n  /**\n   * @description Named conditions for adjustEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data, adjustments) => WhereConditions` that receives the entity's current data\n   * and the adjustment deltas.\n   *\n   * When defined, `$condition` is **required** in the adjustEntity request body.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression.\n   *\n   * @example\n   * ```ts\n   * {\n   *   adjustmentConditions: {\n   *     withdraw: (data, adjustments) => ({\n   *       balance: { $gte: (data.minBalance ?? 0) + Math.abs(adjustments?.balance ?? 0) },\n   *     }),\n   *     deposit: (data, adjustments) => ({\n   *       balance: { $lte: 1000000 - (adjustments.balance ?? 0) },\n   *     }),\n   *   }\n   * }\n   * ```\n   */\n  adjustmentConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((\n          data: Partial<z.infer<z.ZodObject<B>>>,\n          adjustments: Record<string, number>,\n        ) => WhereConditions);\n  };\n\n  /**\n   * @description Named conditions for updateEntity operations.\n   * Each condition is either a static `WhereConditions` object or a function\n   * `(data) => WhereConditions` that receives the entity's current data.\n   *\n   * `$condition` is always **optional** for updateEntity.\n   * The client sends a condition name (string), the server resolves it to a\n   * DynamoDB ConditionExpression. Replaces raw `$where` (deprecated).\n   *\n   * @example\n   * ```ts\n   * {\n   *   updateConditions: {\n   *     publish: { status: { $eq: 'draft' } },\n   *     archive: (data) => ({ status: { $ne: 'archived' } }),\n   *   }\n   * }\n   * ```\n   */\n  updateConditions?: {\n    [conditionName: string]:\n      | WhereConditions\n      | ((data: Partial<z.infer<z.ZodObject<B>>>) => WhereConditions);\n  };\n}\n","import type { Entity, MonoriseEntityConfig, MutualConfig } from '../types/monorise.type';\nimport { z } from 'zod';\n\nfunction makeSchema<\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(config: MonoriseEntityConfig<T, B, C, M, CO, MO>) {\n  const { baseSchema, createSchema, mutual, effect } = config;\n  const { mutualSchema } = mutual || {};\n\n  type FinalSchemaType = CO extends z.AnyZodObject\n    ? MO extends z.AnyZodObject\n      ? z.ZodObject<B & CO['shape'] & MO['shape']>\n      : z.ZodObject<B & CO['shape']>\n    : MO extends z.AnyZodObject\n      ? z.ZodObject<B & MO['shape']>\n      : z.ZodObject<B>;\n\n  const finalSchema = z.object({\n    ...baseSchema.shape,\n    ...createSchema?.shape,\n    ...mutualSchema?.shape,\n  }) as FinalSchemaType;\n\n  if (effect) {\n    return effect(finalSchema) as z.ZodEffects<FinalSchemaType>;\n  }\n\n  return finalSchema;\n}\n\nconst createEntityConfig = <\n  T extends Entity,\n  B extends z.ZodRawShape,\n  C extends z.ZodRawShape,\n  M extends z.ZodRawShape,\n  CO extends z.ZodObject<C> | undefined = undefined,\n  MO extends z.ZodObject<M> | undefined = undefined,\n>(\n  config: MonoriseEntityConfig<T, B, C, M, CO, MO>,\n) => ({\n  ...config,\n  finalSchema: makeSchema(config),\n});\n\nconst createMutualConfig = <MD extends z.ZodRawShape>(\n  config: MutualConfig<MD>,\n) => config;\n\nexport { createEntityConfig, createMutualConfig };\n","import type { Entity as EntityType, EntitySchemaMap } from '@monorise/base';\nimport type {\n  TransactionAdjustEntity,\n  TransactionCreateEntity,\n  TransactionDeleteEntity,\n  TransactionOperation,\n  TransactionUpdateEntity,\n} from './types/transaction.type';\n\nexport const transactional = {\n  createEntity: <T extends EntityType>(\n    entityType: T,\n    payload: EntitySchemaMap[T] & { entityId?: string },\n  ): TransactionCreateEntity<T> => {\n    const { entityId, ...rest } = payload as EntitySchemaMap[T] & {\n      entityId?: string;\n    };\n    return {\n      operation: 'createEntity',\n      entityType,\n      payload: rest as EntitySchemaMap[T],\n      ...(entityId && { entityId }),\n    };\n  },\n\n  updateEntity: <T extends EntityType>(\n    entityType: T,\n    entityId: string,\n    payload: Partial<EntitySchemaMap[T]> & { $condition?: string },\n  ): TransactionUpdateEntity<T> => {\n    const { $condition, ...rest } = payload as Partial<EntitySchemaMap[T]> & {\n      $condition?: string;\n    };\n    return {\n      operation: 'updateEntity',\n      entityType,\n      entityId,\n      payload: rest as Partial<EntitySchemaMap[T]>,\n      ...($condition && { condition: $condition }),\n    };\n  },\n\n  adjustEntity: <T extends EntityType>(\n    entityType: T,\n    entityId: string,\n    adjustments: Record<string, number> & { $condition?: string },\n  ): TransactionAdjustEntity<T> => {\n    const { $condition, ...rest } = adjustments;\n    return {\n      operation: 'adjustEntity',\n      entityType,\n      entityId,\n      adjustments: rest,\n      ...($condition && { condition: $condition }),\n    };\n  },\n\n  deleteEntity: <T extends EntityType>(\n    entityType: T,\n    entityId: string,\n  ): TransactionDeleteEntity<T> => ({\n    operation: 'deleteEntity',\n    entityType,\n    entityId,\n  }),\n};\n\nexport type { TransactionOperation };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGO,IAAK,SAAL,kBAAKA,YAAL;AAAK,SAAAA;AAAA,GAAA;;;ACFZ,SAAS,SAAS;AAElB,SAAS,WAOP,QAAkD;AAClD,QAAM,EAAE,YAAY,cAAc,QAAQ,OAAO,IAAI;AACrD,QAAM,EAAE,aAAa,IAAI,UAAU,CAAC;AAUpC,QAAM,cAAc,EAAE,OAAO,iDACxB,WAAW,QACX,6CAAc,QACd,6CAAc,MAClB;AAED,MAAI,QAAQ;AACV,WAAO,OAAO,WAAW;AAAA,EAC3B;AAEA,SAAO;AACT;AAEA,IAAM,qBAAqB,CAQzB,WACI,iCACD,SADC;AAAA,EAEJ,aAAa,WAAW,MAAM;AAChC;AAEA,IAAM,qBAAqB,CACzB,WACG;;;AC1CE,IAAM,gBAAgB;AAAA,EAC3B,cAAc,CACZ,YACA,YAC+B;AAC/B,UAA8B,cAAtB,WAdZ,IAckC,IAAT,iBAAS,IAAT,CAAb;AAGR,WAAO;AAAA,MACL,WAAW;AAAA,MACX;AAAA,MACA,SAAS;AAAA,OACL,YAAY,EAAE,SAAS;AAAA,EAE/B;AAAA,EAEA,cAAc,CACZ,YACA,UACA,YAC+B;AAC/B,UAAgC,cAAxB,aA9BZ,IA8BoC,IAAT,iBAAS,IAAT,CAAf;AAGR,WAAO;AAAA,MACL,WAAW;AAAA,MACX;AAAA,MACA;AAAA,MACA,SAAS;AAAA,OACL,cAAc,EAAE,WAAW,WAAW;AAAA,EAE9C;AAAA,EAEA,cAAc,CACZ,YACA,UACA,gBAC+B;AAC/B,UAAgC,kBAAxB,aA/CZ,IA+CoC,IAAT,iBAAS,IAAT,CAAf;AACR,WAAO;AAAA,MACL,WAAW;AAAA,MACX;AAAA,MACA;AAAA,MACA,aAAa;AAAA,OACT,cAAc,EAAE,WAAW,WAAW;AAAA,EAE9C;AAAA,EAEA,cAAc,CACZ,YACA,cACgC;AAAA,IAChC,WAAW;AAAA,IACX;AAAA,IACA;AAAA,EACF;AACF;","names":["Entity"]}

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
-import { Entity as Entity$2, EntitySchemaMap, createEntityConfig, WhereConditions } from '../base/index';
+import { Entity as Entity$2, EntitySchemaMap, createEntityConfig, WhereConditions, TransactionOperation, TransactionResult } from '../base/index';
+export { transactional } from '../base/index';
 import * as hono from 'hono';
 import { Hono } from 'hono';
 import { DynamoDB, TransactWriteItemsInput, AttributeValue, TransactWriteItem, UpdateItemCommandInput } from '@aws-sdk/client-dynamodb';
@@ -4724,44 +4725,6 @@ declare class ListTagsController {
     }, hono_utils_http_status.ContentfulStatusCode, "json">>;
 }
 
-type TransactionCreateEntity<T extends Entity$2 = Entity$2> = {
-    operation: 'createEntity';
-    entityType: T;
-    entityId?: string;
-    payload: EntitySchemaMap[T];
-};
-type TransactionUpdateEntity<T extends Entity$2 = Entity$2> = {
-    operation: 'updateEntity';
-    entityType: T;
-    entityId: string;
-    payload: Partial<EntitySchemaMap[T]>;
-    accountId?: string;
-    condition?: string;
-};
-type TransactionAdjustEntity<T extends Entity$2 = Entity$2> = {
-    operation: 'adjustEntity';
-    entityType: T;
-    entityId: string;
-    adjustments: Record<string, number>;
-    accountId?: string;
-    condition?: string;
-};
-type TransactionDeleteEntity<T extends Entity$2 = Entity$2> = {
-    operation: 'deleteEntity';
-    entityType: T;
-    entityId: string;
-};
-type TransactionOperation = TransactionCreateEntity | TransactionUpdateEntity | TransactionAdjustEntity | TransactionDeleteEntity;
-type TransactionResultEntry = {
-    operation: string;
-    entityType: Entity$2;
-    entityId: string;
-    data?: Record<string, unknown>;
-};
-type TransactionResult = {
-    results: TransactionResultEntry[];
-};
-
 declare class TransactionService {
     private EntityConfig;
     private EmailAuthEnabledEntities;
@@ -4943,19 +4906,6 @@ declare const $default: (container: DependencyContainer) => (event: APIGatewayPr
  */
 declare const broadcast: (container: DependencyContainer) => (event: DynamoDBStreamEvent) => Promise<void>;
 
-declare const transactional: {
-    createEntity: <T extends Entity$2>(entityType: T, payload: EntitySchemaMap[T] & {
-        entityId?: string;
-    }) => TransactionCreateEntity<T>;
-    updateEntity: <T extends Entity$2>(entityType: T, entityId: string, payload: Partial<EntitySchemaMap[T]> & {
-        $condition?: string;
-    }) => TransactionUpdateEntity<T>;
-    adjustEntity: <T extends Entity$2>(entityType: T, entityId: string, adjustments: Record<string, number> & {
-        $condition?: string;
-    }) => TransactionAdjustEntity<T>;
-    deleteEntity: <T extends Entity$2>(entityType: T, entityId: string) => TransactionDeleteEntity<T>;
-};
-
 declare class CoreFactory {
     private config;
     setupCommonRoutes: ReturnType<typeof setupCommonRoutes>;
@@ -4977,4 +4927,4 @@ declare class CoreFactory {
     });
 }
 
-export { DependencyContainer, Entity$1 as Entity, EntityRepository, EntityService, Mutual, MutualRepository, MutualService, PROJECTION_EXPRESSION, StandardError, StandardErrorCode, TagRepository, TransactionService, WebSocketRepository, appHandler, handler$4 as createEntityProcessor, CoreFactory as default, handler$3 as mutualProcessor, handler$2 as prejoinProcessor, handler$1 as replicationProcessor, setupCommonRoutes, handler as tagProcessor, transactional, broadcast as wsBroadcast, connect as wsConnect, $default as wsDefault, disconnect as wsDisconnect };
+export { DependencyContainer, Entity$1 as Entity, EntityRepository, EntityService, Mutual, MutualRepository, MutualService, PROJECTION_EXPRESSION, StandardError, StandardErrorCode, TagRepository, TransactionService, WebSocketRepository, appHandler, handler$4 as createEntityProcessor, CoreFactory as default, handler$3 as mutualProcessor, handler$2 as prejoinProcessor, handler$1 as replicationProcessor, setupCommonRoutes, handler as tagProcessor, broadcast as wsBroadcast, connect as wsConnect, $default as wsDefault, disconnect as wsDisconnect };

package/dist/core/index.js

@@ -9547,7 +9547,7 @@ var DependencyContainer = class {
   }
 };
 
-// helpers/transactional.ts
+// ../base/transactional.ts
 var transactional = {
   createEntity: (entityType, payload) => {
     const _a = payload, { entityId } = _a, rest = __objRest(_a, ["entityId"]);