@fyrestack/database 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -0,0 +1,1229 @@
+
+//#region src/context.ts
+/**
+* Detect if we're running in Node.js environment
+*/
+const isNode = typeof process !== "undefined" && process.versions != null && process.versions.node != null;
+/**
+* Browser shim for AsyncLocalStorage.
+* Note: This implementation has limited support for parallel async operations.
+* In browsers, parallel context isolation may not work correctly.
+* For full isolation, use Node.js with native AsyncLocalStorage.
+*/
+var AsyncLocalStorageShim = class {
+	constructor() {
+		this._store = void 0;
+		this._stack = [];
+	}
+	run(store, callback) {
+		this._stack.push(this._store);
+		this._store = store;
+		try {
+			const result = callback();
+			if (result && typeof result.then === "function") return result.finally(() => {
+				this._store = this._stack.pop();
+			});
+			this._store = this._stack.pop();
+			return result;
+		} catch (error) {
+			this._store = this._stack.pop();
+			throw error;
+		}
+	}
+	getStore() {
+		return this._store;
+	}
+};
+/**
+* Get the AsyncLocalStorage implementation.
+* Uses native AsyncLocalStorage in Node.js, falls back to shim in browsers.
+*/
+function getAsyncLocalStorageClass() {
+	if (isNode) try {
+		const dynamicRequire = eval("typeof require !== \"undefined\" ? require : undefined");
+		if (dynamicRequire) return dynamicRequire("async_hooks").AsyncLocalStorage;
+	} catch {}
+	return AsyncLocalStorageShim;
+}
+/**
+* The async context storage that holds the current operation context.
+* This propagates automatically through async/await chains.
+*/
+const AsyncLocalStorageClass = getAsyncLocalStorageClass();
+const operationContext = new AsyncLocalStorageClass();
+/**
+* Get the current operation context, if any.
+* Returns undefined when not inside a transaction or batch.
+*/
+function getCurrentContext() {
+	return operationContext.getStore();
+}
+/**
+* Check if we're currently inside a transaction.
+*/
+function isInTransaction() {
+	return operationContext.getStore()?.type === "transaction";
+}
+/**
+* Check if we're currently inside a batch.
+*/
+function isInBatch() {
+	return operationContext.getStore()?.type === "batch";
+}
+/**
+* Get the current transaction, if inside one.
+* Returns undefined when not in a transaction.
+*/
+function getCurrentTransaction() {
+	const ctx = operationContext.getStore();
+	return ctx?.type === "transaction" ? ctx.tx : void 0;
+}
+/**
+* Get the current batch, if inside one.
+* Returns undefined when not in a batch.
+*/
+function getCurrentBatch() {
+	const ctx = operationContext.getStore();
+	return ctx?.type === "batch" ? ctx.batch : void 0;
+}
+/**
+* Run a function within a transaction context.
+* @internal Used by runTransaction()
+*/
+function runWithTransaction(tx, fn) {
+	const ctx = {
+		type: "transaction",
+		tx
+	};
+	return operationContext.run(ctx, fn);
+}
+/**
+* Run a function within a batch context.
+* @internal Used by writeBatch()
+*/
+function runWithBatch(batch, fn) {
+	const ctx = {
+		type: "batch",
+		batch
+	};
+	return operationContext.run(ctx, fn);
+}
+/**
+* Type guard for transaction context.
+*/
+function isTransactionContext(ctx) {
+	return ctx?.type === "transaction";
+}
+/**
+* Type guard for batch context.
+*/
+function isBatchContext(ctx) {
+	return ctx?.type === "batch";
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* FyreStack Custom Error Types
+*
+* Provides typed errors for better error handling and debugging.
+*/
+/**
+* Base error class for all FyreStack errors.
+*/
+var FyreStackError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.name = "FyreStackError";
+		this.code = code;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+	}
+};
+/**
+* Error thrown when validation fails.
+*/
+var ValidationError = class ValidationError extends FyreStackError {
+	constructor(message, issues = []) {
+		super(message, "VALIDATION_ERROR");
+		this.name = "ValidationError";
+		this.issues = issues;
+	}
+	/**
+	* Create a ValidationError from Standard Schema validation issues.
+	*/
+	static fromStandardSchema(issues) {
+		const mappedIssues = issues.map((issue) => ({
+			path: issue.path?.map((p) => typeof p === "object" ? String(p.key) : String(p)) ?? [],
+			message: issue.message
+		}));
+		return new ValidationError(mappedIssues.length > 0 && mappedIssues[0] !== void 0 ? mappedIssues.length === 1 ? mappedIssues[0].message : `Validation failed with ${String(mappedIssues.length)} issues` : "Validation failed", mappedIssues);
+	}
+};
+/**
+* Error thrown when path parameters are invalid.
+*/
+var PathParamError = class extends FyreStackError {
+	constructor(paramName, paramValue, reason) {
+		super(`Invalid path parameter "${paramName}": ${reason}`, "PATH_PARAM_ERROR");
+		this.name = "PathParamError";
+		this.paramName = paramName;
+		this.paramValue = paramValue;
+	}
+};
+/**
+* Error thrown when Firestore adapter is not initialized.
+*/
+var AdapterNotInitializedError = class extends FyreStackError {
+	constructor() {
+		super("Firestore adapter not initialized. Call setFirestoreAdapter() before using repositories.", "ADAPTER_NOT_INITIALIZED");
+		this.name = "AdapterNotInitializedError";
+	}
+};
+/**
+* Error thrown when a model is missing required properties.
+*/
+var ModelError = class extends FyreStackError {
+	constructor(message) {
+		super(message, "MODEL_ERROR");
+		this.name = "ModelError";
+	}
+};
+/**
+* Error thrown when a document is not found.
+*/
+var NotFoundError = class extends FyreStackError {
+	constructor(documentPath) {
+		super(`Document not found: ${documentPath}`, "NOT_FOUND");
+		this.name = "NotFoundError";
+		this.documentPath = documentPath;
+	}
+};
+/**
+* Error thrown when a Firestore operation fails.
+*/
+var FirestoreError = class FirestoreError extends FyreStackError {
+	constructor(message, originalError) {
+		super(message, "FIRESTORE_ERROR");
+		this.name = "FirestoreError";
+		this.originalError = originalError;
+	}
+	/**
+	* Wrap a Firestore error with context.
+	*/
+	static wrap(operation, error) {
+		return new FirestoreError(`Firestore ${operation} failed: ${error instanceof Error ? error.message : "Unknown error"}`, error);
+	}
+};
+/**
+* Helper to check if a ValidationResult is valid.
+*/
+function isValidResult(result) {
+	return result.valid;
+}
+
+//#endregion
+//#region src/firestore.types.ts
+/**
+* Abstract Firestore types for dependency injection.
+* Allows switching between firebase-admin and client-side firebase.
+*/
+/**
+* Type guard to check if a value is a ServerTimestampSentinel.
+* Note: This checks the runtime structure, not the brand.
+*/
+function isServerTimestamp(value) {
+	return value !== null && typeof value === "object" && "__type__" in value && value.__type__ === "serverTimestamp";
+}
+/**
+* Global Firestore adapter instance holder
+*/
+let firestoreAdapter = null;
+/**
+* Set the Firestore adapter to use (call once at app initialization)
+*/
+function setFirestoreAdapter(adapter) {
+	firestoreAdapter = adapter;
+}
+/**
+* Get the current Firestore adapter
+* @throws AdapterNotInitializedError if adapter not initialized
+*/
+function getFirestoreAdapter() {
+	if (!firestoreAdapter) throw new AdapterNotInitializedError();
+	return firestoreAdapter;
+}
+/**
+* Reset the Firestore adapter (for testing only)
+* @internal
+*/
+function _resetFirestoreAdapter() {
+	firestoreAdapter = null;
+}
+
+//#endregion
+//#region src/batch.ts
+/**
+* Batch Write Support for FyreStack Database
+*
+* Provides atomic write-only operations across multiple repositories.
+* Context is automatically propagated using AsyncContext.
+*/
+/**
+* Maximum operations per Firestore batch.
+*/
+const MAX_BATCH_SIZE = 500;
+/**
+* Run operations within a write batch.
+*
+* Batches provide:
+* - Atomic writes (all succeed or all fail)
+* - Better performance than individual writes
+* - Up to 500 operations per batch
+* - Works across multiple repositories
+*
+* The batch context is **automatically propagated** to all repository
+* methods called within the batch function - no need to pass context explicitly.
+*
+* Note: Batches are write-only. Use `runTransaction` if you need reads.
+*
+* @example
+* ```typescript
+* // Bulk create users
+* await writeBatch(async () => {
+*   for (const user of users) {
+*     await UserRepo.save({}, user);
+*   }
+* });
+* ```
+*
+* @example
+* ```typescript
+* // Cross-repository batch write
+* await writeBatch(async () => {
+*   await UserRepo.save({}, user);
+*   await ProfileRepo.save({ userId: user.id }, profile);
+*   await AuditRepo.save({}, auditLog);
+* });
+* ```
+*
+* @param fn - Async function to run within the batch
+*/
+async function writeBatch(fn) {
+	const batch = getFirestoreAdapter().batch();
+	await runWithBatch(batch, fn);
+	await batch.commit();
+}
+/**
+* Run operations with automatic batch chunking for large datasets.
+*
+* Automatically commits and creates new batches when exceeding 500 operations.
+* Useful for migrations or bulk imports with thousands of records.
+*
+* The batch context is **automatically propagated** to all repository
+* methods called within the function.
+*
+* @example
+* ```typescript
+* // Process 10,000 records with automatic batching
+* await writeChunkedBatch(async () => {
+*   for (const user of thousandsOfUsers) {
+*     await UserRepo.save({}, user);
+*     // Automatically commits every 500 operations
+*   }
+* });
+* ```
+*
+* @param fn - Function to run with automatic batch chunking
+*/
+async function writeChunkedBatch(fn) {
+	const adapter = getFirestoreAdapter();
+	const state = {
+		batch: adapter.batch(),
+		operationCount: 0
+	};
+	const flushIfNeeded = async () => {
+		if (state.operationCount >= MAX_BATCH_SIZE) {
+			await state.batch.commit();
+			state.batch = adapter.batch();
+			state.operationCount = 0;
+		}
+	};
+	const trackedBatch = {
+		set(docRef, data) {
+			state.batch.set(docRef, data);
+			state.operationCount++;
+			flushIfNeeded();
+			return trackedBatch;
+		},
+		update(docRef, data) {
+			state.batch.update(docRef, data);
+			state.operationCount++;
+			flushIfNeeded();
+			return trackedBatch;
+		},
+		delete(docRef) {
+			state.batch.delete(docRef);
+			state.operationCount++;
+			flushIfNeeded();
+			return trackedBatch;
+		},
+		async commit() {}
+	};
+	await runWithBatch(trackedBatch, fn);
+	if (state.operationCount > 0) await state.batch.commit();
+}
+
+//#endregion
+//#region src/model.hooks.ts
+/**
+* Merge multiple repository hooks into a single hooks object.
+* When multiple hooks define the same method, they are chained in order.
+*/
+function mergeRepositoryHooks(...hooksList) {
+	const filtered = hooksList.filter((h) => h !== void 0);
+	if (filtered.length === 0) return {};
+	if (filtered.length === 1) return filtered[0] ?? {};
+	const result = {};
+	const beforeSave = chainDataHooks(filtered.map((h) => h.beforeSave));
+	if (beforeSave) result.beforeSave = beforeSave;
+	const afterSave = chainVoidHooks(filtered.map((h) => h.afterSave));
+	if (afterSave) result.afterSave = afterSave;
+	const beforeUpdate = chainDataHooks(filtered.map((h) => h.beforeUpdate));
+	if (beforeUpdate) result.beforeUpdate = beforeUpdate;
+	const afterUpdate = chainVoidHooks(filtered.map((h) => h.afterUpdate));
+	if (afterUpdate) result.afterUpdate = afterUpdate;
+	const beforeDelete = chainVoidHooksNoData(filtered.map((h) => h.beforeDelete));
+	if (beforeDelete) result.beforeDelete = beforeDelete;
+	const afterDelete = chainVoidHooksNoData(filtered.map((h) => h.afterDelete));
+	if (afterDelete) result.afterDelete = afterDelete;
+	const afterGet = chainNullableDataHooks(filtered.map((h) => h.afterGet));
+	if (afterGet) result.afterGet = afterGet;
+	const afterFind = chainArrayDataHooks(filtered.map((h) => h.afterFind));
+	if (afterFind) result.afterFind = afterFind;
+	return result;
+}
+/**
+* Merge multiple model hooks into a single hooks object.
+*/
+function mergeModelHooks(...hooksList) {
+	const filtered = hooksList.filter((h) => h !== void 0);
+	if (filtered.length === 0) return {};
+	if (filtered.length === 1) return filtered[0] ?? {};
+	const result = {};
+	const onConstruct = chainModelDataHooks(filtered.map((h) => h.onConstruct));
+	if (onConstruct) result.onConstruct = onConstruct;
+	const onValidate = chainModelVoidHooks(filtered.map((h) => h.onValidate));
+	if (onValidate) result.onValidate = onValidate;
+	return result;
+}
+/**
+* Merge feature hooks (combines both model and repository hooks).
+*/
+function mergeFeatureHooks(...hooksList) {
+	const filtered = hooksList.filter((h) => h !== void 0);
+	if (filtered.length === 0) return {};
+	return {
+		model: mergeModelHooks(...filtered.map((h) => h.model)),
+		repository: mergeRepositoryHooks(...filtered.map((h) => h.repository))
+	};
+}
+function chainDataHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (data, context) => {
+		let result = data;
+		for (const hook of filtered) result = hook(result, context);
+		return result;
+	};
+}
+function chainVoidHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (data, context) => {
+		for (const hook of filtered) hook(data, context);
+	};
+}
+function chainVoidHooksNoData(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (context) => {
+		for (const hook of filtered) hook(context);
+	};
+}
+function chainNullableDataHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (data, context) => {
+		let result = data;
+		for (const hook of filtered) result = hook(result, context);
+		return result;
+	};
+}
+function chainArrayDataHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (data, context) => {
+		let result = data;
+		for (const hook of filtered) result = hook(result, context);
+		return result;
+	};
+}
+function chainModelDataHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (props, context) => {
+		let result = props;
+		for (const hook of filtered) result = hook(result, context);
+		return result;
+	};
+}
+function chainModelVoidHooks(hooks) {
+	const filtered = hooks.filter((h) => h !== void 0);
+	if (filtered.length === 0) return void 0;
+	if (filtered.length === 1) return filtered[0];
+	return (data, context) => {
+		for (const hook of filtered) hook(data, context);
+	};
+}
+
+//#endregion
+//#region src/model.metadata.ts
+/**
+* Symbol used to store metadata on model classes.
+* Using a symbol prevents conflicts with user-defined properties.
+*/
+const MODEL_METADATA = Symbol.for("fyrestack.model.metadata");
+/**
+* Get metadata from a model class.
+*/
+function getModelMetadata(ModelClass) {
+	if (ModelClass !== null && typeof ModelClass === "function" && MODEL_METADATA in ModelClass) return ModelClass[MODEL_METADATA];
+}
+/**
+* Get repository hooks from a model class.
+*/
+function getRepositoryHooks(ModelClass) {
+	return getModelMetadata(ModelClass)?.hooks?.repository;
+}
+/**
+* Get model hooks from a model class.
+*/
+function getModelHooks(ModelClass) {
+	return getModelMetadata(ModelClass)?.hooks?.model;
+}
+/**
+* Check if a model has any repository hooks registered.
+*/
+function hasRepositoryHooks(ModelClass) {
+	const hooks = getRepositoryHooks(ModelClass);
+	return hooks !== void 0 && Object.keys(hooks).length > 0;
+}
+/**
+* Check if a model has a specific feature registered.
+*/
+function hasFeature(ModelClass, featureName) {
+	return getModelMetadata(ModelClass)?.features?.[featureName] !== void 0;
+}
+/**
+* Get configuration for a specific feature.
+*/
+function getFeatureConfig(ModelClass, featureName) {
+	return getModelMetadata(ModelClass)?.features?.[featureName];
+}
+/**
+* Create metadata for a feature.
+* Used by feature functions like withTimestamps() to build metadata.
+*
+* @param featureName - Unique name for the feature
+* @param config - Feature-specific configuration (for introspection)
+* @param hooks - Hooks to register
+* @param existingMetadata - Existing metadata to merge with
+*/
+function createFeatureMetadata(featureName, config, hooks, existingMetadata) {
+	return {
+		hooks: mergeFeatureHooks(existingMetadata?.hooks, hooks),
+		features: {
+			...existingMetadata?.features,
+			[featureName]: config
+		}
+	};
+}
+/**
+* Default timestamp configuration.
+*/
+const DEFAULT_TIMESTAMPS = {
+	createdAt: "createdAt",
+	updatedAt: "updatedAt",
+	useServerTimestamp: true
+};
+/**
+* Default audit configuration.
+*/
+const DEFAULT_AUDIT = {
+	createdBy: "createdBy",
+	updatedBy: "updatedBy"
+};
+/**
+* Default status configuration.
+*/
+const DEFAULT_STATUS = {
+	field: "status",
+	values: [
+		"active",
+		"inactive",
+		"deleted"
+	],
+	defaultValue: "active",
+	deletedValue: "deleted",
+	deletedAt: "deletedAt"
+};
+/**
+* Check if a model has timestamps feature.
+*/
+function hasTimestamps(ModelClass) {
+	return hasFeature(ModelClass, "timestamps");
+}
+/**
+* Get timestamps configuration from a model class.
+*/
+function getTimestampsConfig(ModelClass) {
+	return getFeatureConfig(ModelClass, "timestamps");
+}
+/**
+* Check if a model has audit feature.
+*/
+function hasAudit(ModelClass) {
+	return hasFeature(ModelClass, "audit");
+}
+/**
+* Get audit configuration from a model class.
+*/
+function getAuditConfig(ModelClass) {
+	return getFeatureConfig(ModelClass, "audit");
+}
+/**
+* Check if a model has status feature.
+*/
+function hasStatus(ModelClass) {
+	return hasFeature(ModelClass, "status");
+}
+/**
+* Get status configuration from a model class.
+*/
+function getStatusConfig(ModelClass) {
+	return getFeatureConfig(ModelClass, "status");
+}
+
+//#endregion
+//#region src/model.types.ts
+/**
+* Symbol for storing the schema on model instances (internal use).
+*/
+const MODEL_SCHEMA = Symbol.for("fyrestack.model.schema");
+
+//#endregion
+//#region src/model.ts
+function model(...features) {
+	const innerStore = features.reduce((store, feature) => feature(store), getInitialInnerStore());
+	const modelSchema = innerStore.schema;
+	const modelMethods = innerStore.methods;
+	class Model {
+		constructor(data) {
+			this[MODEL_SCHEMA] = modelSchema;
+			let validatedProps = {};
+			if (data !== void 0 && data !== null) if ("~standard" in modelSchema) {
+				const result = modelSchema["~standard"].validate(data);
+				if ("issues" in result && result.issues) throw toValidationError(result.issues);
+				if ("value" in result) validatedProps = result.value;
+			} else validatedProps = data;
+			for (const [key, value] of Object.entries(validatedProps)) this[key] = value;
+			for (const [key, method] of Object.entries(modelMethods)) this[key] = method;
+		}
+		/**
+		* Validate the current model data against the schema.
+		* @returns ValidationResult with validated value or error
+		*/
+		validate() {
+			const schema = this[MODEL_SCHEMA];
+			const data = this.toObject();
+			if (!("~standard" in schema)) return {
+				valid: true,
+				value: data
+			};
+			const result = schema["~standard"].validate(data);
+			if ("issues" in result && result.issues) return {
+				valid: false,
+				error: toValidationError(result.issues)
+			};
+			if ("value" in result) return {
+				valid: true,
+				value: result.value
+			};
+			return {
+				valid: true,
+				value: data
+			};
+		}
+		/**
+		* Check if the current model data is valid.
+		* @returns true if valid, false otherwise
+		*/
+		isValid() {
+			return this.validate().valid;
+		}
+		/**
+		* Convert model instance to a plain object (excludes methods).
+		* Used for Firestore writes and serialization.
+		*/
+		toObject() {
+			const result = {};
+			for (const key of Object.keys(this)) {
+				const value = this[key];
+				if (typeof value !== "function") result[key] = value;
+			}
+			return result;
+		}
+	}
+	const metadata = innerStore._metadata;
+	if (metadata) Model[MODEL_METADATA] = metadata;
+	return Model;
+}
+function getInitialInnerStore() {
+	return {
+		schema: {},
+		props: {},
+		methods: {}
+	};
+}
+/**
+* Convert Standard Schema issues to ValidationIssues.
+* Handles various path formats from different schema libraries.
+*/
+function toValidationError(issues) {
+	const mappedIssues = issues.map((issue) => {
+		let path = [];
+		if (Array.isArray(issue.path)) path = issue.path.map((p) => {
+			if (typeof p === "string" || typeof p === "number" || typeof p === "symbol") return String(p);
+			if (p !== null && typeof p === "object" && "key" in p) return String(p.key);
+			return String(p);
+		});
+		return {
+			path,
+			message: issue.message
+		};
+	});
+	return new ValidationError(mappedIssues.length > 0 && mappedIssues[0] !== void 0 ? mappedIssues.length === 1 ? mappedIssues[0].message : `Validation failed with ${String(mappedIssues.length)} issues` : "Validation failed", mappedIssues);
+}
+
+//#endregion
+//#region src/model.with-schema.ts
+function withSchema(schema) {
+	return (store) => ({
+		schema,
+		props: {},
+		methods: store.methods
+	});
+}
+
+//#endregion
+//#region src/model.with-timestamps.ts
+/**
+* Create repository hooks for timestamp management.
+* This is the core implementation extracted into hooks.
+*/
+function createTimestampsHooks(config) {
+	return {
+		beforeSave(data, context) {
+			const timestamp = config.useServerTimestamp ? context.adapter.serverTimestamp() : /* @__PURE__ */ new Date();
+			if (config.createdAt !== false && (data[config.createdAt] === void 0 || data[config.createdAt] === null)) data[config.createdAt] = timestamp;
+			if (config.updatedAt !== false) data[config.updatedAt] = timestamp;
+			return data;
+		},
+		beforeUpdate(updates, context) {
+			if (config.updatedAt !== false) {
+				const timestamp = config.useServerTimestamp ? context.adapter.serverTimestamp() : /* @__PURE__ */ new Date();
+				updates[config.updatedAt] = timestamp;
+			}
+			return updates;
+		}
+	};
+}
+/**
+* Add automatic timestamp management to a model.
+*
+* This feature registers hooks that:
+* - Set `createdAt` on save (if not already set)
+* - Set `updatedAt` on save and update
+*
+* @example
+* ```typescript
+* // Basic usage with defaults (createdAt, updatedAt)
+* const UserModel = model(
+*   withSchema(UserSchema),
+*   withTimestamps(),
+* );
+*
+* // Custom field names
+* const PostModel = model(
+*   withSchema(PostSchema),
+*   withTimestamps({ createdAt: 'publishedAt', updatedAt: 'modifiedAt' }),
+* );
+*
+* // Disable one field
+* const LogModel = model(
+*   withSchema(LogSchema),
+*   withTimestamps({ updatedAt: false }), // Only track creation
+* );
+*
+* // Use client-side timestamps (for offline support)
+* const OfflineModel = model(
+*   withSchema(OfflineSchema),
+*   withTimestamps({ useServerTimestamp: false }),
+* );
+* ```
+*
+* @param options - Optional configuration for field names and behavior
+*/
+function withTimestamps(options) {
+	const config = {
+		createdAt: options?.createdAt ?? DEFAULT_TIMESTAMPS.createdAt,
+		updatedAt: options?.updatedAt ?? DEFAULT_TIMESTAMPS.updatedAt,
+		useServerTimestamp: options?.useServerTimestamp ?? DEFAULT_TIMESTAMPS.useServerTimestamp
+	};
+	const hooks = createTimestampsHooks(config);
+	return (store) => {
+		const newMetadata = createFeatureMetadata("timestamps", config, { repository: hooks }, store._metadata);
+		return {
+			schema: store.schema,
+			props: store.props,
+			methods: store.methods,
+			_metadata: newMetadata
+		};
+	};
+}
+
+//#endregion
+//#region src/repository.helpers.ts
+/**
+* Composable Repository Implementation for Firestore
+*/
+function createTypedQueryBuilder(queryRef) {
+	return {
+		where(field, op, value) {
+			return createTypedQueryBuilder(queryRef.where(field, op, value));
+		},
+		orderBy(field, direction) {
+			return createTypedQueryBuilder(queryRef.orderBy(field, direction));
+		},
+		limit(count) {
+			return createTypedQueryBuilder(queryRef.limit(count));
+		},
+		startAt(...values) {
+			return createTypedQueryBuilder(queryRef.startAt(...values));
+		},
+		startAfter(...values) {
+			return createTypedQueryBuilder(queryRef.startAfter(...values));
+		},
+		endAt(...values) {
+			return createTypedQueryBuilder(queryRef.endAt(...values));
+		},
+		endBefore(...values) {
+			return createTypedQueryBuilder(queryRef.endBefore(...values));
+		},
+		_queryRef: queryRef
+	};
+}
+function getQueryRef(builder) {
+	return builder._queryRef;
+}
+/**
+* Regex for valid path parameter values.
+* Allows alphanumeric characters, underscores, and hyphens.
+*/
+const VALID_PATH_PARAM_REGEX = /^[a-zA-Z0-9_-]+$/;
+/**
+* Validate a single path parameter value.
+* @throws PathParamError if the value is invalid
+*/
+function validatePathParam(paramName, value) {
+	if (!value || value.length === 0) throw new PathParamError(paramName, value, "cannot be empty");
+	if (value.includes("/")) throw new PathParamError(paramName, value, "cannot contain forward slashes");
+	if (value.includes("..")) throw new PathParamError(paramName, value, "cannot contain path traversal (..)");
+	if (value.includes("\0")) throw new PathParamError(paramName, value, "cannot contain null bytes");
+	if (!VALID_PATH_PARAM_REGEX.test(value)) throw new PathParamError(paramName, value, "must only contain alphanumeric characters, underscores, or hyphens");
+}
+/**
+* Build a collection path from template and params.
+* Validates all path parameters before building.
+* @throws PathParamError if any parameter is invalid
+*/
+function buildCollectionPath(pathTemplate, params) {
+	let result = pathTemplate;
+	for (const [key, value] of Object.entries(params)) {
+		validatePathParam(key, value);
+		result = result.replace(`{${key}}`, value);
+	}
+	return result;
+}
+/**
+* Extract model ID from model instance or string.
+* @throws ModelError if the model doesn't have a valid ID
+*/
+function extractId(modelOrId) {
+	if (typeof modelOrId === "string") {
+		if (!modelOrId) throw new ModelError("Document ID cannot be empty");
+		return modelOrId;
+	}
+	if (modelOrId !== null && typeof modelOrId === "object" && "id" in modelOrId && typeof modelOrId.id === "string") {
+		if (!modelOrId.id) throw new ModelError("Model ID cannot be empty");
+		return modelOrId.id;
+	}
+	throw new ModelError("Model must have a string \"id\" property");
+}
+/**
+* Type guard to check if a model has a validate() method.
+*/
+function isValidatable(model$1) {
+	return "validate" in model$1 && typeof model$1.validate === "function";
+}
+/**
+* Type guard to check if a model has a toObject() method.
+*/
+function hasToObject(model$1) {
+	return "toObject" in model$1 && typeof model$1.toObject === "function";
+}
+/**
+* Validate a model instance before write operations.
+* @throws ValidationError if validation fails
+*/
+function validateModel(model$1) {
+	if (model$1 === null || typeof model$1 !== "object") throw new ValidationError("Model must be an object");
+	if (isValidatable(model$1)) {
+		const result = model$1.validate();
+		if (!result.valid && result.error) throw result.error;
+	}
+}
+/**
+* Convert model to plain object for Firestore.
+* Uses toObject() if available, otherwise spreads the object.
+*/
+function modelToObject(model$1) {
+	if (model$1 !== null && typeof model$1 === "object") {
+		if (hasToObject(model$1)) return model$1.toObject();
+		const result = {};
+		for (const [key, value] of Object.entries(model$1)) if (typeof value !== "function") result[key] = value;
+		return result;
+	}
+	throw new ModelError("Model must be an object");
+}
+
+//#endregion
+//#region src/repository.ts
+function repository(config, ...features) {
+	const { path, model: ModelClass } = config;
+	const hooks = getRepositoryHooks(ModelClass);
+	class Repository {
+		getFirestore() {
+			return getFirestoreAdapter();
+		}
+		getCollectionRef(params) {
+			const collectionPath = buildCollectionPath(path, params);
+			return this.getFirestore().collection(collectionPath);
+		}
+		getDocumentRef(params, id) {
+			return this.getCollectionRef(params).doc(id);
+		}
+		/**
+		* Create hook context for repository hooks.
+		*/
+		createHookContext(params, id) {
+			const context = {
+				adapter: this.getFirestore(),
+				modelClass: ModelClass,
+				path,
+				params
+			};
+			if (id !== void 0) context.id = id;
+			return context;
+		}
+		async get(params, id) {
+			try {
+				const docRef = this.getDocumentRef(params, id);
+				const ctx = getCurrentContext();
+				const tx = isTransactionContext(ctx) ? ctx.tx : void 0;
+				const snapshot = tx ? await tx.get(docRef) : await docRef.get();
+				if (!snapshot.exists) return null;
+				const data = snapshot.data();
+				if (!data) return null;
+				let result = new ModelClass({
+					...data,
+					id: snapshot.id
+				});
+				if (hooks?.afterGet) {
+					const context = this.createHookContext(params, id);
+					result = hooks.afterGet(result, context);
+				}
+				return result;
+			} catch (error) {
+				if (error instanceof PathParamError || error instanceof ValidationError) throw error;
+				throw FirestoreError.wrap("get", error);
+			}
+		}
+		async find(params, queryFn) {
+			try {
+				const collectionRef = this.getCollectionRef(params);
+				let queryRef = collectionRef;
+				if (queryFn) queryRef = getQueryRef(queryFn(createTypedQueryBuilder(collectionRef)));
+				let results = (await queryRef.get()).docs.map((doc) => {
+					return new ModelClass({
+						...doc.data(),
+						id: doc.id
+					});
+				});
+				if (hooks?.afterFind) {
+					const context = this.createHookContext(params);
+					results = hooks.afterFind(results, context);
+				}
+				return results;
+			} catch (error) {
+				if (error instanceof PathParamError || error instanceof ValidationError) throw error;
+				throw FirestoreError.wrap("find", error);
+			}
+		}
+		async save(params, model$1) {
+			try {
+				validateModel(model$1);
+				const id = extractId(model$1);
+				const docRef = this.getDocumentRef(params, id);
+				let data = modelToObject(model$1);
+				if (hooks?.beforeSave) {
+					const context = this.createHookContext(params, id);
+					data = hooks.beforeSave(data, context);
+				}
+				const ctx = getCurrentContext();
+				if (isTransactionContext(ctx)) ctx.tx.set(docRef, data);
+				else if (isBatchContext(ctx)) ctx.batch.set(docRef, data);
+				else await docRef.set(data);
+				if (hooks?.afterSave) {
+					const context = this.createHookContext(params, id);
+					hooks.afterSave(data, context);
+				}
+			} catch (error) {
+				if (error instanceof PathParamError || error instanceof ValidationError || error instanceof ModelError) throw error;
+				throw FirestoreError.wrap("save", error);
+			}
+		}
+		async update(params, modelOrId, updates) {
+			try {
+				const id = extractId(modelOrId);
+				const docRef = this.getDocumentRef(params, id);
+				let updateData = { ...updates };
+				if (hooks?.beforeUpdate) {
+					const context = this.createHookContext(params, id);
+					updateData = hooks.beforeUpdate(updateData, context);
+				}
+				const ctx = getCurrentContext();
+				if (isTransactionContext(ctx)) ctx.tx.update(docRef, updateData);
+				else if (isBatchContext(ctx)) ctx.batch.update(docRef, updateData);
+				else await docRef.update(updateData);
+				if (hooks?.afterUpdate) {
+					const context = this.createHookContext(params, id);
+					hooks.afterUpdate(updateData, context);
+				}
+			} catch (error) {
+				if (error instanceof PathParamError || error instanceof ModelError) throw error;
+				throw FirestoreError.wrap("update", error);
+			}
+		}
+		async delete(params, modelOrId) {
+			try {
+				const id = extractId(modelOrId);
+				const docRef = this.getDocumentRef(params, id);
+				if (hooks?.beforeDelete) {
+					const context = this.createHookContext(params, id);
+					hooks.beforeDelete(context);
+				}
+				const ctx = getCurrentContext();
+				if (isTransactionContext(ctx)) ctx.tx.delete(docRef);
+				else if (isBatchContext(ctx)) ctx.batch.delete(docRef);
+				else await docRef.delete();
+				if (hooks?.afterDelete) {
+					const context = this.createHookContext(params, id);
+					hooks.afterDelete(context);
+				}
+			} catch (error) {
+				if (error instanceof PathParamError || error instanceof ModelError) throw error;
+				throw FirestoreError.wrap("delete", error);
+			}
+		}
+	}
+	if (features.length > 0) {
+		const repoInstance = new Repository();
+		const innerRepo = {
+			model: ModelClass,
+			path,
+			methods: {
+				get: repoInstance.get.bind(repoInstance),
+				find: repoInstance.find.bind(repoInstance),
+				save: repoInstance.save.bind(repoInstance),
+				update: repoInstance.update.bind(repoInstance),
+				delete: repoInstance.delete.bind(repoInstance)
+			},
+			getCollection: repoInstance["getCollectionRef"].bind(repoInstance),
+			getDocument: repoInstance["getDocumentRef"].bind(repoInstance)
+		};
+		let currentMethods = innerRepo.methods;
+		for (const feature of features) currentMethods = feature({
+			...innerRepo,
+			methods: currentMethods
+		});
+		const FinalRepository = class extends Repository {
+			constructor() {
+				super();
+				for (const [key, method] of Object.entries(currentMethods)) if (!(key in this)) this[key] = method;
+			}
+		};
+		return FinalRepository;
+	}
+	return Repository;
+}
+
+//#endregion
+//#region src/repository.with-methods.ts
+/**
+* Add custom methods to a repository
+*/
+function withMethods(methodsFactory) {
+	return (repo) => {
+		const newMethods = methodsFactory(repo);
+		return {
+			...repo.methods,
+			...newMethods
+		};
+	};
+}
+
+//#endregion
+//#region src/transaction.ts
+/**
+* Transaction Support for FyreStack Database
+*
+* Provides atomic read-write operations across multiple repositories.
+* Context is automatically propagated using AsyncContext.
+*/
+/**
+* Run operations within a Firestore transaction.
+*
+* Transactions provide:
+* - Atomic reads and writes across multiple repositories
+* - Automatic retry on contention (up to maxAttempts)
+* - Consistent view of data (all reads see same snapshot)
+* - All-or-nothing semantics (all writes succeed or all fail)
+*
+* The transaction context is **automatically propagated** to all repository
+* methods called within the transaction function - no need to pass context explicitly.
+*
+* @example
+* ```typescript
+* // Transfer funds between accounts atomically
+* const result = await runTransaction(async () => {
+*   const fromAccount = await AccountRepo.get({}, fromId);
+*   const toAccount = await AccountRepo.get({}, toId);
+*
+*   if (!fromAccount || !toAccount) throw new Error('Account not found');
+*   if (fromAccount.balance < amount) throw new Error('Insufficient funds');
+*
+*   await AccountRepo.update({}, fromId, {
+*     balance: fromAccount.balance - amount
+*   });
+*
+*   await AccountRepo.update({}, toId, {
+*     balance: toAccount.balance + amount
+*   });
+*
+*   return { newBalance: fromAccount.balance - amount };
+* });
+* ```
+*
+* @example
+* ```typescript
+* // Cross-repository transaction
+* await runTransaction(async () => {
+*   const order = await OrderRepo.get({}, orderId);
+*   const user = await UserRepo.get({}, order.userId);
+*
+*   await OrderRepo.update({}, orderId, { status: 'paid' });
+*   await UserRepo.update({}, user.id, {
+*     balance: user.balance - order.total
+*   });
+* });
+* ```
+*
+* @param fn - Async function to run within the transaction
+* @param options - Transaction options (maxAttempts, etc.)
+* @returns Result of the transaction function
+*/
+async function runTransaction(fn, options) {
+	return getFirestoreAdapter().runTransaction(async (tx) => {
+		return runWithTransaction(tx, fn);
+	}, options);
+}
+
+//#endregion
+exports.AdapterNotInitializedError = AdapterNotInitializedError;
+exports.DEFAULT_AUDIT = DEFAULT_AUDIT;
+exports.DEFAULT_STATUS = DEFAULT_STATUS;
+exports.DEFAULT_TIMESTAMPS = DEFAULT_TIMESTAMPS;
+exports.FirestoreError = FirestoreError;
+exports.FyreStackError = FyreStackError;
+exports.MAX_BATCH_SIZE = MAX_BATCH_SIZE;
+exports.MODEL_METADATA = MODEL_METADATA;
+exports.MODEL_SCHEMA = MODEL_SCHEMA;
+exports.ModelError = ModelError;
+exports.NotFoundError = NotFoundError;
+exports.PathParamError = PathParamError;
+exports.ValidationError = ValidationError;
+exports._resetFirestoreAdapter = _resetFirestoreAdapter;
+exports.createFeatureMetadata = createFeatureMetadata;
+exports.getAuditConfig = getAuditConfig;
+exports.getCurrentBatch = getCurrentBatch;
+exports.getCurrentContext = getCurrentContext;
+exports.getCurrentTransaction = getCurrentTransaction;
+exports.getFeatureConfig = getFeatureConfig;
+exports.getFirestoreAdapter = getFirestoreAdapter;
+exports.getModelHooks = getModelHooks;
+exports.getModelMetadata = getModelMetadata;
+exports.getRepositoryHooks = getRepositoryHooks;
+exports.getStatusConfig = getStatusConfig;
+exports.getTimestampsConfig = getTimestampsConfig;
+exports.hasAudit = hasAudit;
+exports.hasFeature = hasFeature;
+exports.hasRepositoryHooks = hasRepositoryHooks;
+exports.hasStatus = hasStatus;
+exports.hasTimestamps = hasTimestamps;
+exports.isBatchContext = isBatchContext;
+exports.isInBatch = isInBatch;
+exports.isInTransaction = isInTransaction;
+exports.isServerTimestamp = isServerTimestamp;
+exports.isTransactionContext = isTransactionContext;
+exports.isValidResult = isValidResult;
+exports.mergeFeatureHooks = mergeFeatureHooks;
+exports.mergeModelHooks = mergeModelHooks;
+exports.mergeRepositoryHooks = mergeRepositoryHooks;
+exports.model = model;
+exports.repository = repository;
+exports.runTransaction = runTransaction;
+exports.runWithBatch = runWithBatch;
+exports.runWithTransaction = runWithTransaction;
+exports.setFirestoreAdapter = setFirestoreAdapter;
+exports.withMethods = withMethods;
+exports.withSchema = withSchema;
+exports.withTimestamps = withTimestamps;
+exports.writeBatch = writeBatch;
+exports.writeChunkedBatch = writeChunkedBatch;