@classytic/arc 2.3.0 → 2.4.2

package/dist/utils/index.mjs

@@ -1,6 +1,7 @@
-import { C as ArcQueryParser, S as wrapResponse, _ as paginateWrapper, a as createCircuitBreaker, b as responses, c as deleteResponse, d as getListQueryParams, f as itemResponse, g as mutationResponse, h as messageWrapper, i as CircuitState, l as errorResponseSchema, m as listResponse, n as CircuitBreakerError, o as createCircuitBreakerRegistry, p as itemWrapper, r as CircuitBreakerRegistry, s as createStateMachine, t as CircuitBreaker, u as getDefaultCrudSchemas, v as paginationSchema, w as createQueryParser, x as successResponseSchema, y as queryParams } from "../circuitBreaker-CSS2VvL6.mjs";
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createError, f as isArcError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-DBANPbGr.mjs";
-import { t as hasEvents } from "../typeGuards-DwxA1t_L.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Dtg0Kt9T.mjs";
-
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, wrapResponse };
+import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
+import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
+import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-Dc0WhlIl.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createError, f as isArcError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-rxhfP7Hf.mjs";
+import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DjzHpFam.mjs";
+import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, defineCompensation, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/dist/utils-Dc0WhlIl.mjs

@@ -0,0 +1,594 @@
+//#region src/utils/compensation.ts
+/**
+* Run steps in order with automatic compensation on failure.
+*
+* @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
+*/
+async function withCompensation(_name, steps, initialContext, hooks) {
+	const ctx = { ...initialContext };
+	const completedSteps = [];
+	const results = {};
+	const completed = [];
+	for (const step of steps) {
+		if (step.fireAndForget) {
+			completedSteps.push(step.name);
+			step.execute(ctx).then((result) => hooks?.onStepComplete?.(step.name, result), () => {});
+			continue;
+		}
+		try {
+			const result = await step.execute(ctx);
+			completedSteps.push(step.name);
+			results[step.name] = result;
+			completed.push({
+				step,
+				result
+			});
+			hooks?.onStepComplete?.(step.name, result);
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			hooks?.onStepFailed?.(step.name, error);
+			const compensationErrors = await rollback(ctx, completed, hooks);
+			return {
+				success: false,
+				completedSteps,
+				results,
+				failedStep: step.name,
+				error: error.message,
+				...compensationErrors.length > 0 ? { compensationErrors } : {}
+			};
+		}
+	}
+	return {
+		success: true,
+		completedSteps,
+		results
+	};
+}
+async function rollback(ctx, completed, hooks) {
+	const errors = [];
+	for (let i = completed.length - 1; i >= 0; i--) {
+		const entry = completed[i];
+		if (!entry?.step.compensate) continue;
+		const compensateFn = entry.step.compensate;
+		try {
+			await compensateFn(ctx, entry.result);
+			hooks?.onCompensate?.(entry.step.name);
+		} catch (err) {
+			errors.push({
+				step: entry.step.name,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	}
+	return errors;
+}
+function defineCompensation(name, steps) {
+	return {
+		name,
+		execute: (initialContext, hooks) => withCompensation(name, steps, initialContext, hooks)
+	};
+}
+//#endregion
+//#region src/utils/responseSchemas.ts
+/**
+* Base success response schema
+*/
+const successResponseSchema = {
+	type: "object",
+	properties: { success: {
+		type: "boolean",
+		example: true
+	} },
+	required: ["success"]
+};
+/**
+* Error response schema
+*/
+const errorResponseSchema = {
+	type: "object",
+	properties: {
+		success: {
+			type: "boolean",
+			example: false
+		},
+		error: {
+			type: "string",
+			description: "Error message"
+		},
+		code: {
+			type: "string",
+			description: "Error code"
+		},
+		message: {
+			type: "string",
+			description: "Detailed message"
+		}
+	},
+	required: ["success", "error"]
+};
+/**
+* Pagination schema - matches MongoKit/Arc runtime format
+*
+* Runtime format (flat fields):
+* { page, limit, total, pages, hasNext, hasPrev }
+*/
+const paginationSchema = {
+	type: "object",
+	properties: {
+		page: {
+			type: "integer",
+			example: 1
+		},
+		limit: {
+			type: "integer",
+			example: 20
+		},
+		total: {
+			type: "integer",
+			example: 100
+		},
+		pages: {
+			type: "integer",
+			example: 5
+		},
+		hasNext: {
+			type: "boolean",
+			example: true
+		},
+		hasPrev: {
+			type: "boolean",
+			example: false
+		}
+	},
+	required: [
+		"page",
+		"limit",
+		"total",
+		"pages",
+		"hasNext",
+		"hasPrev"
+	]
+};
+/**
+* Wrap a data schema in a success response
+*/
+function wrapResponse(dataSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: dataSchema
+		},
+		required: ["success", "data"],
+		additionalProperties: true
+	};
+}
+/**
+* Create a list response schema with pagination - matches MongoKit/Arc runtime format
+*
+* Runtime format:
+* { success, docs: [...], page, limit, total, pages, hasNext, hasPrev }
+*
+* Note: Uses 'docs' array (not 'data') with flat pagination fields
+*/
+function listResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			docs: {
+				type: "array",
+				items: itemSchema
+			},
+			page: {
+				type: "integer",
+				example: 1
+			},
+			limit: {
+				type: "integer",
+				example: 20
+			},
+			total: {
+				type: "integer",
+				example: 100
+			},
+			pages: {
+				type: "integer",
+				example: 5
+			},
+			hasNext: {
+				type: "boolean",
+				example: false
+			},
+			hasPrev: {
+				type: "boolean",
+				example: false
+			}
+		},
+		required: ["success", "docs"],
+		additionalProperties: true
+	};
+}
+/**
+* Alias for listResponse - matches local responseSchemas.js naming
+*/
+const paginateWrapper = listResponse;
+/**
+* Create a single item response schema
+*
+* Runtime format: { success, data: {...} }
+*/
+function itemResponse(itemSchema) {
+	return wrapResponse(itemSchema);
+}
+/**
+* Alias for itemResponse - matches local responseSchemas.js naming
+*/
+const itemWrapper = itemResponse;
+/**
+* Create a create/update response schema
+*/
+function mutationResponse(itemSchema) {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: itemSchema,
+			message: {
+				type: "string",
+				example: "Created successfully"
+			}
+		},
+		required: ["success", "data"],
+		additionalProperties: true
+	};
+}
+/**
+* Create a delete response schema
+*
+* Runtime format: { success, data: { message, id?, soft? } }
+*/
+function deleteResponse() {
+	return {
+		type: "object",
+		properties: {
+			success: {
+				type: "boolean",
+				example: true
+			},
+			data: {
+				type: "object",
+				properties: {
+					message: {
+						type: "string",
+						example: "Deleted successfully"
+					},
+					id: {
+						type: "string",
+						example: "507f1f77bcf86cd799439011"
+					},
+					soft: {
+						type: "boolean",
+						example: false
+					}
+				},
+				required: ["message"]
+			}
+		},
+		required: ["success"],
+		additionalProperties: true
+	};
+}
+/**
+* Alias for deleteResponse - matches local responseSchemas.js naming
+*/
+const messageWrapper = deleteResponse;
+const responses = {
+	200: (schema) => ({
+		description: "Successful response",
+		content: { "application/json": { schema } }
+	}),
+	201: (schema) => ({
+		description: "Created successfully",
+		content: { "application/json": { schema: mutationResponse(schema) } }
+	}),
+	400: {
+		description: "Bad Request",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "VALIDATION_ERROR"
+				},
+				details: {
+					type: "object",
+					properties: { errors: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								field: { type: "string" },
+								message: { type: "string" }
+							}
+						}
+					} }
+				}
+			}
+		} } }
+	},
+	401: {
+		description: "Unauthorized",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "UNAUTHORIZED"
+				}
+			}
+		} } }
+	},
+	403: {
+		description: "Forbidden",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "FORBIDDEN"
+				}
+			}
+		} } }
+	},
+	404: {
+		description: "Not Found",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "NOT_FOUND"
+				}
+			}
+		} } }
+	},
+	409: {
+		description: "Conflict",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "CONFLICT"
+				}
+			}
+		} } }
+	},
+	500: {
+		description: "Internal Server Error",
+		content: { "application/json": { schema: {
+			...errorResponseSchema,
+			properties: {
+				...errorResponseSchema.properties,
+				code: {
+					type: "string",
+					example: "INTERNAL_ERROR"
+				}
+			}
+		} } }
+	}
+};
+const queryParams = {
+	pagination: {
+		page: {
+			type: "integer",
+			minimum: 1,
+			default: 1,
+			description: "Page number"
+		},
+		limit: {
+			type: "integer",
+			minimum: 1,
+			maximum: 100,
+			default: 20,
+			description: "Items per page"
+		}
+	},
+	sorting: { sort: {
+		type: "string",
+		description: "Sort field (prefix with - for descending)",
+		example: "-createdAt"
+	} },
+	filtering: {
+		select: {
+			description: "Fields to include (space-separated or object)",
+			example: "name email createdAt"
+		},
+		populate: {
+			description: "Relations to populate (comma-separated string or bracket-notation object)",
+			example: "author,category"
+		}
+	}
+};
+/**
+* Get standard list query parameters schema
+*/
+function getListQueryParams() {
+	return {
+		type: "object",
+		properties: {
+			...queryParams.pagination,
+			...queryParams.sorting,
+			...queryParams.filtering
+		},
+		additionalProperties: true
+	};
+}
+/**
+* Generic item schema that allows any properties.
+* Used as default when no user schema is provided.
+* Enables fast-json-stringify while still passing through all fields.
+*/
+const genericItemSchema = {
+	type: "object",
+	additionalProperties: true
+};
+/**
+* Recursively strip `example` keys from a schema object.
+* The `example` keyword is OpenAPI metadata — not standard JSON Schema —
+* and triggers Ajv strict mode errors when used on routes without the
+* `keywords: ['example']` AJV config (e.g., raw Fastify without createApp).
+*/
+function stripExamples(schema) {
+	if (schema === null || typeof schema !== "object") return schema;
+	if (Array.isArray(schema)) return schema.map(stripExamples);
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) {
+		if (key === "example") continue;
+		result[key] = stripExamples(value);
+	}
+	return result;
+}
+/**
+* Get default response schemas for all CRUD operations.
+*
+* When routes have response schemas, Fastify compiles them with
+* fast-json-stringify for 2-3x faster serialization and prevents
+* accidental field disclosure.
+*
+* These defaults use `additionalProperties: true` so all fields pass through.
+* Override with specific schemas for full serialization performance + safety.
+*
+* Note: `example` properties are stripped from defaults so they work with
+* any Fastify instance (not just createApp which adds `keywords: ['example']`).
+*/
+function getDefaultCrudSchemas() {
+	return stripExamples({
+		list: {
+			querystring: getListQueryParams(),
+			response: { 200: listResponse(genericItemSchema) }
+		},
+		get: { response: { 200: itemResponse(genericItemSchema) } },
+		create: { response: { 201: mutationResponse(genericItemSchema) } },
+		update: { response: { 200: itemResponse(genericItemSchema) } },
+		delete: { response: { 200: deleteResponse() } }
+	});
+}
+//#endregion
+//#region src/utils/stateMachine.ts
+/**
+* Create a state machine for validating transitions
+*
+* @param name - Name of the state machine (used in error messages)
+* @param transitions - Map of actions to allowed source statuses
+* @param options - Additional options (history, guards, actions)
+* @returns State machine with can() and assert() methods
+*
+* @example
+* // Basic usage
+* const transferState = createStateMachine('Transfer', {
+*   approve: ['draft'],
+*   dispatch: ['approved'],
+*   receive: ['dispatched', 'in_transit'],
+*   cancel: ['draft', 'approved'],
+* });
+*
+* @example
+* // With guards and actions
+* const orderState = createStateMachine('Order', {
+*   approve: {
+*     from: ['pending'],
+*     to: 'approved',
+*     guard: ({ data }) => data.paymentConfirmed,
+*     before: ({ from, to }) => console.log(`Approving order from ${from} to ${to}`),
+*     after: ({ data }) => sendApprovalEmail(data.customerId),
+*   },
+* }, { trackHistory: true });
+*/
+function createStateMachine(name, transitions = {}, options = {}) {
+	const normalized = /* @__PURE__ */ new Map();
+	const history = options.trackHistory ? [] : void 0;
+	Object.entries(transitions).forEach(([action, allowed]) => {
+		if (Array.isArray(allowed)) normalized.set(action, { from: new Set(allowed) });
+		else if (typeof allowed === "object" && "from" in allowed) normalized.set(action, {
+			from: new Set(Array.isArray(allowed.from) ? allowed.from : [allowed.from]),
+			to: allowed.to,
+			guard: allowed.guard,
+			before: allowed.before,
+			after: allowed.after
+		});
+	});
+	const can = (action, status) => {
+		const transition = normalized.get(action);
+		if (!transition || !status) return false;
+		return transition.from.has(status);
+	};
+	const canAsync = async (action, status, context) => {
+		const transition = normalized.get(action);
+		if (!transition || !status) return false;
+		if (!transition.from.has(status)) return false;
+		if (transition.guard) try {
+			return await transition.guard({
+				from: status,
+				to: transition.to || "",
+				action,
+				data: context
+			});
+		} catch {
+			return false;
+		}
+		return true;
+	};
+	const assert = (action, status, errorFactory, message) => {
+		if (can(action, status)) return;
+		const errorMessage = message || `${name} cannot '${action}' when status is '${status || "unknown"}'`;
+		if (typeof errorFactory === "function") throw errorFactory(errorMessage);
+		throw new Error(errorMessage);
+	};
+	const recordTransition = (from, to, action, metadata) => {
+		if (history) history.push({
+			from,
+			to,
+			action,
+			timestamp: /* @__PURE__ */ new Date(),
+			metadata
+		});
+	};
+	const getHistory = () => {
+		return history ? [...history] : [];
+	};
+	const clearHistory = () => {
+		if (history) history.length = 0;
+	};
+	const getAvailableActions = (status) => {
+		const actions = [];
+		for (const [action, transition] of normalized.entries()) if (transition.from.has(status)) actions.push(action);
+		return actions;
+	};
+	return {
+		can,
+		canAsync,
+		assert,
+		recordTransition,
+		getHistory,
+		clearHistory,
+		getAvailableActions
+	};
+}
+//#endregion
+export { defineCompensation as _, getListQueryParams as a, listResponse as c, paginateWrapper as d, paginationSchema as f, wrapResponse as g, successResponseSchema as h, getDefaultCrudSchemas as i, messageWrapper as l, responses as m, deleteResponse as n, itemResponse as o, queryParams as p, errorResponseSchema as r, itemWrapper as s, createStateMachine as t, mutationResponse as u, withCompensation as v };

