cabloy 5.1.236 → 5.1.239

package/.cabloy-version

@@ -1 +1 @@
-5.1.236
+5.1.239

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 5.1.239
+
+### Improvements
+
+- Normalize release workspace formatting.
+- Refresh the Vona zova-core patch for v5.1.95.
+
+## 5.1.238
+
+No user-facing changes.
+
 ## 5.1.236
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.236",
+  "version": "5.1.239",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/repo-docs/backend/broadcast-guide.md

@@ -8,6 +8,8 @@ Broadcast lets one worker emit a message that multiple worker processes can rece
 
 This is important because some business logic is not point-to-point background work. It is multi-worker coordination work.
 
+The current broadcast transport uses nonpersistent Redis Pub/Sub, not BullMQ jobs. It has no retained job history or queue-style retention options such as `removeOnComplete` / `removeOnFail`.
+
 ## Create a broadcast
 
 Example: create a broadcast named `echo` in module `training-student`.

package/repo-docs/backend/queue-guide.md

@@ -188,6 +188,37 @@ class QueueAdd {}
 
 That means queue behavior is not only asynchronous. It also participates in concurrency, isolation, and consistency policy.
 
+### Finished-job retention
+
+The global `a-queue` worker defaults are `removeOnComplete: { count: 0 }` and `removeOnFail: { count: 0 }`. Jobs are removed immediately on success or final failure, not on intermediate failures that will be retried. This removes finished job records, not the BullMQ events stream: `pushAsync` still receives completion results and final errors through `QueueEvents`.
+
+For queue-specific retention, set `options.worker` explicitly. Worker removal options take BullMQ `KeepJobs` objects, not booleans; for example, retain up to 100 completed and 100 failed jobs:
+
+```typescript
+@Queue({
+  options: {
+    worker: {
+      removeOnComplete: { count: 100 },
+      removeOnFail: { count: 100 },
+    },
+  },
+})
+class QueueAdd {}
+```
+
+For ordinary `push` / `pushAsync` jobs, `options.job` can instead set `removeOnComplete` / `removeOnFail` to `false` (retain without automatic removal) or a bounded object such as `{ count: 100 }`. Job-level values override worker defaults; per-push `jobOptions` override the corresponding `options.job` values:
+
+```typescript
+await this.scope.queue.add.push(data, {
+  jobOptions: {
+    removeOnComplete: { count: 100 },
+    removeOnFail: false,
+  },
+});
+```
+
+Changing the defaults does not automatically purge previously retained jobs. Retain records when later job lookups or manual retries are needed. Custom `jobId` duplicate suppression lasts only while that job exists; after removal, the same ID can be submitted again. Bounded retention is not an exact TTL or a permanent deduplication guarantee.
+
 ## Configure queues in app config
 
 Queue options can also be overridden in app config.

package/repo-docs/backend/schedule-guide.md

@@ -57,6 +57,29 @@ Schedule parameters can also include:
 
 This matters because recurring jobs often have the same consistency concerns as ordinary queue jobs.
 
+### Finished-run retention
+
+Scheduled runs inherit the selected queue's worker policy, including the global `a-queue` defaults: remove immediately on success or final failure, but not during intermediate retries. See [Finished-job retention](/backend/queue-guide#finished-job-retention) for worker overrides and operational caveats.
+
+Schedules call BullMQ `upsertJobScheduler` directly, bypassing the normal queue-push `options.job` merge. To override retention for a schedule, use `templateOptions`, for example to retain up to 100 successful and 100 failed runs:
+
+```typescript
+@Schedule({
+  repeat: { every: 3000 },
+  templateOptions: {
+    removeOnComplete: { count: 100 },
+    removeOnFail: { count: 100 },
+  },
+})
+export class ScheduleLog extends BeanBase implements IScheduleExecute {
+  async execute() {
+    console.log(Date.now());
+  }
+}
+```
+
+These options govern finished runs, not the recurring scheduler definition; changing them does not automatically purge old retained runs.
+
 ## Enable/disable and environment scoping
 
 Like queues, schedules can be enabled or disabled and scoped to flavor or mode.

