@classytic/arc 2.3.0 → 2.4.2

package/dist/{keys-DhqDRxv3.mjs → keys-qcD-TVJl.mjs}

@@ -29,14 +29,13 @@ function hashParams(params) {
 function stableStringify(value) {
 	if (value === null || value === void 0) return "";
 	if (typeof value !== "object") return String(value);
-	if (Array.isArray(value)) return "[" + value.map(stableStringify).join(",") + "]";
-	return "{" + Object.keys(value).sort().map((k) => k + ":" + stableStringify(value[k])).join(",") + "}";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return "{" + Object.keys(value).sort().map((k) => `${k}:${stableStringify(value[k])}`).join(",") + "}";
 }
 function djb2(str) {
 	let hash = 5381;
 	for (let i = 0; i < str.length; i++) hash = (hash << 5) + hash + str.charCodeAt(i) >>> 0;
 	return hash;
 }
-
 //#endregion
-export { versionKey as i, hashParams as n, tagVersionKey as r, buildQueryKey as t };
+export { versionKey as i, hashParams as n, tagVersionKey as r, buildQueryKey as t };

package/dist/{logger-ByrvQWZO.mjs → logger-Dz3j1ItV.mjs}

@@ -1,5 +1,4 @@
-import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
-
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 //#region src/logger/index.ts
 var logger_exports = /* @__PURE__ */ __exportAll({
 	arcLog: () => arcLog,
@@ -73,6 +72,5 @@ function isSuppressed() {
 	const env = typeof process !== "undefined" ? process.env?.ARC_SUPPRESS_WARNINGS : void 0;
 	return env === "1" || env === "true";
 }
-
 //#endregion
-export { configureArcLogger as n, logger_exports as r, arcLog as t };
+export { configureArcLogger as n, logger_exports as r, arcLog as t };

package/dist/{memory-B2v7KrCB.mjs → memory-Cb_7iy9e.mjs}

@@ -1,5 +1,4 @@
-import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
-
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 //#region src/cache/memory.ts
 var memory_exports = /* @__PURE__ */ __exportAll({
 	MemoryCacheStore: () => MemoryCacheStore,
@@ -138,6 +137,5 @@ var MemoryCacheStore = class {
 function clamp(value, min, max) {
 	return Math.min(max, Math.max(min, value));
 }
-
 //#endregion
-export { memory_exports as n, MemoryCacheStore as t };
+export { memory_exports as n, MemoryCacheStore as t };

package/dist/metrics-Csh4nsvv.mjs

@@ -0,0 +1,224 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import fp from "fastify-plugin";
+//#region src/plugins/metrics.ts
+var metrics_exports = /* @__PURE__ */ __exportAll({
+	default: () => metrics_default,
+	metricsPlugin: () => metricsPlugin
+});
+var Counter = class {
+	data = /* @__PURE__ */ new Map();
+	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
+		});
+	}
+	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, {
+			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
+		}]);
+	}
+	reset() {
+		this.data.clear();
+	}
+};
+var Gauge = class {
+	data = /* @__PURE__ */ new Map();
+	set(labels, value) {
+		const key = labelKey(labels);
+		this.data.set(key, {
+			labels: { ...labels },
+			value
+		});
+	}
+	values() {
+		return [...this.data.values()];
+	}
+	reset() {
+		this.data.clear();
+	}
+};
+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}`);
+		}
+	}
+	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 collector = {
+		collect() {
+			const metrics = [
+				{
+					name: `${prefix}_http_requests_total`,
+					type: "counter",
+					help: "Total HTTP requests",
+					values: httpRequestsTotal.values()
+				},
+				{
+					name: `${prefix}_http_request_duration_seconds`,
+					type: "histogram",
+					help: "HTTP request duration in seconds",
+					values: httpDuration.values()
+				},
+				{
+					name: `${prefix}_crud_operations_total`,
+					type: "counter",
+					help: "Total CRUD operations by resource",
+					values: crudOpsTotal.values()
+				},
+				{
+					name: `${prefix}_crud_operation_duration_seconds`,
+					type: "histogram",
+					help: "CRUD operation duration in seconds",
+					values: crudDuration.values()
+				},
+				{
+					name: `${prefix}_cache_hits_total`,
+					type: "counter",
+					help: "Total cache hits by resource",
+					values: cacheHitsTotal.values()
+				},
+				{
+					name: `${prefix}_cache_misses_total`,
+					type: "counter",
+					help: "Total cache misses by resource",
+					values: cacheMissesTotal.values()
+				},
+				{
+					name: `${prefix}_events_published_total`,
+					type: "counter",
+					help: "Total events published",
+					values: eventsPublishedTotal.values()
+				},
+				{
+					name: `${prefix}_events_consumed_total`,
+					type: "counter",
+					help: "Total events consumed",
+					values: eventsConsumedTotal.values()
+				},
+				{
+					name: `${prefix}_circuit_breaker_state`,
+					type: "gauge",
+					help: "Circuit breaker state (0=closed, 1=open, 2=half-open)",
+					values: circuitBreakerState.values()
+				}
+			];
+			opts.onCollect?.(metrics);
+			return metrics;
+		},
+		reset() {
+			httpRequestsTotal.reset();
+			httpDuration.reset();
+			crudOpsTotal.reset();
+			crudDuration.reset();
+			cacheHitsTotal.reset();
+			cacheMissesTotal.reset();
+			eventsPublishedTotal.reset();
+			eventsConsumedTotal.reset();
+			circuitBreakerState.reset();
+		},
+		recordOperation(resource, operation, status, durationMs) {
+			crudOpsTotal.inc({
+				resource,
+				operation,
+				status: String(status)
+			});
+			crudDuration.observe({
+				resource,
+				operation
+			}, durationMs / 1e3);
+		},
+		recordCacheHit(resource) {
+			cacheHitsTotal.inc({ resource });
+		},
+		recordCacheMiss(resource) {
+			cacheMissesTotal.inc({ resource });
+		},
+		recordEventPublish(eventType) {
+			eventsPublishedTotal.inc({ event_type: eventType });
+		},
+		recordEventConsume(eventType) {
+			eventsConsumedTotal.inc({ event_type: eventType });
+		},
+		recordCircuitBreakerState(service, state) {
+			const stateValue = state === "open" ? 1 : state === "half-open" ? 2 : 0;
+			circuitBreakerState.set({ service }, stateValue);
+		}
+	};
+	fastify.decorate("metrics", collector);
+	fastify.addHook("onResponse", async (request, reply) => {
+		if (request.url === path) return;
+		const duration = reply.elapsedTime / 1e3;
+		const labels = {
+			method: request.method,
+			route: request.routeOptions?.url ?? request.url,
+			status: String(reply.statusCode)
+		};
+		httpRequestsTotal.inc(labels);
+		httpDuration.observe(labels, duration);
+	});
+	fastify.get(path, async (_request, reply) => {
+		const text = toPrometheusText(collector.collect());
+		return reply.type("text/plain; charset=utf-8").send(text);
+	});
+};
+var metrics_default = fp(metricsPlugin, {
+	name: "arc-metrics",
+	fastify: "5.x"
+});
+//#endregion
+export { metrics_default as n, metrics_exports as r, metricsPlugin as t };

package/dist/migrations/index.d.mts

@@ -1,6 +1,41 @@
-import mongoose from "mongoose";
-
 //#region src/migrations/index.d.ts
+/**
+ * Schema Versioning and Migrations System
+ *
+ * Manages database schema changes over time with version tracking.
+ * Supports forward migrations, rollbacks, and schema compatibility layers.
+ *
+ * DB-agnostic: the `db` parameter is typed as `unknown` — the user passes
+ * whatever connection object their adapter uses (Mongoose db, Prisma client,
+ * Knex instance, etc.) and their `up`/`down` functions cast it internally.
+ *
+ * @example
+ * import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
+ *
+ * const productV2 = defineMigration({
+ *   version: 2,
+ *   resource: 'product',
+ *   up: async (db) => {
+ *     const mongo = db as import('mongoose').mongo.Db;
+ *     await mongo.collection('products').updateMany(
+ *       {},
+ *       { $rename: { 'oldField': 'newField' } }
+ *     );
+ *   },
+ *   down: async (db) => {
+ *     const mongo = db as import('mongoose').mongo.Db;
+ *     await mongo.collection('products').updateMany(
+ *       {},
+ *       { $rename: { 'newField': 'oldField' } }
+ *     );
+ *   },
+ * });
+ *
+ * const runner = new MigrationRunner(mongoose.connection.db, {
+ *   store: new MongoMigrationStore(mongoose.connection.db),
+ * });
+ * await runner.up(migrations);
+ */
 interface Migration {
   /** Migration version (sequential number) */
   version: number;
@@ -9,17 +44,18 @@ interface Migration {
   /** Description of the migration */
   description?: string;
   /**
-   * Forward migration (apply schema change)
+   * Forward migration (apply schema change).
+   * The `db` parameter is whatever connection object you pass to the runner.
    */
-  up: (db: mongoose.mongo.Db) => Promise<void>;
+  up: (db: unknown) => Promise<void>;
   /**
-   * Backward migration (revert schema change)
+   * Backward migration (revert schema change).
    */
-  down: (db: mongoose.mongo.Db) => Promise<void>;
+  down: (db: unknown) => Promise<void>;
   /**
    * Optional validation that data is compatible after migration
    */
-  validate?: (db: mongoose.mongo.Db) => Promise<boolean>;
+  validate?: (db: unknown) => Promise<boolean>;
 }
 interface MigrationRecord {
   version: number;
@@ -28,6 +64,54 @@ interface MigrationRecord {
   appliedAt: Date;
   executionTime: number;
 }
+/**
+ * DB-agnostic migration store interface.
+ *
+ * Users implement this for their database:
+ * - MongoMigrationStore (uses a `_migrations` collection)
+ * - PrismaMigrationStore (uses a `_migrations` table)
+ * - or any custom store
+ */
+interface MigrationStore {
+  /** Get all applied migration records, sorted by appliedAt ascending */
+  getApplied(): Promise<MigrationRecord[]>;
+  /** Record a completed migration */
+  record(migration: Migration, executionTime: number): Promise<void>;
+  /** Remove a migration record (for rollback) */
+  remove(migration: Migration): Promise<void>;
+}
+/**
+ * Minimal logger interface — matches Fastify's logger, pino, console, etc.
+ */
+interface MigrationLogger {
+  info(msg: string): void;
+  error(msg: string): void;
+}
+/**
+ * MongoDB-backed migration store.
+ *
+ * Uses a `_migrations` collection in the same database.
+ * The `db` parameter accepts any object with a `.collection()` method
+ * (Mongoose db, native MongoDB Db, etc.)
+ */
+declare class MongoMigrationStore implements MigrationStore {
+  private readonly collectionName;
+  private readonly db;
+  constructor(db: {
+    collection(name: string): any;
+  }, opts?: {
+    collectionName?: string;
+  });
+  getApplied(): Promise<MigrationRecord[]>;
+  record(migration: Migration, executionTime: number): Promise<void>;
+  remove(migration: Migration): Promise<void>;
+}
+interface MigrationRunnerOptions {
+  /** Migration store (required — use MongoMigrationStore or implement your own) */
+  store: MigrationStore;
+  /** Logger (defaults to process.stdout/stderr) */
+  logger?: MigrationLogger;
+}
 /**
  * Define a migration
  */
@@ -35,12 +119,30 @@ declare function defineMigration(migration: Migration): Migration;
 /**
  * Migration Runner
  *
- * Manages execution of migrations with tracking and rollback support.
+ * DB-agnostic. Manages execution of migrations with tracking and rollback.
+ * The `db` parameter is passed through to migration `up`/`down` functions
+ * as-is — the runner never touches it directly.
+ *
+ * @example
+ * ```typescript
+ * // MongoDB
+ * const runner = new MigrationRunner(mongoose.connection.db, {
+ *   store: new MongoMigrationStore(mongoose.connection.db),
+ * });
+ *
+ * // Prisma
+ * const runner = new MigrationRunner(prisma, {
+ *   store: new PrismaMigrationStore(prisma), // user-implemented
+ * });
+ *
+ * await runner.up(migrations);
+ * ```
  */
 declare class MigrationRunner {
-  private readonly collectionName;
   private readonly db;
-  constructor(db: mongoose.mongo.Db);
+  private readonly store;
+  private readonly log;
+  constructor(db: unknown, opts: MigrationRunnerOptions);
   /**
    * Run all pending migrations
    */
@@ -69,14 +171,6 @@ declare class MigrationRunner {
    * Run a single migration
    */
   private runMigration;
-  /**
-   * Record a completed migration
-   */
-  private recordMigration;
-  /**
-   * Remove a migration record
-   */
-  private removeMigration;
 }
 /**
  * Schema version definition for resources
@@ -127,30 +221,5 @@ declare class MigrationRegistry {
    */
   clear(): void;
 }
-/**
- * Global migration registry instance
- */
-declare const migrationRegistry: MigrationRegistry;
-/**
- * Common migration helpers
- */
-declare const migrationHelpers: {
-  /**
-   * Rename a field across all documents
-   */
-  renameField: (collection: string, oldName: string, newName: string) => Migration;
-  /**
-   * Add a new field with default value
-   */
-  addField: (collection: string, fieldName: string, defaultValue: unknown) => Migration;
-  /**
-   * Remove a field
-   */
-  removeField: (collection: string, fieldName: string) => Migration;
-  /**
-   * Create an index
-   */
-  createIndex: (collection: string, fields: Record<string, 1 | -1>, options?: Record<string, unknown>) => Migration;
-};
 //#endregion
-export { Migration, MigrationRecord, MigrationRegistry, MigrationRunner, SchemaVersion, defineMigration, migrationHelpers, migrationRegistry, withSchemaVersion };
+export { Migration, MigrationLogger, MigrationRecord, MigrationRegistry, MigrationRunner, MigrationRunnerOptions, MigrationStore, MongoMigrationStore, SchemaVersion, defineMigration, withSchemaVersion };