@classytic/arc 1.1.0 → 2.1.3

package/dist/introspectionPlugin-B3JkrjwU.mjs

@@ -0,0 +1,53 @@
+import fp from "fastify-plugin";
+
+//#region src/registry/introspectionPlugin.ts
+/**
+* Introspection Plugin
+*
+* Exposes resource registry via API endpoints.
+*/
+const introspectionPlugin = async (fastify, opts = {}) => {
+	const { prefix = "/_resources", authRoles = ["superadmin"], enabled = true } = opts;
+	if (!enabled) {
+		fastify.log?.debug?.("Introspection plugin disabled");
+		return;
+	}
+	const typedFastify = fastify;
+	const authMiddleware = authRoles.length > 0 && typedFastify.authenticate ? [typedFastify.authenticate, typedFastify.authorize?.(...authRoles)].filter(Boolean) : [];
+	const getRegistry = () => fastify.arc?.registry;
+	await fastify.register(async (instance) => {
+		instance.get("/", { preHandler: authMiddleware }, async (_req, _reply) => {
+			return getRegistry()?.getIntrospection() ?? {
+				resources: [],
+				stats: {},
+				generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+		});
+		instance.get("/stats", { preHandler: authMiddleware }, async (_req, _reply) => {
+			return getRegistry()?.getStats() ?? {
+				totalResources: 0,
+				byModule: {},
+				presetUsage: {},
+				totalRoutes: 0,
+				totalEvents: 0
+			};
+		});
+		instance.get("/:name", {
+			schema: { params: {
+				type: "object",
+				properties: { name: { type: "string" } },
+				required: ["name"]
+			} },
+			preHandler: authMiddleware
+		}, async (req, reply) => {
+			const resource = getRegistry()?.get(req.params.name);
+			if (!resource) return reply.code(404).send({ error: `Resource '${req.params.name}' not found` });
+			return resource;
+		});
+	}, { prefix });
+	fastify.log?.debug?.(`Introspection API at ${prefix}`);
+};
+var introspectionPlugin_default = fp(introspectionPlugin, { name: "arc-introspection" });
+
+//#endregion
+export { introspectionPlugin_default as n, introspectionPlugin as t };

package/dist/keys-DhqDRxv3.mjs

@@ -0,0 +1,42 @@
+//#region src/cache/keys.ts
+/**
+* Cache Key Utilities
+*
+* Deterministic, scope-safe key generation for QueryCache.
+* Keys include resource version, operation, params hash, and user/org scope
+* to ensure multi-tenant isolation and O(1) version-based invalidation.
+*/
+/** Build a deterministic cache key for a query */
+function buildQueryKey(resource, operation, resourceVersion, params, userId, orgId) {
+	return `arc:${resource}:${resourceVersion}:${operation}:${hashParams(params)}:u=${userId ?? "anon"}:o=${orgId ?? "pub"}`;
+}
+/** Resource version key — stored in CacheStore, bumped on mutations */
+function versionKey(resource) {
+	return `arc:ver:${resource}`;
+}
+/** Tag version key — stored in CacheStore, bumped on cross-resource invalidation */
+function tagVersionKey(tag) {
+	return `arc:tagver:${tag}`;
+}
+/**
+* Stable hash for query params.
+* Sorts keys recursively, serializes to JSON, then applies djb2 hash.
+* Returns hex string.
+*/
+function hashParams(params) {
+	return djb2(stableStringify(params)).toString(36);
+}
+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(",") + "}";
+}
+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 };

package/dist/logger-ByrvQWZO.mjs