package/vona/packages-cli/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli",
-  "version": "1.1.172",
+  "version": "1.1.173",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli",
   "keywords": [

package/vona/packages-cli/cli-set-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-cli-set-api",
-  "version": "1.1.170",
+  "version": "1.1.171",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona cli-set-api",
   "keywords": [

package/vona/packages-vona/vona/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona",
-  "version": "5.1.117",
+  "version": "5.1.118",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "Vona is an intuitive, elegant and powerful Node.js framework for rapidly developing enterprise applications of any size",
   "keywords": [

package/vona/packages-vona/vona-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-core",
-  "version": "5.1.51",
+  "version": "5.1.52",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona",
   "keywords": [

package/vona/packages-vona/vona-core/src/lib/bean/resource/locale/appLocale.ts

@@ -5,11 +5,11 @@ import type { ILocaleRecord, IModuleLocale, IModuleLocaleText } from './type.ts'
 import { cast } from '../../../../types/utils/cast.ts';
 import { BeanSimple } from '../../beanSimple.ts';
 import { LocaleModuleNameSeparator } from './type.ts';
-import { isLocaleMagic } from './utils.ts';
+import { isLocaleMagic, resolveLocale } from './utils.ts';
 
 export class AppLocale extends BeanSimple {
   get current(): keyof ILocaleRecord {
-    return this.ctx ? this.ctx.locale : 'en-us';
+    return this.ctx ? this.ctx.locale : resolveLocale(undefined, this.app.config.locale);
   }
 
   set current(value: keyof ILocaleRecord) {

package/vona/packages-vona/vona-core/src/lib/bean/resource/locale/utils.ts

@@ -1,5 +1,6 @@
+import type { ConfigLocale } from '../../../../types/config/locale.ts';
 import type { IBeanScopeLocale } from '../../type.ts';
-import type { ILocaleMagic } from './type.ts';
+import type { ILocaleMagic, ILocaleRecord } from './type.ts';
 
 import { cast } from '../../../../types/utils/cast.ts';
 import { useApp } from '../../../framework/useApp.ts';
@@ -59,3 +60,47 @@ export function text(strings: any, ...expressions: any): any {
 export function isLocaleMagic(str: string | object) {
   return typeof str === 'object' && cast(str).toJSON;
 }
+
+export function canonicalizeLocale(value: unknown): string {
+  return typeof value === 'string' ? value.trim().replaceAll('_', '-').toLowerCase() : '';
+}
+
+export function validateLocaleConfig(config: ConfigLocale): void {
+  const items = config?.items;
+  if (!items || typeof items !== 'object' || Object.keys(items).length === 0) {
+    throw new Error('config.locale.items must contain at least one enabled locale');
+  }
+  for (const key of Object.keys(items)) {
+    if (!key || canonicalizeLocale(key) !== key || typeof items[key] !== 'string') {
+      throw new Error(`config.locale.items contains an invalid locale: ${key}`);
+    }
+  }
+  if (
+    typeof config.default !== 'string' ||
+    !Object.hasOwn(items, config.default) ||
+    canonicalizeLocale(config.default) !== config.default
+  ) {
+    throw new Error('config.locale.default must be an enabled config.locale.items key');
+  }
+}
+
+/** Resolve an enabled input without allowing aliases to expand the configured set. */
+export function resolveEnabledLocale(
+  value: unknown,
+  config: ConfigLocale,
+  aliases: Record<string, string> = {},
+): keyof ILocaleRecord | undefined {
+  validateLocaleConfig(config);
+  let locale = canonicalizeLocale(value);
+  if (Object.hasOwn(aliases, locale)) locale = canonicalizeLocale(aliases[locale]);
+  return Object.hasOwn(config.items, locale) ? (locale as keyof ILocaleRecord) : undefined;
+}
+
+/** Active-language selection only; explicit translation lookup remains independent. */
+export function resolveLocale(
+  value: unknown,
+  config: ConfigLocale,
+  aliases?: Record<string, string>,
+): keyof ILocaleRecord {
+  return resolveEnabledLocale(value, config, aliases) ?? config.default;
+}

package/vona/packages-vona/vona-core/src/lib/framework/start.ts

@@ -97,6 +97,10 @@ async function __prepareConfig(app: VonaApplication): Promise<VonaConfigOptional
   const configItemsRes = await Promise.all(configItemsPromise);
   for (const configItem of configItemsRes) {
     if (configItem) {
+      // An explicit language subset replaces the preceding policy, not its individual keys.
+      if (configItem.locale && Object.hasOwn(configItem.locale, 'items') && config.locale) {
+        delete config.locale.items;
+      }
       deepExtend(config, configItem);
     }
   }

package/vona/packages-vona/vona-core/src/lib/module/locales.ts

@@ -1,34 +1,56 @@
 import type { IModule } from '@cabloy/module-info';
 
-import type { TypeModuleResourceLocales, VonaLocaleOptional } from '../../types/index.ts';
+import type {
+  ILocaleProviderResource,
+  TypeModuleResourceLocales,
+  VonaLocaleOptional,
+} from '../../types/index.ts';
 import type { VonaApplication } from '../core/application.ts';
 
 import localesDefault from '../core/locales.ts';
 import { deepExtend } from '../utils/util.ts';
 
 export default async function (app: VonaApplication, modules: Record<string, IModule>) {
-  // all locales
-  app.meta.locales = localesDefault;
+  // Each application owns its registry; never add provider/project data to imported resources.
+  app.meta.locales = deepExtend({}, localesDefault);
   app.meta.localeModules = {};
 
-  // load locales
-  await loadLocales();
+  const localesAll = await app.options.locales();
+  // Preserve existing project global/module override semantics.
+  for (const locale in localesAll.localesDefault) {
+    _initLocales(locale, localesAll.localesDefault[locale]);
+  }
+  for (const locale in localesAll.localesModules) {
+    _initLocales(locale, localesAll.localesModules[locale]);
+  }
 
-  async function loadLocales() {
-    const localesAll = await app.options.locales();
-    // project locales default
-    for (const locale in localesAll.localesDefault) {
-      _initLocales(locale, localesAll.localesDefault[locale]);
-    }
-    // project locales modules
-    for (const locale in localesAll.localesModules) {
-      _initLocales(locale, localesAll.localesModules[locale]);
+  // Providers precede all ordinary dictionaries, independent of their module order.
+  for (const moduleName of Object.keys(modules)) {
+    const module = modules[moduleName];
+    if (!module.info.capabilities?.locale) continue;
+    const locales = module.resource.localesProvider;
+    if (!locales) continue;
+    for (const locale of Object.keys(locales)) {
+      const resource = locales[locale] as ILocaleProviderResource;
+      const globals = Object.fromEntries(
+        Object.entries(resource).filter(
+          ([key, value]) => key !== 'modules' && typeof value === 'string',
+        ),
+      );
+      app.meta.locales[locale] = Object.assign({}, globals, app.meta.locales[locale]);
+      for (const target of Object.keys(resource.modules ?? {})) {
+        // Metadata membership is sufficient; no target import, install or dependency is needed.
+        if (!Object.hasOwn(modules, target)) continue;
+        _registerLocale(target, locale, resource.modules![target]);
+      }
     }
-    // app cache
-    app.meta.hmrCacheLocaleModules = deepExtend({}, app.meta.localeModules);
-    // module locales
-    for (const moduleName in modules) {
-      const module = modules[moduleName];
+  }
+
+  // Preserve project/provider precedence when ordinary target dictionaries are reloaded.
+  app.meta.hmrCacheLocaleModules = deepExtend({}, app.meta.localeModules);
+  for (const moduleName of Object.keys(modules)) {
+    const module = modules[moduleName];
+    if (!module.info.capabilities?.locale) {
       _registerLocales(moduleName, module.resource.locales);
     }
   }
@@ -36,7 +58,6 @@ export default async function (app: VonaApplication, modules: Record<string, IMo
   function _initLocales(locale: string, locales: VonaLocaleOptional | undefined) {
     if (!locales) return;
     if (!locales.modules) {
-      // override
       app.meta.locales[locale] = Object.assign({}, app.meta.locales[locale], locales);
     } else {
       const moduleMap = locales.modules;
@@ -54,9 +75,7 @@ export default async function (app: VonaApplication, modules: Record<string, IMo
   }
 
   function _registerLocale(moduleName: string, locale: string, moduleLocales: object) {
-    // locales: not override
     app.meta.locales[locale] = Object.assign({}, moduleLocales, app.meta.locales[locale]);
-    // localeModules
     if (!app.meta.localeModules[moduleName]) app.meta.localeModules[moduleName] = {};
     app.meta.localeModules[moduleName][locale] = Object.assign(
       {},

package/vona/packages-vona/vona-core/src/lib/utils/zod-enhance.ts

@@ -11,7 +11,7 @@ import type { VonaApplication } from '../core/application.ts';
 import { useApp } from '../framework/useApp.ts';
 
 export type ZodLocaleError = () => { localeError: z.core.$ZodErrorMap };
-export type ZodLocaleErrors = Record<keyof ILocaleRecord, ZodLocaleError>;
+export type ZodLocaleErrors = Partial<Record<keyof ILocaleRecord, ZodLocaleError>>;
 
 const queryCoercion = new AsyncLocalStorage<boolean>();
 

package/vona/packages-vona/vona-core/src/types/config/config.ts

@@ -2,6 +2,7 @@ import type { VonaConfigMeta } from '@cabloy/module-info';
 
 import type { ConfigLogger, IBeanScopeConfig } from '../../index.ts';
 import type { PowerPartial } from '../utils/powerPartial.ts';
+import type { ConfigLocale } from './locale.ts';
 
 // @ts-ignore ignore the throw type check of 'development'
 export interface VonaConfig {
@@ -31,6 +32,7 @@ export interface VonaConfig {
     maxIpsCount: number;
   };
   logger: ConfigLogger;
+  locale: ConfigLocale;
   //
   modules: IBeanScopeConfig;
 }

package/vona/packages-vona/vona-core/src/types/config/locale.ts

@@ -2,13 +2,20 @@ import type { ILocaleRecord } from '../../lib/bean/resource/locale/type.ts';
 import type { IBeanScopeLocale } from '../../lib/bean/type.ts';
 import type { PowerPartial } from '../utils/powerPartial.ts';
 
-// export const localeDefault = {
-//   modules: {},
-// };
+export interface ConfigLocale {
+  items: Partial<Record<keyof ILocaleRecord, string>>;
+  default: keyof ILocaleRecord;
+}
 
 export interface VonaLocale {
   modules: IBeanScopeLocale;
 }
 
 export type VonaLocaleOptional = PowerPartial<VonaLocale>;
-export type VonaLocaleOptionalMap = Record<keyof ILocaleRecord, VonaLocaleOptional>;
+export type VonaLocaleOptionalMap = Partial<Record<keyof ILocaleRecord, VonaLocaleOptional>>;
+
+// Only capability.locale modules interpret this envelope as cross-module resources.
+export interface ILocaleProviderResource {
+  modules?: Record<string, Record<string, string>>;
+  [key: string]: string | Record<string, Record<string, string>> | undefined;
+}

package/vona/packages-vona/vona-core/src/types/interface/module.ts

@@ -17,6 +17,7 @@ export interface IModuleResource {
   Main: new () => IModuleMain;
   Monkey: new () => IMonkeyModule & IMonkeySystem;
   locales: TypeModuleResourceLocales;
+  localesProvider: TypeModuleResourceLocales;
   errors: TypeModuleResourceErrors;
   config: TypeModuleResourceConfig;
   constants: unknown;

package/vona/packages-vona/vona-mock/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vona-mock",
-  "version": "6.1.51",
+  "version": "6.1.52",
   "gitHead": "a79189b882c17af5911573896a781bbb0046d37d",
   "description": "vona mock",
   "keywords": [

package/vona/patches/{zova-core@5.1.94.patch → zova-core@5.1.95.patch}

@@ -14,10 +14,10 @@ index 73cebe18f3e260c295bdf42a3d1ab9e86fa2de87..cb0ff5c3b541f646105198ee23ac0fc3
 -//# sourceMappingURL=errorGlobal.d.ts.map
 
 diff --git a/dist/types/interface/module.d.ts b/dist/types/interface/module.d.ts
-index 838e299407218b7bfac469d42a12d6ab59820380..e8b61cc231e39ee3a270ee513ab43ff5a13fc290 100644
+index cfcfdada3ef32dd555da6ab956aef8b6046c6d86..98834454d1a29dd314732b37b210283fc63c37f2 100644
 --- a/dist/types/interface/module.d.ts
 +++ b/dist/types/interface/module.d.ts
-@@ -23,12 +23,6 @@ export interface IModuleResource {
+@@ -24,12 +24,6 @@ export interface IModuleResource {
      components: TypeModuleResourceComponents;
  }
  export declare const SymbolInstalled: unique symbol;