bazis 0.96.1

package/core/cache/cacheModule.ts

@@ -0,0 +1,21 @@
+import type { BazisModuleRef } from "../di";
+import { buildCacheModule } from "./internal/buildCacheProviders";
+import type { CacheOptions } from "./types/CacheOptions";
+
+/**
+ * In-memory cache as a one-line value. Inject {@link ICache} anywhere; decorate
+ * methods with `@Cacheable` or routes with `@OutputCache`.
+ *
+ * ```ts
+ * createApp({ cache: memory({ maxEntries: 1000 }) });
+ * // or, inside a module: imports: [memory()]
+ * ```
+ *
+ * Options are just the in-memory knobs (`maxEntries`, `defaultTtlSeconds`, …).
+ * For multi-instance caching keep `memory()` and add a distributed backend in your
+ * `@Infra` manifest via `redisConnect(redisConfig, { cache: "distributed" })`; `@CacheableRedis` /
+ * `@OutputRedisCache` then pick the backend up from DI automatically.
+ */
+export function memory(options: CacheOptions = {}): BazisModuleRef {
+  return buildCacheModule(options);
+}

package/core/cache/decorators/Cacheable.ts

@@ -0,0 +1,38 @@
+import type { CacheableOptions } from "../types/CachePolicy";
+import { ownCacheableMeta, ownCacheableMethodMeta } from "./cacheableMetadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type ClassOrMethodDecorator = (
+  value: AnyClass | AnyMethod,
+  context: ClassDecoratorContext | ClassMethodDecoratorContext,
+) => void;
+
+/**
+ * Caches the return value of a service/provider method in {@link ICache}.
+ *
+ * Mirrors Spring / FusionCache `@Cacheable`. Put the decorator on the
+ * **implementation class**, then register via {@link cachedSingleton} or
+ * {@link cachedScoped} so DI returns a caching proxy for the interface token.
+ *
+ * ```ts
+ * class UserService implements IUserStore {
+ *   @Cacheable({ seconds: 300, key: (id) => `user:${id}` })
+ *   async byId(id: number) { ... }
+ * }
+ *
+ * cachedScoped(IUserStore, UserService, [repositoryFor(User)])
+ * ```
+ */
+export function Cacheable(options: CacheableOptions): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownCacheableMeta(context.metadata).cacheable = options;
+    } else {
+      const methodMeta = ownCacheableMethodMeta(context.metadata, context.name);
+      Object.assign(methodMeta, options);
+    }
+  };
+}
+
+export type { CacheableOptions } from "../types/CachePolicy";

package/core/cache/decorators/CacheableRedis.ts

@@ -0,0 +1,39 @@
+import type { CacheableRedisOptions } from "../types/CacheableRedisOptions";
+import { ownCacheableRedisMeta, ownCacheableRedisMethodMeta } from "./cacheableRedisMetadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type ClassOrMethodDecorator = (
+  value: AnyClass | AnyMethod,
+  context: ClassDecoratorContext | ClassMethodDecoratorContext,
+) => void;
+
+/**
+ * Shared service method cache backed by the distributed tier (multi-instance safe).
+ *
+ * Requires a distributed backend: add `redisConnect(redisConfig, { cache: "distributed" })`
+ * to your `@Infra` manifest. Register the class with the usual `cachedScoped` /
+ * `cachedSingleton` (or just `scoped` / `singleton` — the auto-hook wraps it). The distributed
+ * tier activates automatically when a backend is configured.
+ *
+ * ```ts
+ * class UserService implements IUserStore {
+ *   @CacheableRedis({ seconds: 300, key: (id) => `user:${id}`, tags: ["users"] })
+ *   async byId(id: number) { ... }
+ * }
+ *
+ * cachedScoped(IUserStore, UserService, [repositoryFor(User)]);
+ * ```
+ */
+export function CacheableRedis(options: CacheableRedisOptions): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownCacheableRedisMeta(context.metadata).cacheableRedis = options;
+    } else {
+      const methodMeta = ownCacheableRedisMethodMeta(context.metadata, context.name);
+      Object.assign(methodMeta, options);
+    }
+  };
+}
+
+export type { CacheableRedisOptions } from "../types/CacheableRedisOptions";

