@classytic/arc 2.41.1 → 2.44.0

package/dist/{memory-Iotz0cCx.mjs → memory-CTa5pOCW.mjs}

@@ -1,5 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { n as evictToSize } from "./boundedMap-DWiKW7lP.mjs";
 //#region src/cache/memory.ts
 var memory_exports = /* @__PURE__ */ __exportAll({ MemoryCacheStore: () => MemoryCacheStore });
 /**
@@ -24,13 +25,13 @@ var MemoryCacheStore = class {
 	_misses = 0;
 	_evictions = 0;
 	constructor(options = {}) {
-		this.defaultTtlSeconds = options.defaultTtlSeconds ?? 60;
-		this.maxEntries = clamp(options.maxEntries ?? 1e3, 1, 1e5);
-		this.maxEntryBytes = clamp(options.maxEntryBytes ?? 262144, 1024, 10485760);
-		this.maxMemoryBytes = options.maxMemoryBytes ?? 52428800;
-		this.evictionWatermark = clamp(options.evictionWatermark ?? .9, .5, 1);
+		this.defaultTtlSeconds = finite("defaultTtlSeconds", options.defaultTtlSeconds ?? 60);
+		this.maxEntries = clamp("maxEntries", options.maxEntries ?? 1e3, 1, 1e5);
+		this.maxEntryBytes = clamp("maxEntryBytes", options.maxEntryBytes ?? 262144, 1024, 10485760);
+		this.maxMemoryBytes = clamp("maxMemoryBytes", options.maxMemoryBytes ?? 52428800, 0, Number.MAX_SAFE_INTEGER);
+		this.evictionWatermark = clamp("evictionWatermark", options.evictionWatermark ?? .9, .5, 1);
 		this.logger = options.logger ?? console;
-		const cleanupIntervalMs = clamp(options.cleanupIntervalMs ?? 3e4, 1e3, 6e5);
+		const cleanupIntervalMs = clamp("cleanupIntervalMs", options.cleanupIntervalMs ?? 3e4, 1e3, 6e5);
 		this.cleanupTimer = setInterval(() => this.cleanupExpired(), cleanupIntervalMs);
 		if (this.cleanupTimer.unref) this.cleanupTimer.unref();
 	}
@@ -54,11 +55,12 @@ var MemoryCacheStore = class {
 		const effectiveTtlSeconds = ttlSeconds ?? this.defaultTtlSeconds;
 		if (!Number.isFinite(effectiveTtlSeconds) || effectiveTtlSeconds <= 0) return;
 		const ttlMs = effectiveTtlSeconds * 1e3;
-		const size = this.estimateSize(value);
-		if (size > this.maxEntryBytes) {
-			this.logger.warn(`[MemoryCacheStore] Skipping oversized entry for key '${key}' (${size} bytes > ${this.maxEntryBytes} bytes)`);
+		const valueBytes = this.estimateSize(value);
+		if (valueBytes > this.maxEntryBytes) {
+			this.logger.warn(`[MemoryCacheStore] Skipping oversized entry for key '${key}' (${valueBytes} bytes > ${this.maxEntryBytes} bytes)`);
 			return;
 		}
+		const size = valueBytes + keyBytes(key);
 		const existing = this.cache.get(key);
 		if (existing) {
 			this.currentBytes -= existing.size;
@@ -70,8 +72,7 @@ var MemoryCacheStore = class {
 			expiresAt: Date.now() + ttlMs
 		});
 		this.currentBytes += size;
-		this.evictToLimit();
-		if (this.maxMemoryBytes > 0) this.evictToMemoryLimit();
+		this.enforceLimits();
 	}
 	async delete(key) {
 		const entry = this.cache.get(key);
@@ -96,14 +97,14 @@ var MemoryCacheStore = class {
 		const effectiveTtlSeconds = ttlSeconds ?? this.defaultTtlSeconds;
 		if (entry) this.currentBytes -= entry.size;
 		this.cache.delete(key);
-		const size = 8;
+		const size = 8 + keyBytes(key);
 		this.cache.set(key, {
 			value: next,
 			size,
 			expiresAt: live ? entry.expiresAt : now + Math.max(1, effectiveTtlSeconds) * 1e3
 		});
 		this.currentBytes += size;
-		this.evictToLimit();
+		this.enforceLimits();
 		return next;
 	}
 	async clear(pattern) {
@@ -133,26 +134,19 @@ var MemoryCacheStore = class {
 		this.cache.delete(key);
 		this.currentBytes -= entry.size;
 	}
-	evictToLimit() {
-		while (this.cache.size > this.maxEntries) {
-			const oldestKey = this.cache.keys().next().value;
-			if (!oldestKey) break;
-			const entry = this.cache.get(oldestKey);
-			if (!entry) break;
-			this.removeEntry(oldestKey, entry);
-			this._evictions++;
-		}
-	}
-	evictToMemoryLimit() {
+	/** Every write path ends here, so no path can skip a limit. */
+	enforceLimits() {
+		this._evictions += evictToSize(this.cache, this.maxEntries, (_key, entry) => {
+			this.currentBytes -= entry.size;
+		});
+		if (this.maxMemoryBytes <= 0 || this.currentBytes <= this.maxMemoryBytes) return;
 		const target = this.maxMemoryBytes * this.evictionWatermark;
-		while (this.currentBytes > this.maxMemoryBytes && this.cache.size > 0) {
-			const oldestKey = this.cache.keys().next().value;
-			if (!oldestKey) break;
-			const entry = this.cache.get(oldestKey);
-			if (!entry) break;
+		while (this.currentBytes > target) {
+			const oldest = this.cache.entries().next();
+			if (oldest.done) break;
+			const [oldestKey, entry] = oldest.value;
 			this.removeEntry(oldestKey, entry);
 			this._evictions++;
-			if (this.currentBytes <= target) break;
 		}
 	}
 	cleanupExpired() {
@@ -169,8 +163,16 @@ var MemoryCacheStore = class {
 		}
 	}
 };
