@zintrust/core 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {

package/src/boot/Application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Application.d.ts","sourceRoot":"","sources":["../../../src/boot/Application.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAoB,MAAM,8BAA8B,CAAC;AAEnF,OAAO,EAAE,gBAAgB,EAAmB,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AASxD,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,IAAI,OAAO,CAAC;IACpB,aAAa,IAAI,OAAO,CAAC;IACzB,YAAY,IAAI,OAAO,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC;IACrB,cAAc,IAAI,MAAM,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IACvC,WAAW,IAAI,MAAM,CAAC;CACvB;AAkVD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM,GAAG,YAAY;EA0CvC,CAAC;AAEH,eAAe,WAAW,CAAC"}
+{"version":3,"file":"Application.d.ts","sourceRoot":"","sources":["../../../src/boot/Application.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,iBAAiB,EAAoB,MAAM,8BAA8B,CAAC;AAEnF,OAAO,EAAE,gBAAgB,EAAmB,MAAM,8BAA8B,CAAC;AACjF,OAAO,EAAE,KAAK,OAAO,EAAU,MAAM,kBAAkB,CAAC;AASxD,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,IAAI,OAAO,CAAC;IACpB,aAAa,IAAI,OAAO,CAAC;IACzB,YAAY,IAAI,OAAO,CAAC;IACxB,SAAS,IAAI,OAAO,CAAC;IACrB,cAAc,IAAI,MAAM,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC;IACrB,YAAY,IAAI,iBAAiB,CAAC;IAClC,kBAAkB,IAAI,gBAAgB,CAAC;IACvC,WAAW,IAAI,MAAM,CAAC;CACvB;AAsUD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;sBACe,MAAM,GAAG,YAAY;EA0CvC,CAAC;AAEH,eAAe,WAAW,CAAC"}

package/src/boot/Application.js

@@ -197,6 +197,34 @@ const initializeArtifactDirectories = async (resolvedBasePath) => {
         }
     }
 };