package/core/cache/decorators/OutputCache.ts

@@ -0,0 +1,33 @@
+import type { OutputCacheOptions } from "../types/CachePolicy";
+import { ownOutputCacheActionMeta, ownOutputCacheMeta } from "./outputCacheMetadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type ClassOrMethodDecorator = (
+  value: AnyClass | AnyMethod,
+  context: ClassDecoratorContext | ClassMethodDecoratorContext,
+) => void;
+
+/**
+ * Server-side HTTP output cache for controller actions.
+ *
+ * Mirrors ASP.NET Core `[OutputCache]`. Requires a cache value
+ * (`createApp({ cache: memory() })`); the output-cache middleware self-wires via DI.
+ *
+ * ```ts
+ * @Get("products")
+ * @OutputCache({ seconds: 60, varyByQuery: ["limit", "page"], tags: ["products"] })
+ * list(limit = 20, page = 1) { ... }
+ * ```
+ */
+export function OutputCache(options: OutputCacheOptions): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownOutputCacheMeta(context.metadata).outputCache = options;
+    } else {
+      ownOutputCacheActionMeta(context.metadata, context.name).outputCache = options;
+    }
+  };
+}
+
+export type { OutputCacheOptions } from "../types/CachePolicy";

package/core/cache/decorators/OutputRedisCache.ts