@@ -0,0 +1,78 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+
+//#region src/logger/index.ts
+var logger_exports = /* @__PURE__ */ __exportAll({
+	arcLog: () => arcLog,
+	configureArcLogger: () => configureArcLogger
+});
+let globalOptions = {};
+/**
+* Configure the Arc logger globally.
+*
+* Called automatically by `createApp({ debug })`, but can also be
+* called manually for standalone usage outside of `createApp`.
+*/
+function configureArcLogger(options) {
+	globalOptions = { ...options };
+}
+/**
+* Create a module-scoped logger.
+*
+* Debug and info messages are gated by the `ARC_DEBUG` env var or
+* `createApp({ debug })` option. Warnings always show (unless
+* `ARC_SUPPRESS_WARNINGS=1`). Errors always show.
+*
+* @param module - Module name (e.g., 'scope', 'elevation', 'sse', 'preset')
+* @returns Logger instance for that module
+*
+* @example
+* ```typescript
+* const log = arcLog('elevation');
+* log.debug('Checking elevation header');
+* log.warn('No authenticate decorator found');
+* ```
+*/
+function arcLog(module) {
+	const prefix = `[arc:${module}]`;
+	return {
+		debug(...args) {
+			if (isDebugEnabled(module)) getWriter().debug(prefix, ...args);
+		},
+		info(...args) {
+			if (isDebugEnabled(module)) getWriter().info(prefix, ...args);
+		},
+		warn(...args) {
+			if (isSuppressed()) return;
+			getWriter().warn(prefix, ...args);
+		},
+		error(...args) {
+			getWriter().error(prefix, ...args);
+		}
+	};
+}
+function getWriter() {
+	return globalOptions.writer ?? console;
+}
+function isDebugEnabled(module) {
+	const configDebug = globalOptions.debug;
+	if (configDebug !== void 0 && configDebug !== false) return matchesModule(configDebug, module);
+	const envDebug = typeof process !== "undefined" ? process.env?.ARC_DEBUG : void 0;
+	if (envDebug) return matchesModule(envDebug, module);
+	return false;
+}
+function matchesModule(debug, module) {
+	if (debug === true) return true;
+	if (typeof debug === "string") {
+		const normalized = debug.trim();
+		if (normalized === "1" || normalized === "true" || normalized === "*") return true;
+		return normalized.split(",").map((s) => s.trim()).includes(module);
+	}
+	return false;
+}
+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 };

package/dist/memory-B2v7KrCB.mjs

@@ -0,0 +1,143 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+
+//#region src/cache/memory.ts
+var memory_exports = /* @__PURE__ */ __exportAll({
+	MemoryCacheStore: () => MemoryCacheStore,
+	default: () => MemoryCacheStore
+});
+/**
+* In-memory LRU+TTL cache store with hard entry cap and memory budget.
+* - LRU eviction when `maxEntries` or `maxMemoryBytes` is reached
+* - TTL expiration on read + periodic cleanup
+* - Entry size guard to avoid runaway memory usage
+* - Stats tracking for observability
+*/
+var MemoryCacheStore = class {
+	name = "memory-cache";
+	cache = /* @__PURE__ */ new Map();
+	defaultTtlMs;
+	maxEntries;
+	maxEntryBytes;
+	maxMemoryBytes;
+	evictionWatermark;
+	logger;
+	cleanupTimer;
+	currentBytes = 0;
+	_hits = 0;
+	_misses = 0;
+	_evictions = 0;
+	constructor(options = {}) {
+		this.defaultTtlMs = options.defaultTtlMs ?? 6e4;
+		this.maxEntries = clamp(options.maxEntries ?? 1e3, 1, 1e5);
+		this.maxEntryBytes = clamp(options.maxEntryBytes ?? 256 * 1024, 1024, 10 * 1024 * 1024);
+		this.maxMemoryBytes = options.maxMemoryBytes ?? 50 * 1024 * 1024;
+		this.evictionWatermark = clamp(options.evictionWatermark ?? .9, .5, 1);
+		this.logger = options.logger ?? console;
+		const cleanupIntervalMs = clamp(options.cleanupIntervalMs ?? 3e4, 1e3, 600 * 1e3);
+		this.cleanupTimer = setInterval(() => this.cleanupExpired(), cleanupIntervalMs);
+		if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+	}
+	async get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) {
+			this._misses++;
+			return;
+		}
+		if (entry.expiresAt <= Date.now()) {
+			this.removeEntry(key, entry);
+			this._misses++;
+			return;
+		}
+		this.cache.delete(key);
+		this.cache.set(key, entry);
+		this._hits++;
+		return entry.value;
+	}
+	async set(key, value, options = {}) {
+		const ttlMs = options.ttlMs ?? this.defaultTtlMs;
+		if (!Number.isFinite(ttlMs) || ttlMs <= 0) return;
+		const size = this.estimateSize(value);
+		if (size > this.maxEntryBytes) {
+			this.logger.warn(`[MemoryCacheStore] Skipping oversized entry for key '${key}' (${size} bytes > ${this.maxEntryBytes} bytes)`);
+			return;
+		}
+		const existing = this.cache.get(key);
+		if (existing) {
+			this.currentBytes -= existing.size;
+			this.cache.delete(key);
+		}
+		this.cache.set(key, {
+			value,
+			size,
+			expiresAt: Date.now() + ttlMs
+		});
+		this.currentBytes += size;
+		this.evictToLimit();
+		if (this.maxMemoryBytes > 0) this.evictToMemoryLimit();
+	}
+	async delete(key) {
+		const entry = this.cache.get(key);
+		if (entry) this.removeEntry(key, entry);
+	}
+	async clear() {
+		this.cache.clear();
+		this.currentBytes = 0;
+	}
+	async close() {
+		clearInterval(this.cleanupTimer);
+		this.cache.clear();
+		this.currentBytes = 0;
+	}
+	stats() {
+		return {
+			entries: this.cache.size,
+			memoryBytes: this.currentBytes,
+			hits: this._hits,
+			misses: this._misses,
+			evictions: this._evictions
+		};
+	}
+	removeEntry(key, entry) {
+		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);
+			this.removeEntry(oldestKey, entry);
+			this._evictions++;
+		}
+	}
+	evictToMemoryLimit() {
+		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);
+			this.removeEntry(oldestKey, entry);
+			this._evictions++;
+			if (this.currentBytes <= target) break;
+		}
+	}
+	cleanupExpired() {
+		const now = Date.now();
+		for (const [key, entry] of this.cache.entries()) if (entry.expiresAt <= now) this.removeEntry(key, entry);
+	}
+	estimateSize(value) {
+		try {
+			const json = JSON.stringify(value);
+			if (!json) return 0;
+			return Buffer.byteLength(json, "utf8");
+		} catch {
+			return this.maxEntryBytes + 1;
+		}
+	}
+};
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, value));
+}
+
+//#endregion
+export { memory_exports as n, MemoryCacheStore as t };

