@apso/cli 0.16.0 → 0.17.0

package/dist/commands/generate.js

@@ -13,7 +13,7 @@ class Generate extends base_command_1.default {
         const { flags } = await this.parse(Generate);
         const skipFormat = flags["skip-format"];
         const totalBuildStart = perf_hooks_1.performance.now();
-        const { rootFolder, entities, relationshipMap, apiType, auth, language: configLanguage } = (0, lib_1.parseApsorc)();
+        const { rootFolder, entities, relationshipMap, apiType, auth, emitEvents, language: configLanguage } = (0, lib_1.parseApsorc)();
         // Resolve language: flag > .apsorc > prompt
         let language;
         if (flags.language) {
@@ -52,6 +52,10 @@ class Generate extends base_command_1.default {
         const autogenPath = path.join(rootPath, "autogen");
         const lowerCaseApiType = apiType.toLowerCase();
         console.log(`[apso] Generating ${language} code for ${entities.length} entities...`);
+        if (entities.length === 0) {
+            console.log("[apso] No entities found in .apsorc — nothing to generate. Check that the file exists and defines an `entities` array.");
+        }
+        let generatedFileCount = 0;
         const generatorConfig = {
             language,
             rootFolder,
@@ -59,6 +63,7 @@ class Generate extends base_command_1.default {
             entities,
             relationshipMap,
             auth,
+            emitEvents,
         };
         const generator = (0, lib_1.createGenerator)(generatorConfig);
         const validationResult = generator.validateConfig(generatorConfig);
@@ -75,6 +80,7 @@ class Generate extends base_command_1.default {
             // eslint-disable-next-line no-await-in-loop
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
+        generatedFileCount += enumFiles.length;
         // Generate shared query utilities
         const queryUtilFiles = await generator.generateQueryUtils(entities, lowerCaseApiType);
         for (const file of queryUtilFiles) {
@@ -82,6 +88,7 @@ class Generate extends base_command_1.default {
             // eslint-disable-next-line no-await-in-loop
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
+        generatedFileCount += queryUtilFiles.length;
         // Generate per-entity files
         for (const entity of entities) {
             console.log(`[apso] Building... ${entity.name}`);
@@ -128,6 +135,7 @@ class Generate extends base_command_1.default {
                     const fullPath = path.join(autogenPath, file.path);
                     // eslint-disable-next-line no-await-in-loop
                     await (0, file_system_1.createFile)(fullPath, file.content);
+                    generatedFileCount += 1;
                 }
             }
             const entityBuildTime = perf_hooks_1.performance.now() - entityBuildStart;
@@ -140,24 +148,40 @@ class Generate extends base_command_1.default {
             // eslint-disable-next-line no-await-in-loop
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
+        generatedFileCount += guardFiles.length;
+        // Generate domain-event spine (only when at least one entity opts in)
+        const domainEventFiles = await generator.generateDomainEvents(entities, lowerCaseApiType, { emitEvents });
+        for (const file of domainEventFiles) {
+            const fullPath = path.join(autogenPath, file.path);
+            // eslint-disable-next-line no-await-in-loop
+            await (0, file_system_1.createFile)(fullPath, file.content);
+        }
         // Generate index module
-        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType);
+        const indexFiles = await generator.generateIndexModule(entities, lowerCaseApiType, { emitEvents });
         for (const file of indexFiles) {
             const fullPath = path.join(autogenPath, file.path);
             // eslint-disable-next-line no-await-in-loop
             await (0, file_system_1.createFile)(fullPath, file.content);
         }
-        // Format generated files (TypeScript only)
-        if (language === "typescript" && !skipFormat) {
+        generatedFileCount += indexFiles.length;
+        // Format generated files (TypeScript only).
+        // Run prettier directly against the generated output directory so we never
+        // reformat hand-written code elsewhere in the project tree (the project's
+        // `npm run format` script targets a broad glob like `{src,test}/**/*.ts`).
+        if (language === "typescript" && !skipFormat && generatedFileCount > 0) {
             const formatStart = perf_hooks_1.performance.now();
-            console.log("[apso] Formatting files...");
-            await this.runNpmCommand(["run", "format", "src/autogen/**/*.ts", "src/guards/**/*.ts"], true);
+            console.log("[apso] Formatting generated files...");
+            const formatGlob = path.join(autogenPath, "**", "*.ts");
+            await this.runCommand("npx", ["prettier", "--write", formatGlob], true);
             const formatTime = perf_hooks_1.performance.now() - formatStart;
             console.log(`[apso] Finished formatting in ${formatTime.toFixed(2)} ms`);
         }
         else if (skipFormat) {
             console.log("[apso] Skipping formatting (--skip-format flag set)");
         }
+        else if (generatedFileCount === 0) {
+            console.log("[apso] Skipping formatting (no files were generated)");
+        }
         const totalBuildTime = perf_hooks_1.performance.now() - totalBuildStart;
         console.log(`[apso] Finished building all entities in ${totalBuildTime.toFixed(2)} ms`);
     }

package/dist/commands/mcp/serve.js

@@ -923,6 +923,7 @@ const INLINE_SCHEMA_REFERENCE = `# Schema Quick Reference
   "updated_at": true,
   "primaryKeyType": "serial",
   "scopeBy": "organizationId",
+  "emitEvents": true,
   "fields": [
     { "name": "fieldName", "type": "text", "length": 100 }
   ],
@@ -932,6 +933,19 @@ const INLINE_SCHEMA_REFERENCE = `# Schema Quick Reference
 }
 \`\`\`
 
+## Domain Events (emitEvents)
+Set \`emitEvents: true\` (per-entity or as a top-level default) to durably log
+state changes. A top-level \`emitEvents: true\` enables it for every entity; an
+individual entity can opt out with \`emitEvents: false\` (effective value is
+\`entity.emitEvents ?? <top-level emitEvents> ?? false\`).
+
+When at least one entity opts in, the generator emits a \`DomainEvent\` spine
+under \`autogen/events/\`: a \`DomainEvent\` entity (table \`events\`), a TypeORM
+\`DomainEventSubscriber\` that writes events in the SAME DB transaction as the
+change, an app-overridable \`DomainEventMapper\` (event-type + payload), and a
+\`DomainEventRelay\` whose \`publish()\` you override to deliver events. The
+\`DomainEventsModule\` is wired into the generated module list automatically.
+
 ## Relationship Types
 - OneToMany: parent has many children
 - ManyToOne: child belongs to parent

package/dist/lib/apsorc-parser.d.ts

@@ -14,6 +14,12 @@ export type ApsorcType = {
     relationships: ApsorcRelationship[];
     auth?: AuthConfig;
     language?: TargetLanguage;
+    /**
+     * Top-level default for the opt-in DomainEvent ("emitEvents") feature.
+     * When true, every entity emits domain events unless it opts out with
+     * its own `emitEvents: false`.
+     */
+    emitEvents?: boolean;
 };
 type ParsedApsorcData = {
     entities: Entity[];
@@ -26,6 +32,8 @@ type ParsedApsorc = {
     relationshipMap: RelationshipMap;
     auth?: AuthConfig;
     language?: TargetLanguage;
+    /** Top-level default for the DomainEvent ("emitEvents") feature. */
+    emitEvents?: boolean;
 };
 export declare const parseApsorcV1: (apsorc: ApsorcType) => ParsedApsorcData;
 export declare const parseApsorcV2: (apsorc: ApsorcType) => ParsedApsorcData;

package/dist/lib/apsorc-parser.js

@@ -36,6 +36,7 @@ const parseRc = () => {
     const relationships = apsoConfig.relationships || [];
     const auth = apsoConfig.auth;
     const language = apsoConfig.language;
+    const emitEvents = apsoConfig.emitEvents;
     return {
         rootFolder,
         apiType,
@@ -44,6 +45,7 @@ const parseRc = () => {
         relationships,
         auth,
         language,
+        emitEvents,
     };
 };
 const parseApsorc = () => {
@@ -63,6 +65,7 @@ const parseApsorc = () => {
                     apiType: apsoConfig.apiType,
                     auth: apsoConfig.auth,
                     language: apsoConfig.language,
+                    emitEvents: apsoConfig.emitEvents,
                     ...(0, exports.parseApsorcV1)(apsoConfig),
                 };
                 if (debug) {
@@ -79,6 +82,7 @@ const parseApsorc = () => {
                     apiType: apsoConfig.apiType,
                     auth: apsoConfig.auth,
                     language: apsoConfig.language,
+                    emitEvents: apsoConfig.emitEvents,
                     ...(() => {
                         const relStart = perf_hooks_1.performance.now();
                         const parsed = (0, exports.parseApsorcV2)(apsoConfig);

package/dist/lib/base-command.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "@oclif/core";
 export default abstract class BaseCommand extends Command {
+    runCommand(command: string, args: string[], silent?: boolean): Promise<void>;
     runNpmCommand(args: string[], silent?: boolean): Promise<void>;
 }

package/dist/lib/base-command.js

@@ -5,14 +5,14 @@ const core_1 = require("@oclif/core");
 const child_process_1 = require("child_process");
 const os_1 = tslib_1.__importDefault(require("os"));
 class BaseCommand extends core_1.Command {
-    async runNpmCommand(args, silent = false) {
+    async runCommand(command, args, silent = false) {
         return new Promise((resolve, reject) => {
             const isWindows = os_1.default.platform() === "win32";
-            const command = isWindows ? "npm.cmd" : "npm";
+            const resolvedCommand = isWindows ? `${command}.cmd` : command;
             const stdio = silent ? "ignore" : "inherit";
-            const cmdStr = `${command} ${args.join(" ")}`;
+            const cmdStr = `${resolvedCommand} ${args.join(" ")}`;
             this.log(`Running: ${cmdStr}`);
-            const child = (0, child_process_1.spawn)(command, args, {
+            const child = (0, child_process_1.spawn)(resolvedCommand, args, {
                 stdio,
                 shell: isWindows,
             });
@@ -28,5 +28,8 @@ class BaseCommand extends core_1.Command {
             });
         });
     }
+    async runNpmCommand(args, silent = false) {
+        return this.runCommand("npm", args, silent);
+    }
 }
 exports.default = BaseCommand;

package/dist/lib/events.d.ts

@@ -0,0 +1,31 @@
+import { Entity } from "./types";
+/**
+ * Helpers for the opt-in DomainEvent ("emitEvents") feature.
+ *
+ * This implements the standard transactional-outbox pattern for durability, but
+ * is surfaced with generic "domain event" naming (the user found "outbox"
+ * unintuitive). No public artifact is named "outbox".
+ *
+ * Flag resolution: the effective per-entity value is
+ *   `entity.emitEvents ?? globalEmitEvents ?? false`
+ * so a top-level `emitEvents: true` enables it for every entity, while an
+ * individual entity can opt out with `emitEvents: false` (global default WITH
+ * per-entity opt-out).
+ */
+/**
+ * Computes whether a single entity has domain events enabled, given the
+ * top-level (global) default.
+ */
+export declare function isEmitEventsEnabled(entity: Entity, globalEmitEvents?: boolean): boolean;
+/**
+ * Computes the set of entities that have opted in to domain-event emission.
+ * This is the single source of truth used everywhere (generator, wiring,
+ * subscriber scoping).
+ */
+export declare function getEventEmittingEntities(entities: Entity[], globalEmitEvents?: boolean): Entity[];
+/**
+ * Returns true when at least one entity has domain events enabled, meaning the
+ * DomainEvent spine (entity, subscriber, mapper, relay, module) should be
+ * generated.
+ */
+export declare function hasEventEmittingEntities(entities: Entity[], globalEmitEvents?: boolean): boolean;

package/dist/lib/events.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasEventEmittingEntities = exports.getEventEmittingEntities = exports.isEmitEventsEnabled = void 0;
+/**
+ * Helpers for the opt-in DomainEvent ("emitEvents") feature.
+ *
+ * This implements the standard transactional-outbox pattern for durability, but
+ * is surfaced with generic "domain event" naming (the user found "outbox"
+ * unintuitive). No public artifact is named "outbox".
+ *
+ * Flag resolution: the effective per-entity value is
+ *   `entity.emitEvents ?? globalEmitEvents ?? false`
+ * so a top-level `emitEvents: true` enables it for every entity, while an
+ * individual entity can opt out with `emitEvents: false` (global default WITH
+ * per-entity opt-out).
+ */
+/**
+ * Computes whether a single entity has domain events enabled, given the
+ * top-level (global) default.
+ */
+function isEmitEventsEnabled(entity, globalEmitEvents) {
+    var _a, _b;
+    return (_b = (_a = entity.emitEvents) !== null && _a !== void 0 ? _a : globalEmitEvents) !== null && _b !== void 0 ? _b : false;
+}
+exports.isEmitEventsEnabled = isEmitEventsEnabled;
+/**
+ * Computes the set of entities that have opted in to domain-event emission.
+ * This is the single source of truth used everywhere (generator, wiring,
+ * subscriber scoping).
+ */
+function getEventEmittingEntities(entities, globalEmitEvents) {
+    return entities.filter((entity) => isEmitEventsEnabled(entity, globalEmitEvents));
+}
+exports.getEventEmittingEntities = getEventEmittingEntities;
+/**
+ * Returns true when at least one entity has domain events enabled, meaning the
+ * DomainEvent spine (entity, subscriber, mapper, relay, module) should be
+ * generated.
+ */
+function hasEventEmittingEntities(entities, globalEmitEvents) {
+    return entities.some((entity) => isEmitEventsEnabled(entity, globalEmitEvents));
+}
+exports.hasEventEmittingEntities = hasEventEmittingEntities;

package/dist/lib/generators/base.d.ts

@@ -52,7 +52,9 @@ export declare abstract class BaseGenerator implements LanguageGenerator {
     /**
      * Generate the index/main module file
      */
-    abstract generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    abstract generateIndexModule(entities: Entity[], apiType: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Generate guard files (auth, scope, etc.)
      */
@@ -62,6 +64,14 @@ export declare abstract class BaseGenerator implements LanguageGenerator {
      * Default no-op. Override in language generators that need query utils.
      */
     generateQueryUtils(_entities: Entity[], _apiType: string): Promise<GeneratedFile[]>;
+    /**
+     * Generate the durable DomainEvent spine for entities that opt in to
+     * `emitEvents` (transactional-outbox pattern, generic domain-event naming).
+     * Default no-op. Override in language generators that support it.
+     */
+    generateDomainEvents(_entities: Entity[], _apiType?: string, _opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Render a template file with the given data
      */

package/dist/lib/generators/base.js

@@ -27,6 +27,14 @@ class BaseGenerator {
     async generateQueryUtils(_entities, _apiType) {
         return [];
     }
+    /**
+     * Generate the durable DomainEvent spine for entities that opt in to
+     * `emitEvents` (transactional-outbox pattern, generic domain-event naming).
+     * Default no-op. Override in language generators that support it.
+     */
+    async generateDomainEvents(_entities, _apiType, _opts) {
+        return [];
+    }
     /**
      * Render a template file with the given data
      */

package/dist/lib/generators/typescript.d.ts

@@ -16,8 +16,25 @@ export declare class TypeScriptGenerator extends BaseGenerator {
     generateModule(options: EntityGenerationOptions): Promise<GeneratedFile[]>;
     generateMigration(_options: MigrationGenerationOptions): Promise<GeneratedFile[]>;
     generateEnums(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
-    generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    generateIndexModule(entities: Entity[], apiType: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     generateGuards(entities: Entity[], auth?: AuthConfig): Promise<GeneratedFile[]>;
+    /**
+     * Generates the durable DomainEvent spine (transactional-outbox pattern,
+     * surfaced with generic domain-event naming) when at least one entity has
+     * opted in to `emitEvents`.
+     *
+     * Returns an empty array when no entity is opted in, so callers can skip
+     * wiring entirely.
+     *
+     * @param entities All entities from the configuration
+     * @param _apiType API type (unused; events are REST/Graphql agnostic)
+     * @param opts.emitEvents Top-level (global) default for emitEvents
+     */
+    generateDomainEvents(entities: Entity[], _apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Normalizes auth config by applying defaults for DB session providers
      */

package/dist/lib/generators/typescript.js

@@ -15,6 +15,7 @@ const fs = tslib_1.__importStar(require("fs"));
 const os = tslib_1.__importStar(require("os"));
 const util_1 = require("util");
 const guards_1 = require("../guards");
+const events_1 = require("../events");
 const auth_1 = require("../types/auth");
 const unlinkAsync = (0, util_1.promisify)(fs.unlink);
 /**
@@ -302,8 +303,9 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
             },
         ];
     }
-    async generateIndexModule(entities, apiType) {
-        const content = await this.renderTemplate(`./${apiType}/index-module-${apiType}`, { entities });
+    async generateIndexModule(entities, apiType, opts) {
+        const emitDomainEvents = (0, events_1.getEventEmittingEntities)(entities, opts === null || opts === void 0 ? void 0 : opts.emitEvents).length > 0;
+        const content = await this.renderTemplate(`./${apiType}/index-module-${apiType}`, { entities, emitDomainEvents });
         return [
             {
                 path: "index.ts",
@@ -355,6 +357,64 @@ class TypeScriptGenerator extends base_1.BaseGenerator {
         });
         return files;
     }
+    /**
+     * Generates the durable DomainEvent spine (transactional-outbox pattern,
+     * surfaced with generic domain-event naming) when at least one entity has
+     * opted in to `emitEvents`.
+     *
+     * Returns an empty array when no entity is opted in, so callers can skip
+     * wiring entirely.
+     *
+     * @param entities All entities from the configuration
+     * @param _apiType API type (unused; events are REST/Graphql agnostic)
+     * @param opts.emitEvents Top-level (global) default for emitEvents
+     */
+    async generateDomainEvents(entities, _apiType, opts) {
+        const emittingEntities = (0, events_1.getEventEmittingEntities)(entities, opts === null || opts === void 0 ? void 0 : opts.emitEvents);
+        if (emittingEntities.length === 0) {
+            return [];
+        }
+        const templateData = {
+            emittingEntities: emittingEntities.map((entity) => ({
+                name: entity.name,
+            })),
+            generatedAt: new Date().toISOString(),
+            generatedBy: "Apso CLI",
+        };
+        const files = [];
+        const targets = [
+            {
+                template: "./events/domain-event.entity.eta",
+                path: "events/domain-event.entity.ts",
+            },
+            {
+                template: "./events/domain-event.mapper.eta",
+                path: "events/domain-event.mapper.ts",
+            },
+            {
+                template: "./events/domain-event.subscriber.eta",
+                path: "events/domain-event.subscriber.ts",
+            },
+            {
+                template: "./events/domain-event.relay.eta",
+                path: "events/domain-event.relay.ts",
+            },
+            {
+                template: "./events/domain-events.module.eta",
+                path: "events/domain-events.module.ts",
+            },
+            {
+                template: "./events/index.eta",
+                path: "events/index.ts",
+            },
+        ];
+        for (const target of targets) {
+            // eslint-disable-next-line no-await-in-loop
+            const content = await this.renderTemplate(target.template, templateData);
+            files.push({ path: target.path, content });
+        }
+        return files;
+    }
     /**
      * Normalizes auth config by applying defaults for DB session providers
      */

package/dist/lib/index.d.ts

@@ -1,5 +1,6 @@
 export { Entity, RelationshipMap } from "./types";
 export { parseApsorc } from "./apsorc-parser";
 export { hasScopedEntities, getScopedEntities } from "./guards";
+export { isEmitEventsEnabled, getEventEmittingEntities, hasEventEmittingEntities, } from "./events";
 export { BaseGenerator, TypeScriptGenerator, createGenerator, isLanguageSupported, getSupportedLanguages, getImplementedLanguages, } from "./generators";
 export type { TargetLanguage, GeneratedFile, ValidationResult, GeneratorConfig, LanguageGenerator, } from "./types";

package/dist/lib/index.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getImplementedLanguages = exports.getSupportedLanguages = exports.isLanguageSupported = exports.createGenerator = exports.TypeScriptGenerator = exports.BaseGenerator = exports.getScopedEntities = exports.hasScopedEntities = exports.parseApsorc = void 0;
+exports.getImplementedLanguages = exports.getSupportedLanguages = exports.isLanguageSupported = exports.createGenerator = exports.TypeScriptGenerator = exports.BaseGenerator = exports.hasEventEmittingEntities = exports.getEventEmittingEntities = exports.isEmitEventsEnabled = exports.getScopedEntities = exports.hasScopedEntities = exports.parseApsorc = void 0;
 var apsorc_parser_1 = require("./apsorc-parser");
 Object.defineProperty(exports, "parseApsorc", { enumerable: true, get: function () { return apsorc_parser_1.parseApsorc; } });
 var guards_1 = require("./guards");
 Object.defineProperty(exports, "hasScopedEntities", { enumerable: true, get: function () { return guards_1.hasScopedEntities; } });
 Object.defineProperty(exports, "getScopedEntities", { enumerable: true, get: function () { return guards_1.getScopedEntities; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "isEmitEventsEnabled", { enumerable: true, get: function () { return events_1.isEmitEventsEnabled; } });
+Object.defineProperty(exports, "getEventEmittingEntities", { enumerable: true, get: function () { return events_1.getEventEmittingEntities; } });
+Object.defineProperty(exports, "hasEventEmittingEntities", { enumerable: true, get: function () { return events_1.hasEventEmittingEntities; } });
 // Generator exports
 var generators_1 = require("./generators");
 Object.defineProperty(exports, "BaseGenerator", { enumerable: true, get: function () { return generators_1.BaseGenerator; } });

package/dist/lib/templates/events/domain-event.entity.eta

@@ -0,0 +1,51 @@
+<%~ includeFile('../header.eta') %>
+
+import {
+  Entity,
+  PrimaryGeneratedColumn,
+  Column,
+  CreateDateColumn,
+  Index,
+} from 'typeorm';
+
+/**
+ * DomainEvent is a durable, append-only log of domain state changes.
+ *
+ * Rows are written in the SAME database transaction as the state change that
+ * produced them (see DomainEventSubscriber), which is what makes delivery
+ * durable. This implements the standard "transactional outbox" pattern, but is
+ * surfaced with generic domain-event naming.
+ *
+ * A separate DomainEventRelay polls pending rows and delivers them. Because the
+ * stable `id` is preserved across delivery attempts, consumers can dedupe on it
+ * for at-least-once delivery semantics.
+ */
+@Index(['status', 'created_at'])
+@Entity('events')
+export class DomainEvent {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  /** Event type, e.g. "product.created". */
+  @Column({ type: 'varchar' })
+  type: string;
+
+  /** Serialized event payload. */
+  @Column({ type: 'jsonb' })
+  payload: Record<string, unknown>;
+
+  /** Delivery lifecycle: pending -> published, or failed after max attempts. */
+  @Column({ type: 'varchar', default: 'pending' })
+  status: 'pending' | 'published' | 'failed';
+
+  /** Number of delivery attempts made by the relay. */
+  @Column({ type: 'int', default: 0 })
+  attempts: number;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  created_at: Date;
+
+  /** When the event was successfully published; null until then. */
+  @Column({ type: 'timestamptz', nullable: true })
+  publishedAt: Date | null;
+}

package/dist/lib/templates/events/domain-event.mapper.eta

@@ -0,0 +1,62 @@
+<%~ includeFile('../header.eta') %>
+
+import { Injectable } from '@nestjs/common';
+
+/**
+ * Action that produced a domain event.
+ */
+export type DomainEventAction = 'created' | 'updated' | 'removed';
+
+/**
+ * DI token for the DomainEventMapper.
+ *
+ * The generated DomainEventsModule binds this token to DefaultDomainEventMapper.
+ * Your application can override it by providing its own implementation:
+ *
+ *   { provide: DOMAIN_EVENT_MAPPER, useClass: MyDomainEventMapper }
+ */
+export const DOMAIN_EVENT_MAPPER = 'DOMAIN_EVENT_MAPPER';
+
+/**
+ * DomainEventMapper is the extension point that keeps application semantics
+ * (event-type taxonomy, payload shape) OUT of the generated code. Provide your
+ * own implementation under DOMAIN_EVENT_MAPPER to customize.
+ */
+export interface DomainEventMapper {
+  /**
+   * Maps an entity name + action to an event type string, e.g.
+   * ("Product", "created") -> "product.created".
+   */
+  eventType(entityName: string, action: DomainEventAction): string;
+
+  /**
+   * Builds the serializable payload for an event from the changed entity.
+   */
+  toPayload(
+    entity: unknown,
+    action: DomainEventAction
+  ): Record<string, unknown>;
+}
+
+/**
+ * Default mapper. Uses an `entity.action` type taxonomy (entity name
+ * lower-camel-cased) and returns the entity as-is (shallow) as the payload.
+ *
+ * Override by providing your own DomainEventMapper under DOMAIN_EVENT_MAPPER.
+ */
+@Injectable()
+export class DefaultDomainEventMapper implements DomainEventMapper {
+  eventType(entityName: string, action: DomainEventAction): string {
+    const normalized = entityName
+      ? entityName.charAt(0).toLowerCase() + entityName.slice(1)
+      : entityName;
+    return `${normalized}.${action}`;
+  }
+
+  toPayload(
+    entity: unknown,
+    _action: DomainEventAction
+  ): Record<string, unknown> {
+    return { ...(entity as Record<string, unknown>) };
+  }
+}

package/dist/lib/templates/events/domain-event.relay.eta

@@ -0,0 +1,86 @@
+<%~ includeFile('../header.eta') %>
+
+import { Injectable, Logger } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { DomainEvent } from './domain-event.entity';
+
+/**
+ * Maximum number of delivery attempts before an event is marked 'failed'.
+ */
+const MAX_ATTEMPTS = 5;
+
+/**
+ * DomainEventRelay drains the durable `events` table and delivers pending
+ * events. It is the consumer side of the transactional-outbox pattern: the
+ * subscriber writes events transactionally, the relay publishes them
+ * asynchronously with at-least-once semantics.
+ *
+ * DELIVERY is the extension point: override `publish()` (see below) to send
+ * events anywhere — webhooks, Kafka, SNS, an internal event bus, etc. The
+ * generated code intentionally does NOT implement any specific transport.
+ */
+@Injectable()
+export class DomainEventRelay {
+  private readonly logger = new Logger(DomainEventRelay.name);
+
+  constructor(
+    @InjectRepository(DomainEvent)
+    private readonly events: Repository<DomainEvent>
+  ) {}
+
+  /**
+   * Schedule this from your app, e.g. with @nestjs/schedule:
+   *
+   *   // import { Interval } from '@nestjs/schedule';
+   *   // @Interval(5000)
+   *   // async tick() { await this.relay.processPending(); }
+   *
+   * (@nestjs/schedule is intentionally NOT imported here so no dependency is
+   * forced on your project.)
+   */
+  async processPending(limit = 50): Promise<void> {
+    const pending = await this.events.find({
+      where: { status: 'pending' },
+      order: { created_at: 'ASC' },
+      take: limit,
+    });
+
+    for (const event of pending) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        await this.publish(event);
+        event.status = 'published';
+        event.publishedAt = new Date();
+        // eslint-disable-next-line no-await-in-loop
+        await this.events.save(event);
+      } catch (error) {
+        event.attempts += 1;
+        if (event.attempts >= MAX_ATTEMPTS) {
+          event.status = 'failed';
+          this.logger.error(
+            `DomainEvent ${event.id} (${event.type}) failed after ${event.attempts} attempts`,
+            error instanceof Error ? error.stack : undefined
+          );
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await this.events.save(event);
+      }
+    }
+  }
+
+  /**
+   * EXTENSION POINT — deliver a single domain event.
+   *
+   * Override (subclass or re-provide) this method to actually publish events to
+   * your transport of choice (webhooks, Kafka, SNS, internal bus, ...). On
+   * success the relay marks the event published; on a thrown error it retries
+   * up to MAX_ATTEMPTS and then marks it failed.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async publish(event: DomainEvent): Promise<void> {
+    throw new Error(
+      'DomainEventRelay.publish() not implemented — override to deliver events'
+    );
+  }
+}

package/dist/lib/templates/events/domain-event.subscriber.eta

@@ -0,0 +1,118 @@
+<%~ includeFile('../header.eta') %>
+
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import {
+  DataSource,
+  EntitySubscriberInterface,
+  EventSubscriber,
+  InsertEvent,
+  UpdateEvent,
+  RemoveEvent,
+} from 'typeorm';
+import { DomainEvent } from './domain-event.entity';
+import {
+  DOMAIN_EVENT_MAPPER,
+  DomainEventAction,
+  DomainEventMapper,
+} from './domain-event.mapper';
+<% it.emittingEntities.forEach((entity) => { %>
+import { <%= entity.name %> } from '../<%= entity.name %>/<%= entity.name %>.entity';
+<% }) %>
+
+/**
+ * Entity classes that have opted in to domain-event emission. Only state
+ * changes to these entities produce DomainEvent rows; everything else is
+ * skipped.
+ */
+const EMITTING_ENTITIES: Function[] = [
+<% it.emittingEntities.forEach((entity) => { %>
+  <%= entity.name %>,
+<% }) %>
+];
+
+/**
+ * DomainEventSubscriber writes a DomainEvent row for every insert/update/remove
+ * of an opted-in entity.
+ *
+ * DURABILITY: each row is written via `event.manager` (the EntityManager of the
+ * in-flight transaction), so the event is committed atomically WITH the state
+ * change. This is the durability lever behind the transactional-outbox pattern.
+ *
+ * RECURSION GUARD: we never emit events for DomainEvent itself, otherwise each
+ * emitted row would itself trigger another emission. Any other bookkeeping
+ * tables you do not want logged should likewise be excluded from
+ * EMITTING_ENTITIES (this scoping handles that — only opted-in entities emit).
+ */
+@Injectable()
+@EventSubscriber()
+export class DomainEventSubscriber implements EntitySubscriberInterface {
+  constructor(
+    @Inject(DOMAIN_EVENT_MAPPER) private readonly mapper: DomainEventMapper,
+    // MULTI-DATASOURCE: Nest auto-registers @EventSubscriber() providers on the
+    // DEFAULT DataSource. We ALSO push ourselves onto any injected DataSource
+    // here so registration is robust for named/non-default DataSources too. For
+    // multiple DataSources, register DomainEventsModule per DataSource.
+    @Optional() dataSource?: DataSource
+  ) {
+    dataSource?.subscribers?.push(this);
+  }
+
+  private isEmitting(target: Function | string): boolean {
+    // RECURSION GUARD: never emit for DomainEvent itself.
+    if (target === DomainEvent || target === 'DomainEvent') {
+      return false;
+    }
+    return EMITTING_ENTITIES.some(
+      (cls) => target === cls || target === cls.name
+    );
+  }
+
+  private async emit(
+    manager: InsertEvent<unknown>['manager'],
+    entityClass: Function,
+    entity: unknown,
+    action: DomainEventAction
+  ): Promise<void> {
+    const entityName = entityClass.name;
+    const repo = manager.getRepository(DomainEvent);
+    // event.manager keeps us inside the active transaction.
+    await repo.save(
+      repo.create({
+        type: this.mapper.eventType(entityName, action),
+        payload: this.mapper.toPayload(entity, action),
+        status: 'pending',
+        attempts: 0,
+      })
+    );
+  }
+
+  async afterInsert(event: InsertEvent<unknown>): Promise<void> {
+    if (!this.isEmitting(event.metadata.target)) return;
+    await this.emit(
+      event.manager,
+      event.metadata.target as Function,
+      event.entity,
+      'created'
+    );
+  }
+
+  async afterUpdate(event: UpdateEvent<unknown>): Promise<void> {
+    if (!this.isEmitting(event.metadata.target)) return;
+    await this.emit(
+      event.manager,
+      event.metadata.target as Function,
+      event.entity ?? event.databaseEntity,
+      'updated'
+    );
+  }
+
+  async afterRemove(event: RemoveEvent<unknown>): Promise<void> {
+    if (!this.isEmitting(event.metadata.target)) return;
+    await this.emit(
+      event.manager,
+      event.metadata.target as Function,
+      event.entity ?? event.databaseEntity,
+      'removed'
+    );
+  }
+}

package/dist/lib/templates/events/domain-events.module.eta

@@ -0,0 +1,40 @@
+<%~ includeFile('../header.eta') %>
+
+import { Global, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { DomainEvent } from './domain-event.entity';
+import { DomainEventSubscriber } from './domain-event.subscriber';
+import { DomainEventRelay } from './domain-event.relay';
+import {
+  DOMAIN_EVENT_MAPPER,
+  DefaultDomainEventMapper,
+} from './domain-event.mapper';
+
+/**
+ * DomainEventsModule wires the durable domain-event spine (transactional-outbox
+ * pattern, surfaced as generic domain events).
+ *
+ * - DomainEventSubscriber writes events in-transaction with state changes.
+ * - DomainEventRelay drains and delivers pending events (override
+ *   DomainEventRelay.publish()).
+ * - DOMAIN_EVENT_MAPPER controls event-type/payload semantics; override by
+ *   re-providing the token with your own DomainEventMapper.
+ *
+ * MULTI-DATASOURCE: @EventSubscriber() auto-registers on the default DataSource;
+ * for additional named DataSources, register this module (or the subscriber)
+ * per DataSource.
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([DomainEvent])],
+  providers: [
+    DomainEventSubscriber,
+    DomainEventRelay,
+    {
+      provide: DOMAIN_EVENT_MAPPER,
+      useClass: DefaultDomainEventMapper,
+    },
+  ],
+  exports: [DomainEventRelay, DOMAIN_EVENT_MAPPER],
+})
+export class DomainEventsModule {}

package/dist/lib/templates/events/index.eta

@@ -0,0 +1,7 @@
+<%~ includeFile('../header.eta') %>
+
+export * from './domain-event.entity';
+export * from './domain-event.subscriber';
+export * from './domain-event.mapper';
+export * from './domain-event.relay';
+export * from './domain-events.module';

package/dist/lib/templates/graphql/index-module-graphql.eta

@@ -3,6 +3,9 @@
 <% it.entities.forEach((entity) => { %>
 import {<%= entity.name %>Module} from './<%= entity.name %>/<%= entity.name %>.module'
 <%}) %>
+<% if (it.emitDomainEvents) { %>
+import { DomainEventsModule } from './events'
+<% } %>
 import { JSONResolver } from 'graphql-scalars';
 
 <% const scalars = [] %>
@@ -23,4 +26,7 @@ export default [
 <% it.entities.forEach((entity) => { %>
 <%= entity.name %>Module,
 <%}) %>
+<% if (it.emitDomainEvents) { %>
+DomainEventsModule,
+<% } %>
 ]

package/dist/lib/templates/rest/index-module-rest.eta

@@ -3,9 +3,15 @@
 <% it.entities.forEach((entity) => { %>
 import {<%= entity.name %>Module} from './<%= entity.name %>/<%= entity.name %>.module'
 <%}) %>
+<% if (it.emitDomainEvents) { %>
+import { DomainEventsModule } from './events'
+<% } %>
 
 export default [
 <% it.entities.forEach((entity) => { %>
 <%= entity.name %>Module,
 <%}) %>
+<% if (it.emitDomainEvents) { %>
+DomainEventsModule,
+<% } %>
 ]

package/dist/lib/types/entity.d.ts

@@ -45,5 +45,15 @@ export interface Entity {
      * Optional configuration for how scope enforcement should behave.
      */
     scopeOptions?: ScopeOptions;
+    /**
+     * When true, state changes to this entity (insert/update/remove) emit a
+     * durable DomainEvent row written in the SAME database transaction as the
+     * change (transactional-outbox pattern, surfaced as generic "domain events").
+     *
+     * Resolution: the effective value is `entity.emitEvents ?? <global emitEvents> ?? false`.
+     * This means a top-level `emitEvents: true` enables it for every entity, while
+     * an individual entity can opt out with `emitEvents: false`.
+     */
+    emitEvents?: boolean;
     associations?: Association[];
 }

package/dist/lib/types/generator.d.ts

@@ -104,6 +104,11 @@ export interface GeneratorConfig {
      * Authentication configuration (optional)
      */
     auth?: AuthConfig;
+    /**
+     * Top-level default for the opt-in DomainEvent ("emitEvents") feature.
+     * Effective per-entity value is `entity.emitEvents ?? emitEvents ?? false`.
+     */
+    emitEvents?: boolean;
     /**
      * Language-specific configuration options
      */
@@ -229,7 +234,9 @@ export interface LanguageGenerator {
     /**
      * Generate the index/main module file that ties everything together
      */
-    generateIndexModule(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    generateIndexModule(entities: Entity[], apiType: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
     /**
      * Generate guard files (auth, scope, etc.)
      */
@@ -238,6 +245,13 @@ export interface LanguageGenerator {
      * Generate shared query utility files (filter, sort, pagination)
      */
     generateQueryUtils(entities: Entity[], apiType: string): Promise<GeneratedFile[]>;
+    /**
+     * Generate the durable DomainEvent spine for entities that opt in to
+     * `emitEvents`. Returns [] when no entity is opted in.
+     */
+    generateDomainEvents(entities: Entity[], apiType?: string, opts?: {
+        emitEvents?: boolean;
+    }): Promise<GeneratedFile[]>;
 }
 /**
  * Factory function type for creating language generators

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@apso/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@apso/cli",
-      "version": "0.16.0",
+      "version": "0.17.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@electric-sql/pglite": "^0.2.17",

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.16.0",
+  "version": "0.17.0",
   "commands": {
     "config": {
       "id": "config",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "mcpName": "io.github.apsoai/apso",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",