+const tryImportOptional = async (modulePath) => {
+    try {
+        return (await import(modulePath));
+    }
+    catch {
+        return undefined;
+    }
+};
+const registerFromRuntimeConfig = async () => {
+    const db = await tryImportOptional('@orm/DatabaseRuntimeRegistration');
+    db?.registerDatabasesFromRuntimeConfig?.(databaseConfig);
+    const queues = await tryImportOptional('@tools/queue/QueueRuntimeRegistration');
+    queues?.registerQueuesFromRuntimeConfig?.(queueConfig);
+    const caches = await tryImportOptional('@cache/CacheRuntimeRegistration');
+    caches?.registerCachesFromRuntimeConfig?.(cacheConfig);
+    const broadcasters = await tryImportOptional('@broadcast/BroadcastRuntimeRegistration');
+    broadcasters?.registerBroadcastersFromRuntimeConfig?.({
+        default: broadcastConfig.default,
+        drivers: broadcastConfig.drivers,
+    });
+    const disks = await tryImportOptional('@storage/StorageRuntimeRegistration');
+    disks?.registerDisksFromRuntimeConfig?.(storageConfig);
+    const notifications = await tryImportOptional('@notification/NotificationRuntimeRegistration');
+    notifications?.registerNotificationChannelsFromRuntimeConfig?.({
+        default: notificationConfig.default,
+        drivers: notificationConfig.drivers,
+    });
+};
 const createLifecycle = (params) => {
     const boot = async () => {
         if (params.getBooted())
@@ -205,67 +233,7 @@ const createLifecycle = (params) => {
         StartupConfigValidator.assertValid();
         FeatureFlags.initialize();
         await StartupHealthChecks.assertHealthy();
-        // Register ORM database connections from runtime config.
-        // This makes every `databaseConfig.connections[name]` available via `useDatabase(undefined, name)`.
-        // The configured default is also registered as 'default'.
-        try {
-            const { registerDatabasesFromRuntimeConfig } = await import('../orm/DatabaseRuntimeRegistration.js');
-            registerDatabasesFromRuntimeConfig(databaseConfig);
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
-        // Register queue drivers from runtime config.
-        // Ensures default drivers like `sync` are available without manual registration.
-        try {
-            const { registerQueuesFromRuntimeConfig } = await import('../tools/queue/QueueRuntimeRegistration.js');
-            registerQueuesFromRuntimeConfig(queueConfig);
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
-        // Register cache driver factories from runtime config.
-        // Ensures built-in drivers are available via the driver registry.
-        try {
-            const { registerCachesFromRuntimeConfig } = await import('../cache/CacheRuntimeRegistration.js');
-            registerCachesFromRuntimeConfig(cacheConfig);
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
-        // Register broadcasters from runtime config.
-        // Ensures named broadcasters are available and unknown names throw when selected.
-        try {
-            const { registerBroadcastersFromRuntimeConfig } = await import('../tools/broadcast/BroadcastRuntimeRegistration.js');
-            registerBroadcastersFromRuntimeConfig({
-                default: broadcastConfig.default,
-                drivers: broadcastConfig.drivers,
-            });
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
-        // Register storage disks from runtime config.
-        // Ensures named disks are available and 'default' is a reserved alias.
-        try {
-            const { registerDisksFromRuntimeConfig } = await import('../tools/storage/StorageRuntimeRegistration.js');
-            registerDisksFromRuntimeConfig(storageConfig);
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
-        // Register notification channels from runtime config.
-        // Enables selecting named channels and reserves the `default` alias.
-        try {
-            const { registerNotificationChannelsFromRuntimeConfig } = await import('../tools/notification/NotificationRuntimeRegistration.js');
-            registerNotificationChannelsFromRuntimeConfig({
-                default: notificationConfig.default,
-                drivers: notificationConfig.drivers,
-            });
-        }
-        catch {
-            // best-effort: ignore in restrictive runtimes
-        }
+        await registerFromRuntimeConfig();
         await initializeArtifactDirectories(params.resolvedBasePath);
         await registerRoutes(params.resolvedBasePath, params.router);
         // Register service providers

package/src/cli/CLI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyBH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AAsLD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}
+{"version":3,"file":"CLI.d.ts","sourceRoot":"","sources":["../../../src/cli/CLI.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4BH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,MAAM,WAAW,IAAI;IACnB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,IAAI,OAAO,CAAC;CACvB;AAyLD;;;;;;;GAOG;AACH,eAAO,MAAM,GAAG;cACJ,IAAI;EAed,CAAC"}

package/src/cli/CLI.js

@@ -3,6 +3,7 @@
  * Orchestrates all CLI commands using Commander
  */
 import { AddCommand } from './commands/AddCommand.js';
+import { BroadcastWorkCommand } from './commands/BroadcastWorkCommand.js';
 import { ConfigCommand } from './commands/ConfigCommand.js';
 import { D1MigrateCommand } from './commands/D1MigrateCommand.js';
 import { DebugCommand } from './commands/DebugCommand.js';
@@ -12,9 +13,11 @@ import { MakeMailTemplateCommand } from './commands/MakeMailTemplateCommand.js';
 import { MakeNotificationTemplateCommand } from './commands/MakeNotificationTemplateCommand.js';
 import { MigrateCommand } from './commands/MigrateCommand.js';
 import { NewCommand } from './commands/NewCommand.js';
+import { NotificationWorkCommand } from './commands/NotificationWorkCommand.js';
 import { PluginCommand } from './commands/PluginCommand.js';
 import { PrepareCommand } from './commands/PrepareCommand.js';
 import { QACommand } from './commands/QACommand.js';
+import { QueueCommand } from './commands/QueueCommand.js';
 import { SecretsCommand } from './commands/SecretsCommand.js';
 import { SimulateCommand } from './commands/SimulateCommand.js';
 import { StartCommand } from './commands/StartCommand.js';
@@ -68,6 +71,9 @@ const registerCommands = (program) => {
         PrepareCommand,
         AddCommand.create(),
         StartCommand.create(),
+        QueueCommand.create(),
+        BroadcastWorkCommand.create(),
+        NotificationWorkCommand.create(),
         MigrateCommand.create(),
         D1MigrateCommand.create(),
         DebugCommand.create(),

package/src/cli/commands/BroadcastWorkCommand.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Broadcast Work Command
+ * Alias to work a broadcast queue.
+ */
+import { type IBaseCommand } from '../BaseCommand';
+export declare const BroadcastWorkCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default BroadcastWorkCommand;
+//# sourceMappingURL=BroadcastWorkCommand.d.ts.map

package/src/cli/commands/BroadcastWorkCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastWorkCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/BroadcastWorkCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAQtB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/src/cli/commands/BroadcastWorkCommand.js

@@ -0,0 +1,16 @@
+/**
+ * Broadcast Work Command
+ * Alias to work a broadcast queue.
+ */
+import { createKindWorkCommand } from '../commands/createKindWorkCommand.js';
+export const BroadcastWorkCommand = Object.freeze({
+    create() {
+        return createKindWorkCommand({
+            name: 'broadcast:work',
+            description: 'Work queued broadcasts',
+            kind: 'broadcast',
+            helpHint: 'zin broadcast:work --help',
+        });
+    },
+});
+export default BroadcastWorkCommand;

package/src/cli/commands/NotificationWorkCommand.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Notification Work Command
+ * Alias to work a notification queue.
+ */
+import { type IBaseCommand } from '../BaseCommand';
+export declare const NotificationWorkCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default NotificationWorkCommand;
+//# sourceMappingURL=NotificationWorkCommand.d.ts.map

package/src/cli/commands/NotificationWorkCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationWorkCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/NotificationWorkCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,eAAO,MAAM,uBAAuB;cACxB,YAAY;EAQtB,CAAC;AAEH,eAAe,uBAAuB,CAAC"}

package/src/cli/commands/NotificationWorkCommand.js

@@ -0,0 +1,16 @@
+/**
+ * Notification Work Command
+ * Alias to work a notification queue.
+ */
+import { createKindWorkCommand } from '../commands/createKindWorkCommand.js';
+export const NotificationWorkCommand = Object.freeze({
+    create() {
+        return createKindWorkCommand({
+            name: 'notification:work',
+            description: 'Work queued notifications',
+            kind: 'notification',
+            helpHint: 'zin notification:work --help',
+        });
+    },
+});
+export default NotificationWorkCommand;

package/src/cli/commands/QueueCommand.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Queue Command
+ * Run queued jobs via the framework CLI.
+ */
+import { type IBaseCommand } from '../BaseCommand';
+export declare const QueueCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default QueueCommand;
+//# sourceMappingURL=QueueCommand.d.ts.map

package/src/cli/commands/QueueCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/QueueCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAYvF,eAAO,MAAM,YAAY;cACb,YAAY;EA0EtB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/cli/commands/QueueCommand.js

@@ -0,0 +1,63 @@
+/**
+ * Queue Command
+ * Run queued jobs via the framework CLI.
+ */
+import { BaseCommand } from '../BaseCommand.js';
+import { QueueWorkCommandUtils } from '../commands/QueueWorkCommandUtils.js';
+import { QueueWorkRunner } from '../workers/QueueWorkRunner.js';
+export const QueueCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'queue',
+            description: 'Work queued jobs (broadcast/notification)',
+            addOptions: (command) => {
+                command
+                    .argument('<queueName>', 'Queue name to work')
+                    .option('--timeout <seconds>', 'Stop after this many seconds (default: 10)')
+                    .option('--retry <count>', 'Retries after first attempt (default: 3)')
+                    .option('--max-items <count>', 'Max items to process in one run (default: 1000)')
+                    .option('--driver <name>', 'Queue driver name (default: from QUEUE_DRIVER)');
+                command
+                    .command('work <kind> <queueName>')
+                    .alias('w')
+                    .description('Work a queue with explicit kind (broadcast|notification)')
+                    .option('--timeout <seconds>', 'Stop after this many seconds (default: 10)')
+                    .option('--retry <count>', 'Retries after first attempt (default: 3)')
+                    .option('--max-items <count>', 'Max items to process in one run (default: 1000)')
+                    .option('--driver <name>', 'Queue driver name (default: from QUEUE_DRIVER)')
+                    .action(async (kindRaw, queueName, subOptions) => {
+                    const kind = QueueWorkRunner.parseKind(kindRaw);
+                    const timeoutSeconds = QueueWorkCommandUtils.parsePositiveInt(subOptions['timeout'], '--timeout');
+                    const retry = QueueWorkCommandUtils.parseNonNegativeInt(subOptions['retry'], '--retry');
+                    const maxItems = QueueWorkCommandUtils.parsePositiveInt(subOptions['maxItems'], '--max-items');
+                    const driverName = QueueWorkCommandUtils.normalizeDriverName(subOptions['driver']);
+                    const result = await QueueWorkRunner.run({
+                        kind,
+                        queueName,
+                        timeoutSeconds,
+                        retry,
+                        maxItems,
+                        driverName,
+                    });
+                    QueueWorkCommandUtils.logSummary(queueName, kind, result);
+                });
+            },
+            execute: async (options) => {
+                const queueName = QueueWorkCommandUtils.requireQueueNameFromArgs(options.args, 'zin queue --help');
+                const timeoutSeconds = QueueWorkCommandUtils.parsePositiveInt(options.timeout, '--timeout');
+                const retry = QueueWorkCommandUtils.parseNonNegativeInt(options.retry, '--retry');
+                const maxItems = QueueWorkCommandUtils.parsePositiveInt(options.maxItems, '--max-items');
+                const driverName = QueueWorkCommandUtils.normalizeDriverName(options.driver);
+                const result = await QueueWorkRunner.run({
+                    queueName,
+                    timeoutSeconds,
+                    retry,
+                    maxItems,
+                    driverName,
+                });
+                QueueWorkCommandUtils.logSummary(queueName, 'auto', result);
+            },
+        });
+    },
+});
+export default QueueCommand;

package/src/cli/commands/QueueWorkCommandUtils.d.ts

@@ -0,0 +1,10 @@
+import { type QueueWorkRunnerResult } from '../workers/QueueWorkRunner';
+export declare const QueueWorkCommandUtils: Readonly<{
+    parsePositiveInt: (value: unknown, flag: string) => number | undefined;
+    parseNonNegativeInt: (value: unknown, flag: string) => number | undefined;
+    normalizeDriverName: (value: unknown) => string | undefined;
+    requireQueueNameFromArgs: (args: unknown[] | undefined, helpHint: string) => string;
+    logSummary: (queueName: string, kindLabel: string, result: QueueWorkRunnerResult) => void;
+}>;
+export default QueueWorkCommandUtils;
+//# sourceMappingURL=QueueWorkCommandUtils.d.ts.map

package/src/cli/commands/QueueWorkCommandUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueWorkCommandUtils.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/QueueWorkCommandUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAI1E,eAAO,MAAM,qBAAqB;8BACN,OAAO,QAAQ,MAAM,KAAG,MAAM,GAAG,SAAS;iCAcvC,OAAO,QAAQ,MAAM,KAAG,MAAM,GAAG,SAAS;iCAc1C,OAAO,KAAG,MAAM,GAAG,SAAS;qCAKxB,OAAO,EAAE,GAAG,SAAS,YAAY,MAAM,KAAG,MAAM;4BAQzD,MAAM,aAAa,MAAM,UAAU,qBAAqB,KAAG,IAAI;EAKvF,CAAC;AAEH,eAAe,qBAAqB,CAAC"}

package/src/cli/commands/QueueWorkCommandUtils.js

@@ -0,0 +1,43 @@
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+export const QueueWorkCommandUtils = Object.freeze({
+    parsePositiveInt: (value, flag) => {
+        if (value === undefined)
+            return undefined;
+        const raw = String(value).trim();
+        if (raw === '')
+            return undefined;
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n <= 0) {
+            throw ErrorFactory.createCliError(`Error: Invalid ${flag} '${raw}'. Expected a positive integer.`);
+        }
+        return n;
+    },
+    parseNonNegativeInt: (value, flag) => {
+        if (value === undefined)
+            return undefined;
+        const raw = String(value).trim();
+        if (raw === '')
+            return undefined;
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isFinite(n) || n < 0) {
+            throw ErrorFactory.createCliError(`Error: Invalid ${flag} '${raw}'. Expected a non-negative integer.`);
+        }
+        return n;
+    },
+    normalizeDriverName: (value) => {
+        const raw = typeof value === 'string' ? value.trim() : '';
+        return raw === '' ? undefined : raw;
+    },
+    requireQueueNameFromArgs: (args, helpHint) => {
+        const queueName = typeof args?.[0] === 'string' ? String(args[0]) : '';
+        if (queueName.trim() === '') {
+            throw ErrorFactory.createCliError(`Error: Missing <queueName>. Try '${helpHint}'.`);
+        }
+        return queueName;
+    },
+    logSummary: (queueName, kindLabel, result) => {
+        Logger.info(`Queue work complete (${kindLabel}) for '${queueName}': processed=${result.processed} retried=${result.retried} dropped=${result.dropped} notDueRequeued=${result.notDueRequeued} unknown=${result.unknown}`);
+    },
+});
+export default QueueWorkCommandUtils;

package/src/cli/commands/createKindWorkCommand.d.ts

@@ -0,0 +1,9 @@
+import { type IBaseCommand } from '../BaseCommand';
+import { type QueueWorkKind } from '../workers/QueueWorkRunner';
+export declare function createKindWorkCommand(options: {
+    name: string;
+    description: string;
+    kind: QueueWorkKind;
+    helpHint: string;
+}): IBaseCommand;
+//# sourceMappingURL=createKindWorkCommand.d.ts.map

package/src/cli/commands/createKindWorkCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createKindWorkCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/createKindWorkCommand.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEvF,OAAO,EAAmB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAUnF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,YAAY,CAsCf"}

package/src/cli/commands/createKindWorkCommand.js

@@ -0,0 +1,33 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { QueueWorkCommandUtils } from '../commands/QueueWorkCommandUtils.js';
+import { QueueWorkRunner } from '../workers/QueueWorkRunner.js';
+export function createKindWorkCommand(options) {
+    return BaseCommand.create({
+        name: options.name,
+        description: options.description,
+        addOptions: (command) => {
+            command
+                .argument('<queueName>', 'Queue name to work')
+                .option('--timeout <seconds>', 'Stop after this many seconds (default: 10)')
+                .option('--retry <count>', 'Retries after first attempt (default: 3)')
+                .option('--max-items <count>', 'Max items to process in one run (default: 1000)')
+                .option('--driver <name>', 'Queue driver name (default: from QUEUE_DRIVER)');
+        },
+        execute: async (cmdOptions) => {
+            const queueName = QueueWorkCommandUtils.requireQueueNameFromArgs(cmdOptions.args, options.helpHint);
+            const timeoutSeconds = QueueWorkCommandUtils.parsePositiveInt(cmdOptions.timeout, '--timeout');
+            const retry = QueueWorkCommandUtils.parseNonNegativeInt(cmdOptions.retry, '--retry');
+            const maxItems = QueueWorkCommandUtils.parsePositiveInt(cmdOptions.maxItems, '--max-items');
+            const driverName = QueueWorkCommandUtils.normalizeDriverName(cmdOptions.driver);
+            const result = await QueueWorkRunner.run({
+                kind: options.kind,
+                queueName,
+                timeoutSeconds,
+                retry,
+                maxItems,
+                driverName,
+            });
+            QueueWorkCommandUtils.logSummary(queueName, options.kind, result);
+        },
+    });
+}

package/src/cli/commands/index.d.ts

@@ -2,6 +2,7 @@
  * CLI Commands Module Index
  */
 export { AddCommand } from '../commands/AddCommand';
+export { BroadcastWorkCommand } from '../commands/BroadcastWorkCommand';
 export { ConfigCommand } from '../commands/ConfigCommand';
 export { DebugCommand } from '../commands/DebugCommand';
 export { LogsCleanupCommand } from '../commands/LogsCleanupCommand';
@@ -9,7 +10,9 @@ export { MakeMailTemplateCommand } from '../commands/MakeMailTemplateCommand';
 export { MakeNotificationTemplateCommand } from '../commands/MakeNotificationTemplateCommand';
 export { MigrateCommand } from '../commands/MigrateCommand';
 export { NewCommand } from '../commands/NewCommand';
+export { NotificationWorkCommand } from '../commands/NotificationWorkCommand';
 export { PrepareCommand } from '../commands/PrepareCommand';
+export { QueueCommand } from '../commands/QueueCommand';
 export { SecretsCommand } from '../commands/SecretsCommand';
 export { StartCommand } from '../commands/StartCommand';
 export { TemplatesCommand } from '../commands/TemplatesCommand';

package/src/cli/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,+BAA+B,EAAE,MAAM,+CAA+C,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,+BAA+B,EAAE,MAAM,+CAA+C,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC"}

package/src/cli/commands/index.js

@@ -2,6 +2,7 @@
  * CLI Commands Module Index
  */
 export { AddCommand } from '../commands/AddCommand.js';
+export { BroadcastWorkCommand } from '../commands/BroadcastWorkCommand.js';
 export { ConfigCommand } from '../commands/ConfigCommand.js';
 export { DebugCommand } from '../commands/DebugCommand.js';
 export { LogsCleanupCommand } from '../commands/LogsCleanupCommand.js';
@@ -9,7 +10,9 @@ export { MakeMailTemplateCommand } from '../commands/MakeMailTemplateCommand.js'
 export { MakeNotificationTemplateCommand } from '../commands/MakeNotificationTemplateCommand.js';
 export { MigrateCommand } from '../commands/MigrateCommand.js';
 export { NewCommand } from '../commands/NewCommand.js';
+export { NotificationWorkCommand } from '../commands/NotificationWorkCommand.js';
 export { PrepareCommand } from '../commands/PrepareCommand.js';
+export { QueueCommand } from '../commands/QueueCommand.js';
 export { SecretsCommand } from '../commands/SecretsCommand.js';
 export { StartCommand } from '../commands/StartCommand.js';
 export { TemplatesCommand } from '../commands/TemplatesCommand.js';

package/src/cli/scaffolding/ModelGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModelGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ModelGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,EAAE,CAAC;AAEP,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAsB3F;AAED;;GAEG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA0ClF;AA+HD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CAW5C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CAU5C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAU7C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;EAOzB,CAAC"}
+{"version":3,"file":"ModelGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ModelGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,EAAE,CAAC;AAEP,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAsB3F;AAED;;GAEG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA0ClF;AAgID;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,EAAE,CAEjD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CAW5C;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CAU5C;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAU7C;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;EAOzB,CAAC"}

package/src/cli/scaffolding/ModelGenerator.js

@@ -92,6 +92,7 @@ export const ${options.name} = Object.freeze(
   fillable: [${fillable.map((f) => `'${f}'`).join(', ')}],
   hidden: [${hidden.map((f) => `'${f}'`).join(', ')}],
   timestamps: ${options.timestamps !== false},
+  softDeletes: ${options.softDelete === true},
   casts: {
 `;
     // Add field casts

package/src/cli/workers/QueueWorkRunner.d.ts

@@ -0,0 +1,23 @@
+export type QueueWorkKind = 'broadcast' | 'notification';
+export type QueueWorkRunnerOptions = {
+    queueName: string;
+    kind?: QueueWorkKind;
+    driverName?: string;
+    timeoutSeconds?: number;
+    maxItems?: number;
+    /** Max retries after the first attempt (so total attempts = retry + 1) */
+    retry?: number;
+};
+export type QueueWorkRunnerResult = {
+    processed: number;
+    retried: number;
+    dropped: number;
+    notDueRequeued: number;
+    unknown: number;
+};
+export declare const QueueWorkRunner: Readonly<{
+    run(options: QueueWorkRunnerOptions): Promise<QueueWorkRunnerResult>;
+    parseKind(value: unknown): QueueWorkKind;
+}>;
+export default QueueWorkRunner;
+//# sourceMappingURL=QueueWorkRunner.d.ts.map

package/src/cli/workers/QueueWorkRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueueWorkRunner.d.ts","sourceRoot":"","sources":["../../../../src/cli/workers/QueueWorkRunner.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,cAAc,CAAC;AAoBzD,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAyHF,eAAO,MAAM,eAAe;iBACP,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;qBAuCzD,OAAO,GAAG,aAAa;EAUxC,CAAC;AAEH,eAAe,eAAe,CAAC"}

package/src/cli/workers/QueueWorkRunner.js

@@ -0,0 +1,142 @@
+import { Broadcast } from '../../tools/broadcast/Broadcast.js';
+import { Logger } from '../../config/logger.js';
+import { queueConfig } from '../../config/queue.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { Notification } from '../../tools/notification/Notification.js';
+import { Queue } from '../../tools/queue/Queue.js';
+import { registerQueuesFromRuntimeConfig } from '../../tools/queue/QueueRuntimeRegistration.js';
+const isKind = (value) => value === 'broadcast' || value === 'notification';
+const detectKindFromPayload = (payload) => {
+    if (payload !== null && typeof payload === 'object') {
+        const p = payload;
+        if (isKind(p['type']))
+            return p['type'];
+        if (typeof p['channel'] === 'string' && typeof p['event'] === 'string')
+            return 'broadcast';
+        if (typeof p['recipient'] === 'string' && typeof p['message'] === 'string')
+            return 'notification';
+    }
+    return undefined;
+};
+const normalizeNumber = (value) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '') {
+        const n = Number(value);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return undefined;
+};
+const getTimestamp = (payload) => {
+    return normalizeNumber(payload['timestamp']);
+};
+const getAttempts = (payload) => {
+    const n = normalizeNumber(payload['attempts']);
+    return typeof n === 'number' && n >= 0 ? Math.floor(n) : 0;
+};
+const withAttempts = (payload, attempts) => {
+    return { ...payload, attempts };
+};
+const shouldStop = (startedAtMs, timeoutSeconds) => {
+    if (timeoutSeconds === undefined)
+        return false;
+    const elapsedMs = Date.now() - startedAtMs;
+    return elapsedMs >= timeoutSeconds * 1000;
+};
+const processMessage = async (options, msg, maxAttempts, result) => {
+    const payload = msg.payload ?? {};
+    const kind = options.kind ?? detectKindFromPayload(payload);
+    if (kind === undefined) {
+        Logger.warn('Queue worker: unknown job payload; dropping', {
+            queue: options.queueName,
+            messageId: msg.id,
+            payloadKeys: Object.keys(payload),
+        });
+        result.unknown++;
+        await Queue.ack(options.queueName, msg.id, options.driverName);
+        return 'continue';
+    }
+    const timestamp = getTimestamp(payload);
+    if (typeof timestamp === 'number' && timestamp > Date.now()) {
+        // Not due yet: re-enqueue and stop after rotating the head once.
+        await Queue.enqueue(options.queueName, payload, options.driverName);
+        await Queue.ack(options.queueName, msg.id, options.driverName);
+        result.notDueRequeued++;
+        return 'break';
+    }
+    const attempts = getAttempts(payload);
+    try {
+        if (kind === 'broadcast') {
+            const job = payload;
+            await Broadcast.send(job.channel, job.event, job.data);
+        }
+        else {
+            const job = payload;
+            await Notification.send(job.recipient, job.message, job.options ?? {});
+        }
+        await Queue.ack(options.queueName, msg.id, options.driverName);
+        result.processed++;
+        return 'continue';
+    }
+    catch (error) {
+        const nextAttempts = attempts + 1;
+        const canRetry = nextAttempts < maxAttempts;
+        Logger.error('Queue worker: job failed', {
+            queue: options.queueName,
+            kind,
+            messageId: msg.id,
+            attempts: nextAttempts,
+            maxAttempts,
+            error,
+        });
+        if (canRetry) {
+            await Queue.enqueue(options.queueName, withAttempts(payload, nextAttempts), options.driverName);
+            result.retried++;
+        }
+        else {
+            result.dropped++;
+        }
+        await Queue.ack(options.queueName, msg.id, options.driverName);
+        return 'continue';
+    }
+};
+export const QueueWorkRunner = Object.freeze({
+    async run(options) {
+        registerQueuesFromRuntimeConfig(queueConfig);
+        const startedAtMs = Date.now();
+        const maxItems = typeof options.maxItems === 'number' ? options.maxItems : 1000;
+        const timeoutSeconds = typeof options.timeoutSeconds === 'number' ? options.timeoutSeconds : 10;
+        const maxRetries = typeof options.retry === 'number' ? options.retry : 3;
+        const maxAttempts = Math.max(0, Math.floor(maxRetries)) + 1;
+        const result = {
+            processed: 0,
+            retried: 0,
+            dropped: 0,
+            notDueRequeued: 0,
+            unknown: 0,
+        };
+        /* eslint-disable no-await-in-loop */
+        while (result.processed < maxItems && !shouldStop(startedAtMs, timeoutSeconds)) {
+            const msg = await Queue.dequeue(options.queueName, options.driverName);
+            if (msg === undefined)
+                break;
+            const outcome = await processMessage(options, { id: msg.id, payload: msg.payload ?? {} }, maxAttempts, result);
+            if (outcome === 'break')
+                break;
+        }
+        /* eslint-enable no-await-in-loop */
+        return result;
+    },
+    parseKind(value) {
+        const v = String(value ?? '')
+            .trim()
+            .toLowerCase();
+        if (v === 'broadcast' || v === 'broad')
+            return 'broadcast';
+        if (v === 'notification' || v === 'notify')
+            return 'notification';
+        throw ErrorFactory.createCliError(`Invalid kind '${String(value)}'. Expected 'broadcast' or 'notification'.`);
+    },
+});
+export default QueueWorkRunner;