package/dist/migrations/index.d.mts

@@ -0,0 +1,156 @@
+import mongoose from "mongoose";
+
+//#region src/migrations/index.d.ts
+interface Migration {
+  /** Migration version (sequential number) */
+  version: number;
+  /** Resource name this migration applies to */
+  resource: string;
+  /** Description of the migration */
+  description?: string;
+  /**
+   * Forward migration (apply schema change)
+   */
+  up: (db: mongoose.mongo.Db) => Promise<void>;
+  /**
+   * Backward migration (revert schema change)
+   */
+  down: (db: mongoose.mongo.Db) => Promise<void>;
+  /**
+   * Optional validation that data is compatible after migration
+   */
+  validate?: (db: mongoose.mongo.Db) => Promise<boolean>;
+}
+interface MigrationRecord {
+  version: number;
+  resource: string;
+  description?: string;
+  appliedAt: Date;
+  executionTime: number;
+}
+/**
+ * Define a migration
+ */
+declare function defineMigration(migration: Migration): Migration;
+/**
+ * Migration Runner
+ *
+ * Manages execution of migrations with tracking and rollback support.
+ */
+declare class MigrationRunner {
+  private readonly collectionName;
+  private readonly db;
+  constructor(db: mongoose.mongo.Db);
+  /**
+   * Run all pending migrations
+   */
+  up(migrations: Migration[]): Promise<void>;
+  /**
+   * Rollback last migration
+   */
+  down(migrations: Migration[]): Promise<void>;
+  /**
+   * Rollback to specific version
+   */
+  downTo(migrations: Migration[], targetVersion: number): Promise<void>;
+  /**
+   * Get all applied migrations
+   */
+  getAppliedMigrations(): Promise<MigrationRecord[]>;
+  /**
+   * Get pending migrations
+   */
+  getPendingMigrations(migrations: Migration[]): Promise<Migration[]>;
+  /**
+   * Check if migrations are up to date
+   */
+  isUpToDate(migrations: Migration[]): Promise<boolean>;
+  /**
+   * Run a single migration
+   */
+  private runMigration;
+  /**
+   * Record a completed migration
+   */
+  private recordMigration;
+  /**
+   * Remove a migration record
+   */
+  private removeMigration;
+}
+/**
+ * Schema version definition for resources
+ */
+interface SchemaVersion {
+  version: number;
+  migrations: Migration[];
+}
+/**
+ * Add versioning to resource definition
+ *
+ * @example
+ * export default defineResource({
+ *   name: 'product',
+ *   version: 2,
+ *   migrations: [productV1ToV2Migration],
+ *   // ... rest of resource definition
+ * });
+ */
+declare function withSchemaVersion(version: number, migrations: Migration[]): SchemaVersion;
+/**
+ * Global migration registry
+ */
+declare class MigrationRegistry {
+  private migrations;
+  /**
+   * Register a migration
+   */
+  register(migration: Migration): void;
+  /**
+   * Register multiple migrations
+   */
+  registerMany(migrations: Migration[]): void;
+  /**
+   * Get all migrations for a resource
+   */
+  getForResource(resource: string): Migration[];
+  /**
+   * Get all migrations
+   */
+  getAll(): Migration[];
+  /**
+   * Get migration by resource and version
+   */
+  get(resource: string, version: number): Migration | undefined;
+  /**
+   * Clear all registrations
+   */
+  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 };