@@ -0,0 +1,33 @@
+import type { OutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+import { ownOutputRedisCacheActionMeta, ownOutputRedisCacheMeta } from "./outputRedisCacheMetadata";
+
+type AnyClass = abstract new (...args: never[]) => unknown;
+type AnyMethod = (...args: never[]) => unknown;
+type ClassOrMethodDecorator = (
+  value: AnyClass | AnyMethod,
+  context: ClassDecoratorContext | ClassMethodDecoratorContext,
+) => void;
+
+/**
+ * Shared HTTP output cache backed by the distributed tier (multi-instance safe).
+ *
+ * Requires a distributed backend: add `redisConnect(redisConfig, { cache: "distributed" })`
+ * to your `@Infra` manifest.
+ *
+ * ```ts
+ * @Get("products")
+ * @OutputRedisCache({ seconds: 60, varyByQuery: ["limit", "page"], tags: ["products"] })
+ * list() { ... }
+ * ```
+ */
+export function OutputRedisCache(options: OutputRedisCacheOptions): ClassOrMethodDecorator {
+  return (_value, context) => {
+    if (context.kind === "class") {
+      ownOutputRedisCacheMeta(context.metadata).outputRedisCache = options;
+    } else {
+      ownOutputRedisCacheActionMeta(context.metadata, context.name).outputRedisCache = options;
+    }
+  };
+}
+
+export type { OutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";

package/core/cache/decorators/cacheableMetadata.ts

@@ -0,0 +1,78 @@
+import type { CacheableOptions } from "../types/CachePolicy";
+
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const CACHEABLE_META = Symbol.for("bazis:cache:cacheable");
+
+export interface CacheableRequirement extends CacheableOptions {}
+
+export interface CacheableClassMeta {
+  cacheable?: CacheableRequirement;
+  methods: Map<string | symbol, CacheableRequirement>;
+}
+
+interface CacheableMetadataCarrier {
+  [CACHEABLE_META]?: CacheableClassMeta;
+}
+
+function emptyMeta(): CacheableClassMeta {
+  return { methods: new Map() };
+}
+
+function cloneMeta(source: CacheableClassMeta): CacheableClassMeta {
+  const methods = new Map<string | symbol, CacheableRequirement>();
+  for (const [name, requirement] of source.methods) {
+    methods.set(name, { ...requirement });
+  }
+  return {
+    cacheable: source.cacheable ? { ...source.cacheable } : undefined,
+    methods,
+  };
+}
+
+export function ownCacheableMeta(metadata: object): CacheableClassMeta {
+  const carrier = metadata as CacheableMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, CACHEABLE_META)) {
+    const inherited = carrier[CACHEABLE_META];
+    carrier[CACHEABLE_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[CACHEABLE_META]!;
+}
+
+export function ownCacheableMethodMeta(metadata: object, methodName: string | symbol): CacheableRequirement {
+  const meta = ownCacheableMeta(metadata);
+  let requirement = meta.methods.get(methodName);
+  if (requirement === undefined) {
+    requirement = {};
+    meta.methods.set(methodName, requirement);
+  }
+  return requirement;
+}
+
+export function cacheableMetaOf(ctor: object): CacheableClassMeta | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | CacheableMetadataCarrier
+    | undefined;
+  return metadata?.[CACHEABLE_META];
+}
+
+export function resolveCacheableRequirement(
+  classMeta: CacheableClassMeta | undefined,
+  methodName: string | symbol,
+): CacheableRequirement | undefined {
+  if (classMeta === undefined) {
+    return undefined;
+  }
+  const method = classMeta.methods.get(methodName);
+  if (method !== undefined) {
+    return { ...classMeta.cacheable, ...method };
+  }
+  return classMeta.cacheable;
+}
+
+export function hasCacheableMethods(classMeta: CacheableClassMeta | undefined): boolean {
+  if (classMeta === undefined) {
+    return false;
+  }
+  return classMeta.cacheable !== undefined || classMeta.methods.size > 0;
+}

package/core/cache/decorators/cacheableRedisMetadata.ts

@@ -0,0 +1,81 @@
+import type { CacheableRedisOptions } from "../types/CacheableRedisOptions";
+
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const CACHEABLE_REDIS_META = Symbol.for("bazis:cache:cacheable-redis");
+
+export interface CacheableRedisRequirement extends CacheableRedisOptions {}
+
+export interface CacheableRedisClassMeta {
+  cacheableRedis?: CacheableRedisRequirement;
+  methods: Map<string | symbol, CacheableRedisRequirement>;
+}
+
+interface CacheableRedisMetadataCarrier {
+  [CACHEABLE_REDIS_META]?: CacheableRedisClassMeta;
+}
+
+function emptyMeta(): CacheableRedisClassMeta {
+  return { methods: new Map() };
+}
+
+function cloneMeta(source: CacheableRedisClassMeta): CacheableRedisClassMeta {
+  const methods = new Map<string | symbol, CacheableRedisRequirement>();
+  for (const [name, requirement] of source.methods) {
+    methods.set(name, { ...requirement });
+  }
+  return {
+    cacheableRedis: source.cacheableRedis ? { ...source.cacheableRedis } : undefined,
+    methods,
+  };
+}
+
+export function ownCacheableRedisMeta(metadata: object): CacheableRedisClassMeta {
+  const carrier = metadata as CacheableRedisMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, CACHEABLE_REDIS_META)) {
+    const inherited = carrier[CACHEABLE_REDIS_META];
+    carrier[CACHEABLE_REDIS_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[CACHEABLE_REDIS_META]!;
+}
+
+export function ownCacheableRedisMethodMeta(
+  metadata: object,
+  methodName: string | symbol,
+): CacheableRedisRequirement {
+  const meta = ownCacheableRedisMeta(metadata);
+  let requirement = meta.methods.get(methodName);
+  if (requirement === undefined) {
+    requirement = {};
+    meta.methods.set(methodName, requirement);
+  }
+  return requirement;
+}
+
+export function cacheableRedisMetaOf(ctor: object): CacheableRedisClassMeta | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | CacheableRedisMetadataCarrier
+    | undefined;
+  return metadata?.[CACHEABLE_REDIS_META];
+}
+
+export function resolveCacheableRedisRequirement(
+  classMeta: CacheableRedisClassMeta | undefined,
+  methodName: string | symbol,
+): CacheableRedisRequirement | undefined {
+  if (classMeta === undefined) {
+    return undefined;
+  }
+  const method = classMeta.methods.get(methodName);
+  if (method !== undefined) {
+    return { ...classMeta.cacheableRedis, ...method };
+  }
+  return classMeta.cacheableRedis;
+}
+
+export function hasCacheableRedisMethods(classMeta: CacheableRedisClassMeta | undefined): boolean {
+  if (classMeta === undefined) {
+    return false;
+  }
+  return classMeta.cacheableRedis !== undefined || classMeta.methods.size > 0;
+}