package/dist/versioning-BzfeHmhj.mjs

@@ -0,0 +1,37 @@
+import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
+import fp from "fastify-plugin";
+//#region src/plugins/versioning.ts
+var versioning_exports = /* @__PURE__ */ __exportAll({
+	default: () => versioning_default,
+	versioningPlugin: () => versioningPlugin
+});
+const PREFIX_REGEX = /^\/v(\d+)\//;
+const versioningPlugin = async (fastify, opts) => {
+	const { type, defaultVersion = "1", headerName = "accept-version", responseHeader = "x-api-version", deprecated = [], sunset } = opts;
+	const deprecatedSet = new Set(deprecated);
+	fastify.decorateRequest("apiVersion", defaultVersion);
+	fastify.addHook("onRequest", async (request) => {
+		let version = defaultVersion;
+		if (type === "header") {
+			const headerValue = request.headers[headerName];
+			if (headerValue) version = String(headerValue);
+		} else if (type === "prefix") {
+			const match = request.url.match(PREFIX_REGEX);
+			if (match) version = match[1] ?? defaultVersion;
+		}
+		request.apiVersion = version;
+	});
+	fastify.addHook("onSend", async (request, reply) => {
+		reply.header(responseHeader, request.apiVersion);
+		if (deprecatedSet.has(request.apiVersion)) {
+			reply.header("deprecation", "true");
+			reply.header("sunset", sunset ?? new Date(Date.now() + 2160 * 60 * 60 * 1e3).toISOString());
+		}
+	});
+};
+var versioning_default = fp(versioningPlugin, {
+	name: "arc-versioning",
+	fastify: "5.x"
+});
+//#endregion
+export { versioning_default as n, versioning_exports as r, versioningPlugin as t };