-function clamp(value, min, max) {
-	return Math.min(max, Math.max(min, value));
+/** A non-finite option is a configuration bug — `Math.max(min, NaN)` is NaN, which silently disabled the cap. */
+function finite(name, value) {
+	if (!Number.isFinite(value)) throw new Error(`[arc] MemoryCacheStore ${name} must be a finite number, got ${String(value)}.`);
+	return value;
+}
+function clamp(name, value, min, max) {
+	return Math.min(max, Math.max(min, finite(name, value)));
+}
+function keyBytes(key) {
+	return Buffer.byteLength(key, "utf8");
 }
 /**
 * Translate a glob pattern (`prefix:*`, `*:tag:v`) into a regex. Only `*`

package/dist/{metrics-NMsmpRmY.mjs → metrics-DsZrvnpB.mjs}

@@ -1,5 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { a as MetricHistogram, i as DURATION_BUCKETS_SECONDS, o as MetricSeries, s as renderMetricSample } from "./health-CrqUp3sz.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/metrics.ts
 var metrics_exports = /* @__PURE__ */ __exportAll({
@@ -7,99 +8,64 @@ var metrics_exports = /* @__PURE__ */ __exportAll({
 	metricsPlugin: () => metricsPlugin
 });
 var Counter = class {
-	data = /* @__PURE__ */ new Map();
+	series;
+	constructor(maxSeries) {
+		this.series = new MetricSeries(maxSeries);
+	}
 	inc(labels, value = 1) {
-		const key = labelKey(labels);
-		const existing = this.data.get(key);
-		if (existing) existing.value += value;
-		else this.data.set(key, {
-			labels: { ...labels },
-			value
-		});
+		this.series.get(labels, () => ({ value: 0 })).value += value;
 	}
 	values() {
-		return [...this.data.values()];
-	}
-	reset() {
-		this.data.clear();
-	}
-};
-var Histogram = class {
-	data = /* @__PURE__ */ new Map();
-	observe(labels, value) {
-		const key = labelKey(labels);
-		const existing = this.data.get(key);
-		if (existing) {
-			existing.sum += value;
-			existing.count += 1;
-		} else this.data.set(key, {
+		return this.series.entries().map(({ labels, value }) => ({
 			labels: { ...labels },
-			sum: value,
-			count: 1
-		});
-	}
-	values() {
-		return [...this.data.values()].flatMap(({ labels, sum, count }) => [{
-			labels: {
-				...labels,
-				le: "sum"
-			},
-			value: sum
-		}, {
-			labels: {
-				...labels,
-				le: "count"
-			},
-			value: count
-		}]);
+			value: value.value
+		}));
 	}
 	reset() {
-		this.data.clear();
+		this.series.reset();
 	}
 };
 var Gauge = class {
-	data = /* @__PURE__ */ new Map();
+	series;
+	constructor(maxSeries) {
+		this.series = new MetricSeries(maxSeries);
+	}
 	set(labels, value) {
-		const key = labelKey(labels);
-		this.data.set(key, {
-			labels: { ...labels },
-			value
-		});
+		this.series.get(labels, () => ({ value: 0 })).value = value;
 	}
 	values() {
-		return [...this.data.values()];
+		return this.series.entries().map(({ labels, value }) => ({
+			labels: { ...labels },
+			value: value.value
+		}));
 	}
 	reset() {
-		this.data.clear();
+		this.series.reset();
 	}
 };
-function labelKey(labels) {
-	return Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(",");
-}
 function toPrometheusText(metrics) {
 	const lines = [];
 	for (const m of metrics) {
 		lines.push(`# HELP ${m.name} ${m.help}`);
 		lines.push(`# TYPE ${m.name} ${m.type}`);
-		for (const v of m.values) {
-			const labelStr = Object.entries(v.labels).map(([k, val]) => `${k}="${val}"`).join(",");
-			lines.push(`${m.name}{${labelStr}} ${v.value}`);
-		}
+		for (const v of m.values) lines.push(renderMetricSample(m.name, v));
 	}
 	return `${lines.join("\n")}\n`;
 }
 const metricsPlugin = async (fastify, opts = {}) => {
 	const path = opts.path ?? "/_metrics";
 	const prefix = opts.prefix ?? "arc";
-	const httpRequestsTotal = new Counter();
-	const crudOpsTotal = new Counter();
-	const cacheHitsTotal = new Counter();
-	const cacheMissesTotal = new Counter();
-	const eventsPublishedTotal = new Counter();
-	const eventsConsumedTotal = new Counter();
-	const httpDuration = new Histogram();
-	const crudDuration = new Histogram();
-	const circuitBreakerState = new Gauge();
+	const maxSeries = opts.maxSeries ?? 1e3;
+	if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(prefix)) throw new Error("metrics.prefix must be a valid Prometheus metric prefix");
+	const httpRequestsTotal = new Counter(maxSeries);
+	const crudOpsTotal = new Counter(maxSeries);
+	const cacheHitsTotal = new Counter(maxSeries);
+	const cacheMissesTotal = new Counter(maxSeries);
+	const eventsPublishedTotal = new Counter(maxSeries);
+	const eventsConsumedTotal = new Counter(maxSeries);
+	const httpDuration = new MetricHistogram(DURATION_BUCKETS_SECONDS, maxSeries);
+	const crudDuration = new MetricHistogram(DURATION_BUCKETS_SECONDS, maxSeries);
+	const circuitBreakerState = new Gauge(maxSeries);
 	const collector = {
 		collect() {
 			const metrics = [
@@ -196,17 +162,18 @@ const metricsPlugin = async (fastify, opts = {}) => {
 			eventsConsumedTotal.inc({ event_type: eventType });
 		},
 		recordCircuitBreakerState(service, state) {
-			const stateValue = state === "open" ? 1 : state === "half-open" ? 2 : 0;
+			const normalized = state.toLowerCase().replaceAll("_", "-");
+			const stateValue = normalized === "open" ? 1 : normalized === "half-open" ? 2 : 0;
 			circuitBreakerState.set({ service }, stateValue);
 		}
 	};
 	fastify.decorate("metrics", collector);
 	fastify.addHook("onResponse", async (request, reply) => {
-		if (request.url === path) return;
+		if (request.routeOptions.url === path) return;
 		const duration = reply.elapsedTime / 1e3;
 		const labels = {
 			method: request.method,
-			route: request.routeOptions?.url ?? request.url,
+			route: request.routeOptions.url ?? "__unmatched__",
 			status: String(reply.statusCode)
 		};
 		httpRequestsTotal.inc(labels);
@@ -222,4 +189,4 @@ var metrics_default = fp(metricsPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { metrics_default as n, metrics_exports as r, metricsPlugin as t };
+export { metrics_exports as n, metrics_default as t };

package/dist/middleware/index.d.mts

@@ -1,5 +1,5 @@
 
-import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-DHbyPo5j.mjs";
+import { A as RequestWithExtras, J as MiddlewareConfig, k as MiddlewareHandler } from "../index-WH7xgvxS.mjs";
 import { RouteHandlerMethod } from "fastify";
 //#region src/middleware/middleware.d.ts
 interface NamedMiddleware {
@@ -23,12 +23,12 @@ interface MiddlewareOptions {
 /**
  * Create a named middleware with priority and conditions.
  */
-declare function middleware(name: string, options: MiddlewareOptions): NamedMiddleware;
+export declare function middleware(name: string, options: MiddlewareOptions): NamedMiddleware;
 /**
  * Sort named middlewares by priority (ascending — lower runs first).
  * Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
  */
-declare function sortMiddlewares(middlewares: NamedMiddleware[]): MiddlewareConfig;
+export declare function sortMiddlewares(middlewares: NamedMiddleware[]): MiddlewareConfig;
 //#endregion
 //#region src/middleware/multipartBody.d.ts
 /** Parsed file from multipart form-data */
@@ -120,6 +120,6 @@ interface MultipartBodyOptions {
  * routes with strict rate limits — buffering video through the app tier is
  * the wrong architecture regardless of limits.
  */
-declare function multipartBody(options?: MultipartBodyOptions): RouteHandlerMethod;
+export declare function multipartBody(options?: MultipartBodyOptions): RouteHandlerMethod;
 //#endregion
-export { type MultipartBodyOptions, type NamedMiddleware, type ParsedFile, middleware, multipartBody, sortMiddlewares };
+export type { MiddlewareOptions, MultipartBodyOptions, NamedMiddleware, ParsedFile };

package/dist/middleware/index.mjs

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as CRUD_OPERATIONS } from "../constants-D5Ubn1fe.mjs";
-import { t as multipartBody } from "../multipartBody-DtRWM6_U.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as CRUD_OPERATIONS } from "../constants-B2QHb6u6.mjs";
+import { t as multipartBody } from "../multipartBody-Cc7eZ9cq.mjs";
 //#region src/middleware/middleware.ts
 /**
 * Named Middleware — Priority-based, conditional middleware execution.

package/dist/migrations/index.d.mts

@@ -1,7 +1,7 @@
 
 import { LockAdapter } from "@classytic/repo-core/lock";
 //#region src/migrations/index.d.ts
-interface Migration {
+export interface Migration {
   /** Migration version (sequential number) */
   version: number;
   /** Resource name this migration applies to */
@@ -22,7 +22,7 @@ interface Migration {
    */
   validate?: (db: unknown) => Promise<boolean>;
 }
-interface MigrationRecord {
+export interface MigrationRecord {
   version: number;
   resource: string;
   description?: string;
@@ -43,7 +43,7 @@ interface MigrationRecord {
  * - PrismaMigrationStore (uses a `_migrations` table)
  * - or any custom store
  */
-interface MigrationStore {
+export interface MigrationStore {
   /** Get all applied migration records, sorted by appliedAt ascending */
   getApplied(): Promise<MigrationRecord[]>;
   /**
@@ -60,7 +60,7 @@ interface MigrationStore {
 /**
  * Minimal logger interface — matches Fastify's logger, pino, console, etc.
  */
-interface MigrationLogger {
+export interface MigrationLogger {
   info(msg: string): void;
   error(msg: string): void;
 }
@@ -93,7 +93,7 @@ interface MongoCollectionLike {
 interface MongoDbLike {
   collection(name: string): MongoCollectionLike;
 }
-declare class MongoMigrationStore implements MigrationStore {
+export declare class MongoMigrationStore implements MigrationStore {
   private readonly collectionName;
   private readonly db;
   constructor(db: MongoDbLike, opts?: {
@@ -105,7 +105,7 @@ declare class MongoMigrationStore implements MigrationStore {
   }): Promise<void>;
   remove(migration: Migration): Promise<void>;
 }
-interface MigrationRunnerOptions {
+export interface MigrationRunnerOptions {
   /** Migration store (required — use MongoMigrationStore or implement your own) */
   store: MigrationStore;
   /** Logger (defaults to process.stdout/stderr) */
@@ -144,11 +144,11 @@ interface MigrationRunnerOptions {
  * `up`/`down` source. Stable for a given build; a transpile-target change
  * can legitimately shift it (hence `checksumMismatch: 'warn'` default).
  */
-declare function computeMigrationChecksum(migration: Migration): string;
+export declare function computeMigrationChecksum(migration: Migration): string;
 /**
  * Define a migration
  */
-declare function defineMigration(migration: Migration): Migration;
+export declare function defineMigration(migration: Migration): Migration;
 /**
  * Migration Runner
  *
@@ -171,7 +171,7 @@ declare function defineMigration(migration: Migration): Migration;
  * await runner.up(migrations);
  * ```
  */
-declare class MigrationRunner {
+export declare class MigrationRunner {
   private readonly db;
   private readonly store;
   private readonly log;
@@ -243,7 +243,7 @@ declare class MigrationRunner {
 /**
  * Schema version definition for resources
  */
-interface SchemaVersion {
+export interface SchemaVersion {
   version: number;
   migrations: Migration[];
 }
@@ -258,11 +258,11 @@ interface SchemaVersion {
  *   // ... rest of resource definition
  * });
  */
-declare function withSchemaVersion(version: number, migrations: Migration[]): SchemaVersion;
+export declare function withSchemaVersion(version: number, migrations: Migration[]): SchemaVersion;
 /**
  * Global migration registry
  */
-declare class MigrationRegistry {
+export declare class MigrationRegistry {
   private migrations;
   /**
    * Register a migration
@@ -290,4 +290,4 @@ declare class MigrationRegistry {
   clear(): void;
 }
 //#endregion
-export { Migration, MigrationLogger, MigrationRecord, MigrationRegistry, MigrationRunner, MigrationRunnerOptions, MigrationStore, MongoMigrationStore, SchemaVersion, computeMigrationChecksum, defineMigration, withSchemaVersion };
+export {};

package/dist/migrations/index.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as startRenewingLease } from "../renewingLease-yF8BdW4b.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { t as startRenewingLease } from "../renewingLease-BFJxGPuh.mjs";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/migrations/index.ts
 /**

package/dist/{module-DpLJG2_N.mjs → module--L0iBIZz.mjs}

@@ -1,18 +1,18 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
 //#region src/factory/module/index.ts
 /**
 * Identity helper for authoring a typed module — mirrors `defineResource`.
 * Gives inference + a single obvious construction site; does no work.
 *
-* `TExports` is inferred from the `bootstrap` return value, so a module
-* author gets a typed public export for free:
+* Everything is inferred: the export from `bootstrap`'s return, the port types from
+* `requires` (declare `requires` BEFORE the phases that read `ports`):
 *
 * ```ts
-* export const accountingModule = (deps: Deps) =>
-*   defineModule({
-*     name: "accounting",
-*     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
-*   });
+* defineModule({
+*   name: "accounting",
+*   requires: { ports: ["outbox"], optionalPorts: ["calendar"] },
+*   bootstrap: (f, { ports }) => createAccountingEngine(ports.outbox, ports.calendar),
+* });
 * ```
 */
 function defineModule(module) {