package/core/cache/decorators/outputCacheMetadata.ts

@@ -0,0 +1,71 @@
+import type { OutputCacheOptions } from "../types/CachePolicy";
+
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const OUTPUT_CACHE_META = Symbol.for("bazis:cache:output");
+
+export interface OutputCacheRequirement extends OutputCacheOptions {}
+
+export interface OutputCacheControllerMeta {
+  outputCache?: OutputCacheRequirement;
+  actions: Map<string | symbol, OutputCacheActionMeta>;
+}
+
+export interface OutputCacheActionMeta {
+  outputCache?: OutputCacheRequirement;
+}
+
+interface OutputCacheMetadataCarrier {
+  [OUTPUT_CACHE_META]?: OutputCacheControllerMeta;
+}
+
+function emptyMeta(): OutputCacheControllerMeta {
+  return { actions: new Map() };
+}
+
+function cloneMeta(source: OutputCacheControllerMeta): OutputCacheControllerMeta {
+  const actions = new Map<string | symbol, OutputCacheActionMeta>();
+  for (const [name, action] of source.actions) {
+    actions.set(name, { ...action, outputCache: action.outputCache ? { ...action.outputCache } : undefined });
+  }
+  return {
+    outputCache: source.outputCache ? { ...source.outputCache } : undefined,
+    actions,
+  };
+}
+
+export function ownOutputCacheMeta(metadata: object): OutputCacheControllerMeta {
+  const carrier = metadata as OutputCacheMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, OUTPUT_CACHE_META)) {
+    const inherited = carrier[OUTPUT_CACHE_META];
+    carrier[OUTPUT_CACHE_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[OUTPUT_CACHE_META]!;
+}
+
+export function ownOutputCacheActionMeta(metadata: object, methodName: string | symbol): OutputCacheActionMeta {
+  const meta = ownOutputCacheMeta(metadata);
+  let action = meta.actions.get(methodName);
+  if (action === undefined) {
+    action = {};
+    meta.actions.set(methodName, action);
+  }
+  return action;
+}
+
+export function outputCacheMetaOf(ctor: object): OutputCacheControllerMeta | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | OutputCacheMetadataCarrier
+    | undefined;
+  return metadata?.[OUTPUT_CACHE_META];
+}
+
+export function resolveOutputCacheRequirement(
+  controllerMeta: OutputCacheControllerMeta | undefined,
+  methodName: string | symbol,
+): OutputCacheRequirement | undefined {
+  if (controllerMeta === undefined) {
+    return undefined;
+  }
+  return controllerMeta.actions.get(methodName)?.outputCache ?? controllerMeta.outputCache;
+}

package/core/cache/decorators/outputRedisCacheMetadata.ts

@@ -0,0 +1,77 @@
+import type { OutputRedisCacheOptions } from "../types/OutputRedisCacheOptions";
+
+(Symbol as { metadata?: symbol }).metadata ??= Symbol.for("Symbol.metadata");
+
+const OUTPUT_REDIS_CACHE_META = Symbol.for("bazis:cache:output-redis");
+
+export interface OutputRedisCacheRequirement extends OutputRedisCacheOptions {}
+
+export interface OutputRedisCacheControllerMeta {
+  outputRedisCache?: OutputRedisCacheRequirement;
+  actions: Map<string | symbol, OutputRedisCacheActionMeta>;
+}
+
+export interface OutputRedisCacheActionMeta {
+  outputRedisCache?: OutputRedisCacheRequirement;
+}
+
+interface OutputRedisCacheMetadataCarrier {
+  [OUTPUT_REDIS_CACHE_META]?: OutputRedisCacheControllerMeta;
+}
+
+function emptyMeta(): OutputRedisCacheControllerMeta {
+  return { actions: new Map() };
+}
+
+function cloneMeta(source: OutputRedisCacheControllerMeta): OutputRedisCacheControllerMeta {
+  const actions = new Map<string | symbol, OutputRedisCacheActionMeta>();
+  for (const [name, action] of source.actions) {
+    actions.set(name, {
+      ...action,
+      outputRedisCache: action.outputRedisCache ? { ...action.outputRedisCache } : undefined,
+    });
+  }
+  return {
+    outputRedisCache: source.outputRedisCache ? { ...source.outputRedisCache } : undefined,
+    actions,
+  };
+}
+
+export function ownOutputRedisCacheMeta(metadata: object): OutputRedisCacheControllerMeta {
+  const carrier = metadata as OutputRedisCacheMetadataCarrier;
+  if (!Object.prototype.hasOwnProperty.call(carrier, OUTPUT_REDIS_CACHE_META)) {
+    const inherited = carrier[OUTPUT_REDIS_CACHE_META];
+    carrier[OUTPUT_REDIS_CACHE_META] = inherited ? cloneMeta(inherited) : emptyMeta();
+  }
+  return carrier[OUTPUT_REDIS_CACHE_META]!;
+}
+
+export function ownOutputRedisCacheActionMeta(
+  metadata: object,
+  methodName: string | symbol,
+): OutputRedisCacheActionMeta {
+  const meta = ownOutputRedisCacheMeta(metadata);
+  let action = meta.actions.get(methodName);
+  if (action === undefined) {
+    action = {};
+    meta.actions.set(methodName, action);
+  }
+  return action;
+}
+
+export function outputRedisCacheMetaOf(ctor: object): OutputRedisCacheControllerMeta | undefined {
+  const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as
+    | OutputRedisCacheMetadataCarrier
+    | undefined;
+  return metadata?.[OUTPUT_REDIS_CACHE_META];
+}
+
+export function resolveOutputRedisCacheRequirement(
+  controllerMeta: OutputRedisCacheControllerMeta | undefined,
+  methodName: string | symbol,
+): OutputRedisCacheRequirement | undefined {
+  if (controllerMeta === undefined) {
+    return undefined;
+  }
+  return controllerMeta.actions.get(methodName)?.outputRedisCache ?? controllerMeta.outputRedisCache;
+}

package/core/cache/di/classProviderHook.ts

@@ -0,0 +1,26 @@
+import type { Class, ClassProviderHook, Token } from "../../di";
+import { cacheableMetaOf, hasCacheableMethods } from "../decorators/cacheableMetadata";
+import { cacheableRedisMetaOf, hasCacheableRedisMethods } from "../decorators/cacheableRedisMetadata";
+import { cachedScoped, cachedSingleton } from "../providers/cachedProviders";
+
+/**
+ * Pure build extension contributed by the cache module to its own container.
+ * DI retains construction, lifetime, dependency validation and resource ownership.
+ */
+export const cacheableClassProviderHook: ClassProviderHook = ({ lifetime, provide, useClass, deps }) => {
+  const hasCache =
+    hasCacheableMethods(cacheableMetaOf(useClass))
+    || hasCacheableRedisMethods(cacheableRedisMetaOf(useClass));
+  if (!hasCache) {
+    return undefined;
+  }
+  const token = provide as Token<object>;
+  const impl = useClass as Class<object>;
+  if (lifetime === "scoped") {
+    return cachedScoped(token, impl, deps);
+  }
+  if (lifetime === "singleton") {
+    return cachedSingleton(token, impl, deps);
+  }
+  return undefined;
+};

package/core/cache/distributed/CacheCodec.ts

@@ -0,0 +1,5 @@
+/** Serializes cache values to/from the string form a distributed store keeps. */
+export interface CacheCodec<TValue> {
+  serialize(value: TValue): string;
+  deserialize(raw: string): TValue;
+}