alepha 0.13.1 → 0.13.2

package/dist/core/index.native.js

@@ -0,0 +1,2113 @@
+import { Compile } from "typebox/compile";
+import * as TypeBox from "typebox";
+import { Type } from "typebox";
+import TypeBoxFormat from "typebox/format";
+import { Locale } from "typebox/system";
+import * as TypeBoxValue from "typebox/value";
+
+//#region src/core/constants/KIND.ts
+/**
+* Used for identifying primitives.
+*
+* @internal
+*/
+const KIND = Symbol.for("Alepha.Kind");
+
+//#endregion
+//#region src/core/constants/MODULE.ts
+/**
+* Used for identifying modules.
+*
+* @internal
+*/
+const MODULE = Symbol.for("Alepha.Module");
+
+//#endregion
+//#region src/core/constants/OPTIONS.ts
+/**
+* Used for primitives options.
+*
+* @internal
+*/
+const OPTIONS = Symbol.for("Alepha.Options");
+
+//#endregion
+//#region src/core/errors/AlephaError.ts
+/**
+* Default error class for Alepha.
+*/
+var AlephaError = class extends Error {
+	name = "AlephaError";
+};
+
+//#endregion
+//#region src/core/errors/CircularDependencyError.ts
+var CircularDependencyError = class extends AlephaError {
+	name = "CircularDependencyError";
+	constructor(provider, parents) {
+		super(`Instance not available. Looks like a circular dependency. ? -> ${parents?.map((name) => `${name} -> `).join("")}${provider} -> ?`);
+	}
+};
+
+//#endregion
+//#region src/core/errors/ContainerLockedError.ts
+var ContainerLockedError = class extends AlephaError {
+	name = "ContainerLockedError";
+	constructor(message = "Container is locked. No more providers can be added.") {
+		super(message);
+	}
+};
+
+//#endregion
+//#region src/core/errors/TooLateSubstitutionError.ts
+var TooLateSubstitutionError = class extends AlephaError {
+	name = "TooLateSubstitutionError";
+	constructor(original, substitution) {
+		super(`Service already substituted. Please, substitute Service '${original}' with Service '${substitution}' before using it.`);
+	}
+};
+
+//#endregion
+//#region src/core/errors/MissingContextError.ts
+var MissingContextError = class extends AlephaError {
+	name = "MissingContextError";
+	constructor() {
+		super("Missing context. Did you forget to call Alepha.create()?");
+		this.name = "MissingContextError";
+	}
+};
+
+//#endregion
+//#region src/core/helpers/ref.ts
+/**
+* Store the current context and definition during injection phase.
+*
+* @internal
+*/
+const __alephaRef = {};
+/**
+* Note:
+*
+* This file is used to share context between $primitives and the Alepha core during the injection phase.
+*
+* There is no side effect as long as Alepha is not used concurrently in multiple contexts (which is not the case).
+*
+* // __alephaRef === undefined
+* // begin alepha.with()
+* //   __alephaRef.context = alepha
+* //   ... injection phase ...
+* //   __alephaRef.context = undefined
+* // end alepha.with()
+* // __alephaRef === undefined
+*
+* As .with() is synchronous, there is no risk of context leakage.
+*
+* ---------------------------------------------------------------------------------------------------------------------
+*
+* Why this helper?
+*
+* It allows to avoid passing Alepha instance to every $hook, $inject, etc. calls. It's a beautiful syntactic sugar.
+*
+* With sugar:
+*
+* class A {
+*   on = $hook( ... ) // <- __alephaRef is set here
+* }
+*
+* Without sugar:
+*
+* class A {
+*   constructor(alepha: Alepha) {
+*     this.on = $hook(alepha, ... ) // <- no need of __alephaRef
+*   }
+* }
+*
+* One main goal of Alepha is working with classes but without the class verbosity.
+* Forcing to pass Alepha instance in constructors would be a step back in that direction!
+*/
+
+//#endregion
+//#region src/core/primitives/$context.ts
+/**
+* Get Alepha instance and current service from the current context.
+*
+* It can only be used inside $primitive functions.
+*
+* ```ts
+* import { $context } from "alepha";
+*
+* const $hello = () => {
+*   const { alepha, service, module } = $context();
+*
+*   // alepha - alepha instance
+*   // service - class which is creating this primitive, this is NOT the instance but the service definition
+*   // module - module definition, if any
+*
+*   return {};
+* }
+*
+* class MyService {
+*   hello = $hello();
+* }
+*
+* const alepha = new Alepha().with(MyService);
+* ```
+*
+* @internal
+*/
+const $context = () => {
+	if (!__alephaRef.alepha) throw new MissingContextError();
+	return {
+		alepha: __alephaRef.alepha,
+		service: __alephaRef.service,
+		module: __alephaRef.service?.[MODULE]
+	};
+};
+
+//#endregion
+//#region src/core/helpers/primitive.ts
+var Primitive = class {
+	alepha;
+	options;
+	config;
+	constructor(args) {
+		this.alepha = args.alepha;
+		this.options = args.options;
+		this.config = {
+			propertyKey: "",
+			service: args.service,
+			module: args.module
+		};
+	}
+	/**
+	* Called automatically by Alepha after the primitive is created.
+	*/
+	onInit() {}
+};
+const createPrimitive = (primitive, options) => {
+	const { alepha, service } = $context();
+	if (MODULE in primitive && primitive[MODULE]) alepha.with(primitive[MODULE]);
+	return alepha.inject(primitive, {
+		lifetime: "transient",
+		args: [{
+			options,
+			alepha,
+			service: service ?? Alepha
+		}]
+	});
+};
+
+//#endregion
+//#region src/core/interfaces/Service.ts
+function isClass(func) {
+	if (typeof func !== "function") return false;
+	const descriptor = Object.getOwnPropertyDescriptor(func, "prototype");
+	return !!descriptor && !descriptor.writable;
+}
+
+//#endregion
+//#region src/core/primitives/$module.ts
+/**
+* Wrap Services and Primitives into a Module.
+*
+* - A module is just a Service with some extra {@link Module}.
+* - You must attach a `name` to it.
+* - Name must follow the pattern: `project.module.submodule`. (e.g. `myapp.users.auth`).
+*
+* @example
+* ```ts
+* import { $module } from "alepha";
+* import { MyService } from "./MyService.ts";
+*
+* // export MyService, so it can be used everywhere (optional)
+* export * from "./MyService.ts";
+*
+* export default $module({
+*  name: "my.project.module",
+*  // MyService will have a module context "my.project.module"
+*  services: [MyService],
+* });
+* ```
+*
+* ### Why Modules?
+*
+* #### Logging
+*
+* By default, AlephaLogger will log the module name in the logs.
+* This helps to identify where the logs are coming from.
+*
+* You can also set different log levels for different modules.
+* It means you can set 'some.very.specific.module' to 'debug' and keep the rest of the application to 'info'.
+*
+* #### Modulith
+*
+* Force to structure your application in modules, even if it's a single deployable unit.
+* It helps to keep a clean architecture and avoid monolithic applications.
+*
+* A strict mode flag will probably come to enforce module boundaries.
+* -> Throwing errors when a service from another module is injected.
+* But it's not implemented yet.
+*
+* ### When not to use Modules?
+*
+* Small applications does not need modules. It's better to keep it simple.
+* Modules are more useful when the application grows and needs to be structured.
+* If we speak with number of `$actions`, a module should be used when you have more than 30 actions in a single module.
+* Meaning that if you have 100 actions, you should have at least 3 modules.
+*/
+const $module = (options) => {
+	const { services = [], primitives = [], name } = options;
+	if (!name || !Module.NAME_REGEX.test(name)) throw new AlephaError(`Invalid module name '${name}'. It should be in the format of 'project.module.submodule'`);
+	const $ = class extends Module {
+		options = options;
+		register(alepha) {
+			if (typeof options.register === "function") {
+				options.register(alepha);
+				return;
+			}
+			for (const service of services) alepha.inject(service, { parent: this.constructor });
+		}
+	};
+	Object.defineProperty($, "name", {
+		value: name,
+		writable: false
+	});
+	for (const service of services) if (!Module.is(service)) service[MODULE] = $;
+	for (const factory of primitives) if (typeof factory[KIND] === "function") factory[KIND][MODULE] = $;
+	return $;
+};
+/**
+* Base class for all modules.
+*/
+var Module = class Module {
+	static NAME_REGEX = /^[a-z]+(\.[a-z][a-z0-9-]*)*$/;
+	/**
+	* Check if a Service is a Module.
+	*/
+	static is(ctor) {
+		return ctor.prototype instanceof Module;
+	}
+	/**
+	* Get the Module of a Service.
+	*
+	* Returns undefined if the Service is not part of a Module.
+	*/
+	static of(ctor) {
+		return ctor[MODULE];
+	}
+};
+
+//#endregion
+//#region src/core/providers/AlsProvider.ts
+var AlsProvider = class AlsProvider {
+	static create = () => {};
+	als;
+	constructor() {
+		this.als = AlsProvider.create();
+	}
+	createContextId() {
+		return crypto.randomUUID();
+	}
+	run(callback, data = {}) {
+		if (!this.als) return callback();
+		data.registry ??= /* @__PURE__ */ new Map();
+		data.context ??= this.createContextId();
+		return this.als.run(data, callback);
+	}
+	exists() {
+		return !!this.get("context");
+	}
+	get(key) {
+		if (!this.als) return;
+		const store = this.als.getStore();
+		if (store) return store[key];
+	}
+	set(key, value) {
+		if (!this.als) return;
+		const store = this.als.getStore();
+		if (store) store[key] = value;
+	}
+};
+
+//#endregion
+//#region src/core/primitives/$inject.ts
+/**
+* Get the instance of the specified type from the context.
+*
+* ```ts
+* class A { }
+* class B {
+*   a = $inject(A);
+* }
+* ```
+*/
+const $inject = (type, opts = {}) => {
+	const { alepha, service } = $context();
+	if (type === alepha.constructor) return alepha;
+	return alepha.inject(type, {
+		parent: service ?? alepha.constructor,
+		...opts
+	});
+};
+var InjectPrimitive = class extends Primitive {};
+
+//#endregion
+//#region src/core/providers/Json.ts
+/**
+* Mimics the JSON global object with stringify and parse methods.
+*
+* Used across the codebase via dependency injection.
+*/
+var Json = class {
+	stringify(value, replacer, space) {
+		return JSON.stringify(value, replacer, space);
+	}
+	parse(text, reviver) {
+		return JSON.parse(text, reviver);
+	}
+};
+
+//#endregion
+//#region src/core/providers/SchemaCodec.ts
+var SchemaCodec = class {};
+
+//#endregion
+//#region src/core/providers/JsonSchemaCodec.ts
+var JsonSchemaCodec = class extends SchemaCodec {
+	json = $inject(Json);
+	encoder = new TextEncoder();
+	decoder = new TextDecoder();
+	encodeToString(schema, value) {
+		return this.json.stringify(value);
+	}
+	encodeToBinary(schema, value) {
+		return this.encoder.encode(this.encodeToString(schema, value));
+	}
+	decode(schema, value) {
+		if (value instanceof Uint8Array) {
+			const text = this.decoder.decode(value);
+			return this.json.parse(text);
+		}
+		if (typeof value === "string") {
+			const trimmed = value.trim();
+			if (trimmed.startsWith("{") || trimmed.startsWith("[")) return this.json.parse(value);
+			return value;
+		}
+		return value;
+	}
+};
+
+//#endregion
+//#region src/core/errors/TypeBoxError.ts
+var TypeBoxError = class extends AlephaError {
+	name = "TypeBoxError";
+	cause;
+	value;
+	constructor(error) {
+		super(`Invalid input: ${error.message}${error.instancePath ? ` at ${error.instancePath}` : ""}`, { cause: error });
+		const params = error.params;
+		if (params?.requiredProperties) this.value = {
+			path: `/${params.requiredProperties[0]}`,
+			message: "must be defined"
+		};
+		else this.value = {
+			path: error.instancePath,
+			message: error.message
+		};
+		this.cause = error;
+	}
+};
+
+//#endregion
+//#region src/core/providers/SchemaValidator.ts
+var SchemaValidator = class {
+	cache = /* @__PURE__ */ new Map();
+	/**
+	* Validate the value against the provided schema.
+	*
+	* Validation create a new value by applying some preprocessing. (e.g., trimming text)
+	*/
+	validate(schema, value, options = {}) {
+		const newValue = this.beforeParse(schema, value, {
+			trim: options.trim ?? true,
+			nullToUndefined: options.nullToUndefined ?? true,
+			deleteUndefined: options.deleteUndefined ?? true
+		});
+		try {
+			return this.getValidator(schema).Parse(newValue);
+		} catch (error) {
+			if (error.cause?.errors?.[0]) throw new TypeBoxError(error.cause.errors[0]);
+			throw error;
+		}
+	}
+	getValidator(schema) {
+		if (this.cache.has(schema)) return this.cache.get(schema);
+		const validator = Compile(schema);
+		this.cache.set(schema, validator);
+		return validator;
+	}
+	/**
+	* Preprocess the value based on the schema before validation.
+	*
+	* - If the value is `null` and the schema does not allow `null`, it converts it to `undefined`.
+	* - If the value is a string and the schema has a `~options.trim` flag, it trims whitespace from the string.
+	*/
+	beforeParse(schema, value, options) {
+		if (!schema) return value;
+		if (value === null && !this.isSchemaNullable(schema) && options.nullToUndefined) return;
+		if (Array.isArray(value)) return value.map((it) => this.beforeParse(schema.items, it, options));
+		if (typeof value === "string" && schema.type === "string") {
+			let str = value;
+			if (options.trim && schema["~options"]?.trim) str = str.trim();
+			if (schema["~options"]?.lowercase) str = str.toLowerCase();
+			return str;
+		}
+		if (typeof value === "object" && value !== null && schema.type === "object") {
+			const obj = {};
+			for (const key in value) {
+				const newValue = this.beforeParse(schema.properties?.[key], value[key], options);
+				if (newValue === void 0 && options.deleteUndefined) continue;
+				obj[key] = newValue;
+			}
+			return obj;
+		}
+		return value;
+	}
+	/**
+	* Used by `beforeParse` to determine if a schema allows null values.
+	*/
+	isSchemaNullable = (schema) => {
+		if (!schema) return false;
+		if (schema.type === "null") return true;
+		if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+		if (schema.anyOf) return schema.anyOf.some((it) => this.isSchemaNullable(it));
+		if (schema.oneOf) return schema.oneOf.some((it) => this.isSchemaNullable(it));
+		if (schema.allOf) return schema.allOf.some((it) => this.isSchemaNullable(it));
+		return false;
+	};
+};
+
+//#endregion
+//#region src/core/providers/CodecManager.ts
+/**
+* CodecManager manages multiple codec formats and provides a unified interface
+* for encoding and decoding data with different formats.
+*/
+var CodecManager = class {
+	codecs = /* @__PURE__ */ new Map();
+	jsonCodec = $inject(JsonSchemaCodec);
+	schemaValidator = $inject(SchemaValidator);
+	default = "json";
+	constructor() {
+		this.register(this.default, this.jsonCodec);
+	}
+	/**
+	* Register a new codec format.
+	*
+	* @param name - The name of the codec (e.g., 'json', 'protobuf')
+	* @param codec - The codec implementation
+	*/
+	register(name, codec) {
+		this.codecs.set(name, codec);
+	}
+	/**
+	* Get a specific codec by name.
+	*
+	* @param name - The name of the codec
+	* @returns The codec instance
+	* @throws {AlephaError} If the codec is not found
+	*/
+	getCodec(name) {
+		const codec = this.codecs.get(name);
+		if (!codec) throw new AlephaError(`Codec "${name}" not found. Available codecs: ${Array.from(this.codecs.keys()).join(", ")}`);
+		return codec;
+	}
+	/**
+	* Encode data using the specified codec and output format.
+	*/
+	encode(schema, value, options) {
+		const codec = this.getCodec(options?.encoder ?? this.default);
+		const as = options?.as ?? "object";
+		if (options?.validation !== false) value = this.schemaValidator.validate(schema, value, options?.validation);
+		if (as === "object") return value;
+		if (as === "binary") return codec.encodeToBinary(schema, value);
+		return codec.encodeToString(schema, value);
+	}
+	/**
+	* Decode data using the specified codec.
+	*/
+	decode(schema, data, options) {
+		const encoderName = options?.encoder ?? this.default;
+		let value = this.getCodec(encoderName).decode(schema, data);
+		if (options?.validation !== false) value = this.schemaValidator.validate(schema, value, options?.validation);
+		return value;
+	}
+	/**
+	* Validate decoded data against the schema.
+	*
+	* This is automatically called before encoding or after decoding.
+	*/
+	validate(schema, value, options) {
+		return this.schemaValidator.validate(schema, value, options);
+	}
+};
+
+//#endregion
+//#region src/core/providers/EventManager.ts
+var EventManager = class {
+	logFn;
+	/**
+	* List of events that can be triggered. Powered by $hook().
+	*/
+	events = {};
+	constructor(logFn) {
+		this.logFn = logFn;
+	}
+	get log() {
+		return this.logFn?.();
+	}
+	/**
+	* Registers a hook for the specified event.
+	*/
+	on(event, hookOrFunc) {
+		if (!this.events[event]) this.events[event] = [];
+		const hook = typeof hookOrFunc === "function" ? { callback: hookOrFunc } : hookOrFunc;
+		if (hook.priority === "first") this.events[event].unshift(hook);
+		else if (hook.priority === "last") this.events[event].push(hook);
+		else {
+			const index = this.events[event].findIndex((it) => it.priority === "last");
+			if (index !== -1) this.events[event].splice(index, 0, hook);
+			else this.events[event].push(hook);
+		}
+		return () => {
+			this.events[event] = this.events[event].filter((it) => it.callback !== hook.callback);
+		};
+	}
+	/**
+	* Emits the specified event with the given payload.
+	*/
+	async emit(func, payload, options = {}) {
+		const ctx = {};
+		if (options.log) {
+			ctx.now = Date.now();
+			this.log?.trace(`${func} ...`);
+		}
+		let events = this.events[func] ?? [];
+		if (options.reverse) events = events.toReversed();
+		for (const hook of events) {
+			const name = hook.caller?.name ?? "unknown";
+			if (options.log) {
+				ctx.now2 = Date.now();
+				this.log?.trace(`${func}(${name}) ...`);
+			}
+			try {
+				await hook.callback(payload);
+			} catch (error) {
+				if (options.catch) {
+					this.log?.error(`${func}(${name}) ERROR`, error);
+					continue;
+				}
+				if (options.log) throw new AlephaError(`Failed during '${func}()' hook for service: ${name}`, { cause: error });
+				throw error;
+			}
+			if (options.log) this.log?.debug(`${func}(${name}) OK [${Date.now() - ctx.now2}ms]`);
+		}
+		if (options.log) this.log?.debug(`${func} OK [${Date.now() - ctx.now}ms]`);
+	}
+};
+
+//#endregion
+//#region src/core/primitives/$atom.ts
+/**
+* Define an atom for state management.
+*
+* Atom lets you define a piece of state with a name, schema, and default value.
+*
+* By default, Alepha state is just a simple key-value store.
+* Using atoms allows you to have type safety, validation, and default values for your state.
+*
+* You control how state is structured and validated.
+*
+* Features:
+* - Set a schema for validation
+* - Set a default value for initial state
+* - Rules, like read-only, custom validation, etc.
+* - Automatic getter access in services with {@link $use}
+* - SSR support (server state automatically serialized and hydrated on client)
+* - React integration (useAtom hook for automatic component re-renders)
+* - Middleware
+* - Persistence adapters (localStorage, Redis, database, file system, cookie, etc.)
+* - State migrations (version upgrades when schema changes)
+* - Documentation generation & devtools integration
+*
+* Common use cases:
+* - user preferences
+* - feature flags
+* - configuration options
+* - session data
+*
+* Atom must contain only serializable data.
+* Avoid storing complex objects like class instances, functions, or DOM elements.
+* If you need to store complex data, consider using identifiers or references instead.
+*/
+const $atom = (options) => {
+	return new Atom(options);
+};
+var Atom = class {
+	options;
+	get schema() {
+		return this.options.schema;
+	}
+	get key() {
+		return this.options.name;
+	}
+	constructor(options) {
+		this.options = options;
+	}
+};
+$atom[KIND] = "atom";
+
+//#endregion
+//#region src/core/providers/StateManager.ts
+var StateManager = class {
+	als = $inject(AlsProvider);
+	events = $inject(EventManager);
+	codec = $inject(JsonSchemaCodec);
+	atoms = /* @__PURE__ */ new Map();
+	store = {};
+	constructor(store = {}) {
+		this.store = store;
+	}
+	getAtoms(context = true) {
+		const atoms = [];
+		if (context && this.als?.exists()) for (const atom of this.atoms.values()) {
+			const value = this.als.get(atom.key);
+			if (value !== void 0) atoms.push({
+				atom,
+				value
+			});
+		}
+		else for (const [key, atom] of this.atoms.entries()) atoms.push({
+			atom,
+			value: this.store[key]
+		});
+		return atoms;
+	}
+	register(atom) {
+		const key = atom.key;
+		if (!this.atoms.has(key)) {
+			this.atoms.set(key, atom);
+			if (!(key in this.store)) this.set(key, atom.options.default);
+		}
+		return this;
+	}
+	get(target) {
+		if (target instanceof Atom) this.register(target);
+		const key = target instanceof Atom ? target.key : target;
+		const store = this.store;
+		return this.als?.exists() ? this.als.get(key) ?? store[key] : store[key];
+	}
+	set(target, value) {
+		if (target instanceof Atom) this.register(target);
+		const key = target instanceof Atom ? target.key : target;
+		const store = this.store;
+		const prevValue = this.get(key);
+		if (prevValue === value) return this;
+		if (this.als?.exists()) this.als.set(key, value);
+		else store[key] = value;
+		this.events?.emit("state:mutate", {
+			key,
+			value,
+			prevValue
+		}, { catch: true }).catch(() => null);
+		return this;
+	}
+	mut(target, mutator) {
+		const updated = mutator(this.get(target));
+		return this.set(target, updated);
+	}
+	/**
+	* Check if a key exists in the state
+	*/
+	has(key) {
+		return key in this.store;
+	}
+	/**
+	* Delete a key from the state (set to undefined)
+	*/
+	del(key) {
+		return this.set(key, void 0);
+	}
+	/**
+	* Push a value to an array in the state
+	*/
+	push(key, value) {
+		const current = this.get(key) ?? [];
+		if (Array.isArray(current)) this.set(key, [...current, value]);
+		return this;
+	}
+	/**
+	* Clear all state
+	*/
+	clear() {
+		this.store = {};
+		return this;
+	}
+	/**
+	* Get all keys that exist in the state
+	*/
+	keys() {
+		return Object.keys(this.store);
+	}
+};
+
+//#endregion
+//#region src/core/Alepha.ts
+/**
+* Core container of the Alepha framework.
+*
+* It is responsible for managing the lifecycle of services,
+* handling dependency injection,
+* and providing a unified interface for the application.
+*
+* @example
+* ```ts
+* import { Alepha, run } from "alepha";
+*
+* class MyService {
+*   // business logic here
+* }
+*
+* const alepha = Alepha.create({
+*   // state, env, and other properties
+* })
+*
+* alepha.with(MyService);
+*
+* run(alepha); // trigger .start (and .stop) automatically
+* ```
+*
+* ### Alepha Factory
+*
+* Alepha.create() is an enhanced version of new Alepha().
+* - It merges `process.env` with the provided state.env when available.
+* - It populates the test hooks for Vitest or Jest environments when available.
+*
+* new Alepha() is fine if you don't need these helpers.
+*
+* ### Platforms & Environments
+*
+* Alepha is designed to work in various environments:
+* - **Browser**: Runs in the browser, using the global `window` object.
+* - **Serverless**: Runs in serverless environments like Vercel or Vite.
+* - **Test**: Runs in test environments like Jest or Vitest.
+* - **Production**: Runs in production environments, typically with NODE_ENV set to "production".
+* * You can check the current environment using the following methods:
+*
+* - `isBrowser()`: Returns true if the App is running in a browser environment.
+* - `isServerless()`: Returns true if the App is running in a serverless environment.
+* - `isTest()`: Returns true if the App is running in a test environment.
+* - `isProduction()`: Returns true if the App is running in a production environment.
+*
+* ### State & Environment
+*
+* The state of the Alepha container is stored in the `store` property.
+* Most important property is `store.env`, which contains the environment variables.
+*
+* ```ts
+* const alepha = Alepha.create({ env: { MY_VAR: "value" } });
+*
+* // You can access the environment variables using alepha.env
+* console.log(alepha.env.MY_VAR); // "value"
+*
+* // But you should use $env() primitive to get typed values from the environment.
+* class App {
+*   env = $env(
+*     t.object({
+*  	   MY_VAR: t.text(),
+*     })
+*   );
+* }
+* ```
+*
+* ### Modules
+*
+* Modules are a way to group services together.
+* You can register a module using the `$module` primitive.
+*
+* ```ts
+* import { $module } from "alepha";
+*
+* class MyLib {}
+*
+* const myModule = $module({
+*   name: "my.project.module",
+*   services: [MyLib],
+* });
+* ```
+*
+* Do not use modules for small applications.
+*
+* ### Hooks
+*
+* Hooks are a way to run async functions from all registered providers/services.
+* You can register a hook using the `$hook` primitive.
+*
+* ```ts
+* import { $hook } from "alepha";
+*
+* class App {
+* 	 log = $logger();
+* 	 onCustomerHook = $hook({
+* 			on: "my:custom:hook",
+* 			handler: () => {
+* 		 	  this.log?.info("App is being configured");
+* 	 		},
+* 	  });
+* 	}
+*
+* Alepha.create()
+* 	 .with(App)
+* 	 .start()
+* 	 .then(alepha => alepha.events.emit("my:custom:hook"));
+* ```
+*
+* 	Hooks are fully typed. You can create your own hooks by using module augmentation:
+*
+* 	```ts
+* 	declare module "alepha" {
+* 		interface Hooks {
+* 		  "my:custom:hook": {
+* 				arg1: string;
+* 		  }
+* 		}
+* 	}
+* 	```
+*
+* 	@module alepha
+*/
+var Alepha = class Alepha {
+	/**
+	* Creates a new instance of the Alepha container with some helpers:
+	*
+	* - merges `process.env` with the provided state.env when available.
+	* - populates the test hooks for Vitest or Jest environments when available.
+	*
+	* If you are not interested about these helpers, you can use the constructor directly.
+	*/
+	static create(state = {}) {
+		if (typeof process === "object" && typeof process.env === "object") state.env = {
+			...state.env,
+			...process.env
+		};
+		const alepha = new Alepha(state);
+		if (alepha.isTest()) {
+			const g = globalThis;
+			const beforeAll = state["alepha.test.beforeAll"] ?? g.beforeAll;
+			const afterAll = state["alepha.test.afterAll"] ?? g.afterAll;
+			const afterEach = state["alepha.test.afterEach"] ?? g.afterEach;
+			const onTestFinished = state["alepha.test.onTestFinished"] ?? g.onTestFinished;
+			beforeAll?.(() => alepha.start());
+			afterAll?.(() => alepha.stop());
+			try {
+				onTestFinished?.(() => alepha.stop());
+			} catch (_error) {}
+			alepha.store.set("alepha.test.beforeAll", beforeAll).set("alepha.test.afterAll", afterAll).set("alepha.test.afterEach", afterEach).set("alepha.test.onTestFinished", onTestFinished);
+		}
+		return alepha;
+	}
+	/**
+	* Flag indicating whether the App won't accept any further changes.
+	* Pass to true when #start() is called.
+	*/
+	locked = false;
+	/**
+	* True if the App has been configured.
+	*/
+	configured = false;
+	/**
+	* True if the App has started.
+	*/
+	started = false;
+	/**
+	* True if the App is ready.
+	*/
+	ready = false;
+	/**
+	* A promise that resolves when the App has started.
+	*/
+	starting;
+	/**
+	* Initial state of the container.
+	*
+	* > Used to initialize the StateManager.
+	*/
+	init;
+	/**
+	* During the instantiation process, we keep a list of pending instantiations.
+	* > It allows us to detect circular dependencies.
+	*/
+	pendingInstantiations = [];
+	/**
+	* Cache for environment variables.
+	* > It allows us to avoid parsing the same schema multiple times.
+	*/
+	cacheEnv = /* @__PURE__ */ new Map();
+	/**
+	* List of modules that are registered in the container.
+	*
+	* Modules are used to group services and provide a way to register them in the container.
+	*/
+	modules = [];
+	/**
+	* List of service substitutions.
+	*
+	* Services registered here will be replaced by the specified service when injected.
+	*/
+	substitutions = /* @__PURE__ */ new Map();
+	/**
+	* Registry of primitives.
+	*/
+	primitiveRegistry = /* @__PURE__ */ new Map();
+	/**
+	*  List of all services + how they are provided.
+	*/
+	registry = /* @__PURE__ */ new Map();
+	/**
+	* Node.js feature that allows to store context across asynchronous calls.
+	*
+	* This is used for logging, tracing, and other context-related features.
+	*
+	* Mocked for browser environments.
+	*/
+	get context() {
+		return this.inject(AlsProvider);
+	}
+	/**
+	* Event manager to handle lifecycle events and custom events.
+	*/
+	get events() {
+		return this.inject(EventManager, { args: [() => this.log] });
+	}
+	/**
+	* State manager to store arbitrary values.
+	*/
+	get store() {
+		this.events;
+		return this.inject(StateManager, { args: [this.init] });
+	}
+	/**
+	* Codec manager for encoding and decoding data with different formats.
+	*
+	* Supports multiple codec formats (JSON, Protobuf, etc.) with a unified interface.
+	*/
+	get codec() {
+		return this.inject(CodecManager);
+	}
+	/**
+	* Get logger instance.
+	*/
+	get log() {
+		return this.store.get("alepha.logger");
+	}
+	/**
+	* The environment variables for the App.
+	*/
+	get env() {
+		return this.store.get("env") ?? {};
+	}
+	constructor(init = {}) {
+		this.init = init;
+	}
+	/**
+	* True when start() is called.
+	*
+	* -> No more services can be added, it's over, bye!
+	*/
+	isLocked() {
+		return this.locked;
+	}
+	/**
+	* Returns whether the App is configured.
+	*
+	* It means that Alepha#configure() has been called.
+	*
+	* > By default, configure() is called automatically when start() is called, but you can also call it manually.
+	*/
+	isConfigured() {
+		return this.configured;
+	}
+	/**
+	* Returns whether the App has started.
+	*
+	* It means that #start() has been called but maybe not all services are ready.
+	*/
+	isStarted() {
+		return this.started;
+	}
+	/**
+	* True if the App is ready. It means that Alepha is started AND ready() hook has beed called.
+	*/
+	isReady() {
+		return this.ready;
+	}
+	/**
+	* True if the App is running in a Continuous Integration environment.
+	*/
+	isCI() {
+		if (this.env.GITHUB_ACTIONS) return true;
+		return !!this.env.CI;
+	}
+	/**
+	* True if the App is running in a browser environment.
+	*/
+	isBrowser() {
+		return typeof window !== "undefined";
+	}
+	/**
+	* Returns whether the App is running in Vite dev mode.
+	*/
+	isViteDev() {
+		if (this.isBrowser()) return false;
+		return !!this.env.VITE_ALEPHA_DEV;
+	}
+	isBun() {
+		return "Bun" in globalThis;
+	}
+	/**
+	* Returns whether the App is running in a serverless environment.
+	*/
+	isServerless() {
+		if (this.isBrowser()) return false;
+		if (this.env.VERCEL_REGION) return true;
+		if (this.env.ALEPHA_SERVERLESS) return true;
+		return false;
+	}
+	/**
+	* Returns whether the App is in test mode. (Running in a test environment)
+	*
+	* > This is automatically set when running tests with Jest or Vitest.
+	*/
+	isTest() {
+		return this.env.NODE_ENV === "test";
+	}
+	/**
+	* Returns whether the App is in production mode. (Running in a production environment)
+	*
+	* > This is automatically set by Vite or Vercel. However, you have to set it manually when running Docker apps.
+	*/
+	isProduction() {
+		return this.env.NODE_ENV === "production";
+	}
+	/**
+	* Starts the App.
+	*
+	* - Lock any further changes to the container.
+	* - Run "configure" hook for all services. Primitives will be processed.
+	* - Run "start" hook for all services. Providers will connect/listen/...
+	* - Run "ready" hook for all services. This is the point where the App is ready to serve requests.
+	*
+	* @return A promise that resolves when the App has started.
+	*/
+	async start() {
+		if (this.ready) {
+			this.log?.debug("App is already started, skipping...");
+			return this;
+		}
+		if (this.starting) {
+			this.log?.warn("App is already starting, waiting for it to finish...");
+			return this.starting.promise;
+		}
+		this.codec;
+		this.starting = Promise.withResolvers();
+		const now = Date.now();
+		this.log?.info("Starting App...");
+		for (const [key] of this.substitutions.entries()) this.inject(key);
+		const target = this.store.get("alepha.target");
+		if (target) {
+			this.registry = /* @__PURE__ */ new Map();
+			this.primitiveRegistry = /* @__PURE__ */ new Map();
+			this.with(target);
+		}
+		this.locked = true;
+		await this.events.emit("configure", this, { log: true });
+		this.configured = true;
+		await this.events.emit("start", this, { log: true });
+		this.started = true;
+		await this.events.emit("ready", this, { log: true });
+		this.log?.info(`App is now ready [${Date.now() - now}ms]`);
+		this.ready = true;
+		this.starting.resolve(this);
+		this.starting = void 0;
+		return this;
+	}
+	/**
+	* Stops the App.
+	*
+	* - Run "stop" hook for all services.
+	*
+	* Stop will NOT reset the container.
+	* Stop will NOT unlock the container.
+	*
+	* > Stop is used to gracefully shut down the application, nothing more. There is no "restart".
+	*
+	* @return A promise that resolves when the App has stopped.
+	*/
+	async stop() {
+		if (!this.started) return;
+		this.log?.info("Stopping App...");
+		await this.events.emit("stop", this, {
+			reverse: true,
+			log: true
+		});
+		this.log?.info("App is now off");
+		this.started = false;
+		this.ready = false;
+	}
+	/**
+	* Check if entry is registered in the container.
+	*/
+	has(entry, opts = {}) {
+		if (entry === Alepha) return true;
+		const { inStack = true, inRegistry = true, inSubstitutions = true, registry = this.registry } = opts;
+		const { provide } = typeof entry === "object" && "provide" in entry ? entry : { provide: entry };
+		if (inSubstitutions) {
+			if (this.substitutions.get(provide)) return true;
+		}
+		if (inRegistry) {
+			if (registry.get(provide)) return true;
+		}
+		if (inStack) {
+			const substitute = this.substitutions.get(provide)?.use;
+			if (substitute && this.pendingInstantiations.includes(substitute)) return true;
+			return this.pendingInstantiations.includes(provide);
+		}
+		return false;
+	}
+	/**
+	* Registers the specified service in the container.
+	*
+	* - If the service is ALREADY registered, the method does nothing.
+	* - If the service is NOT registered, a new instance is created and registered.
+	*
+	* Method is chainable, so you can register multiple services in a single call.
+	*
+	* > ServiceEntry allows to provide a service **substitution** feature.
+	*
+	* @example
+	* ```ts
+	* class A { value = "a"; }
+	* class B { value = "b"; }
+	* class M { a = $inject(A); }
+	*
+	* Alepha.create().with({ provide: A, use: B }).get(M).a.value; // "b"
+	* ```
+	*
+	* > **Substitution** is an advanced feature that allows you to replace a service with another service.
+	* > It's useful for testing or for providing different implementations of a service.
+	* > If you are interested in configuring a service, use Alepha#configure() instead.
+	*
+	* @param serviceEntry - The service to register in the container.
+	* @return Current instance of Alepha.
+	*/
+	with(serviceEntry) {
+		const entry = "default" in serviceEntry ? serviceEntry.default : serviceEntry;
+		if (this.has(entry, {
+			inSubstitutions: false,
+			inRegistry: false
+		})) return this;
+		if (typeof entry === "object") {
+			if (entry.provide === entry.use) {
+				this.inject(entry.provide);
+				return this;
+			}
+			if (!this.substitutions.has(entry.provide) && !this.has(entry.provide)) {
+				if (this.started) throw new ContainerLockedError();
+				if (MODULE in entry.provide && typeof entry.provide[MODULE] === "function") entry.use[MODULE] ??= entry.provide[MODULE];
+				this.substitutions.set(entry.provide, { use: entry.use });
+			} else if (!entry.optional) throw new TooLateSubstitutionError(entry.provide.name, entry.use.name);
+			return this;
+		}
+		this.inject(entry);
+		return this;
+	}
+	/**
+	* Get an instance of the specified service from the container.
+	*
+	* @see {@link InjectOptions} for the available options.
+	*/
+	inject(service, opts = {}) {
+		const lifetime = opts.lifetime ?? "singleton";
+		const parent = opts.parent !== void 0 ? opts.parent : __alephaRef?.parent ?? Alepha;
+		const transient = lifetime === "transient";
+		const registry = lifetime === "scoped" ? this.context.get("registry") ?? this.registry : this.registry;
+		if (service === Alepha) return this;
+		if (typeof service === "string") {
+			for (const [key, value] of registry.entries()) if (key.name === service) return value.instance;
+			throw new AlephaError(`Service not found: ${service}`);
+		}
+		const substitute = this.substitutions.get(service);
+		if (substitute) return this.inject(substitute.use, {
+			parent,
+			lifetime
+		});
+		const index = this.pendingInstantiations.indexOf(service);
+		if (index !== -1 && !transient) throw new CircularDependencyError(service.name, this.pendingInstantiations.slice(0, index).map((it) => it.name));
+		if (!transient) {
+			const match = registry.get(service);
+			if (match) {
+				if (!match.parents.includes(parent) && parent !== service) match.parents.push(parent);
+				return match.instance;
+			}
+			if (this.started) throw new ContainerLockedError(`Container is locked. No more services can be added. ${parent?.name} -> ${service.name}`);
+		}
+		const module = service[MODULE];
+		if (module && typeof module === "function") this.with(module);
+		if (this.has(service, { registry }) && !transient) return this.inject(service, {
+			parent,
+			lifetime
+		});
+		const instance = this.new(service, opts.args);
+		const definition = {
+			parents: [parent],
+			instance
+		};
+		if (!transient) registry.set(service, definition);
+		if (instance instanceof Module) {
+			this.modules.push(instance);
+			const parent$1 = __alephaRef.parent;
+			__alephaRef.parent = instance.constructor;
+			instance.register(this);
+			__alephaRef.parent = parent$1;
+		}
+		return instance;
+	}
+	/**
+	* Applies environment variables to the provided schema and state object.
+	*
+	* It replaces also all templated $ENV inside string values.
+	*
+	* @param schema - The schema object to apply environment variables to.
+	* @return The schema object with environment variables applied.
+	*/
+	parseEnv(schema) {
+		if (this.cacheEnv.has(schema)) return this.cacheEnv.get(schema);
+		const config = this.codec.validate(schema, this.env);
+		for (const key in config) if (typeof config[key] === "string") for (const env in config) config[key] = config[key].replace(new RegExp(`\\$${env}`, "gim"), config[env]);
+		this.cacheEnv.set(schema, config);
+		return config;
+	}
+	/**
+	* Dump the current dependency graph of the App.
+	*
+	* This method returns a record where the keys are the names of the services.
+	*/
+	graph() {
+		for (const [key] of this.substitutions.entries()) if (!this.has(key)) this.inject(key);
+		const graph = {};
+		for (const [provide, { parents }] of this.registry.entries()) {
+			graph[provide.name] = { from: parents.filter((it) => !!it).map((it) => it.name) };
+			const aliases = this.substitutions.entries().filter((it) => it[1].use === provide).map((it) => it[0].name).toArray();
+			if (aliases.length) graph[provide.name].as = aliases;
+			const module = Module.of(provide);
+			if (module) graph[provide.name].module = module.name;
+		}
+		return graph;
+	}
+	services(base) {
+		const list = [];
+		for (const [key, value] of this.registry.entries()) if (value.instance instanceof base) list.push(value.instance);
+		return list;
+	}
+	/**
+	* Get all primitives of the specified type.
+	*/
+	primitives(factory) {
+		if (typeof factory === "string") {
+			const key1 = factory.toLowerCase().replace("$", "");
+			const key2 = `${key1}primitive`;
+			for (const [key, value] of this.primitiveRegistry.entries()) {
+				const name = key.name.toLowerCase();
+				if (name === key1 || name === key2) return value;
+			}
+			return [];
+		}
+		return this.primitiveRegistry.get(factory[KIND]) ?? [];
+	}
+	new(service, args = []) {
+		this.pendingInstantiations.push(service);
+		__alephaRef.alepha = this;
+		__alephaRef.service = service;
+		const instance = isClass(service) ? new service(...args) : service(...args) ?? {};
+		const obj = instance;
+		for (const [key, value] of Object.entries(obj)) {
+			if (value instanceof Primitive) this.processPrimitive(value, key);
+			if (typeof value === "object" && value !== null && typeof value[OPTIONS] === "object" && "getter" in value[OPTIONS]) {
+				const getter = value[OPTIONS].getter;
+				Object.defineProperty(obj, key, { get: () => this.store.get(getter) });
+			}
+		}
+		this.pendingInstantiations.pop();
+		if (this.pendingInstantiations.length === 0) __alephaRef.alepha = void 0;
+		__alephaRef.service = this.pendingInstantiations[this.pendingInstantiations.length - 1];
+		return instance;
+	}
+	processPrimitive(value, propertyKey = "") {
+		value.config.propertyKey = propertyKey;
+		value.onInit();
+		const kind = value.constructor;
+		const list = this.primitiveRegistry.get(kind) ?? [];
+		this.primitiveRegistry.set(kind, [...list, value]);
+	}
+};
+
+//#endregion
+//#region src/core/errors/AppNotStartedError.ts
+var AppNotStartedError = class extends AlephaError {
+	name = "AppNotStartedError";
+	constructor() {
+		super("App not started. Please start the app before.");
+	}
+};
+
+//#endregion
+//#region src/core/helpers/createPagination.ts
+/**
+* Create a pagination object from an array of entities.
+*
+* This is a pure function that works with any data source (databases, APIs, caches, arrays, etc.).
+* It handles the core pagination logic including:
+* - Slicing the content to the requested page size
+* - Calculating pagination metadata (offset, page number, etc.)
+* - Determining navigation state (isFirst, isLast)
+* - Including sort metadata when provided
+*
+* @param entities - The entities to paginate (should include one extra item to detect if there's a next page)
+* @param limit - The limit of the pagination (page size)
+* @param offset - The offset of the pagination (starting position)
+* @param sort - Optional sort metadata to include in response
+* @returns A complete Page object with content and metadata
+*
+* @example Basic pagination
+* ```ts
+* const users = await fetchUsers({ limit: 11, offset: 0 }); // Fetch limit + 1
+* const page = createPagination(users, 10, 0);
+* // page.content has max 10 items
+* // page.page.isLast tells us if there are more pages
+* ```
+*
+* @example With sorting
+* ```ts
+* const page = createPagination(
+*   entities,
+*   10,
+*   0,
+*   [{ column: "name", direction: "asc" }]
+* );
+* ```
+*
+* @example In a custom service
+* ```ts
+* class MyService {
+*   async listItems(page: number, size: number) {
+*     const items = await this.fetchItems({ limit: size + 1, offset: page * size });
+*     return createPagination(items, size, page * size);
+*   }
+* }
+* ```
+*/
+function createPagination(entities, limit = 10, offset = 0, sort) {
+	const content = entities.slice(0, limit);
+	const hasNext = entities.length === limit + 1;
+	const pageNumber = Math.floor(offset / limit);
+	return {
+		content,
+		page: {
+			number: pageNumber,
+			size: limit,
+			offset,
+			numberOfElements: content.length,
+			isEmpty: content.length === 0,
+			isFirst: pageNumber === 0,
+			isLast: !hasNext,
+			...sort && sort.length > 0 ? { sort: {
+				sorted: true,
+				fields: sort.map((s) => ({
+					field: s.column,
+					direction: s.direction
+				}))
+			} } : {}
+		}
+	};
+}
+
+//#endregion
+//#region src/core/helpers/FileLike.ts
+const isTypeFile = (value) => {
+	return value && typeof value === "object" && "format" in value && value.format === "binary";
+};
+const isFileLike = (value) => {
+	return !!value && typeof value === "object" && !Array.isArray(value) && typeof value.name === "string" && typeof value.type === "string" && typeof value.size === "number" && typeof value.stream.bind(value) === "function";
+};
+
+//#endregion
+//#region src/core/providers/TypeProvider.ts
+const isUUID = TypeBoxFormat.IsUuid;
+const isEmail = TypeBoxFormat.IsEmail;
+const isURL = TypeBoxFormat.IsUrl;
+const isDateTime = TypeBoxFormat.IsDateTime;
+const isDate = TypeBoxFormat.IsDate;
+const isTime = TypeBoxFormat.IsTime;
+const isDuration = TypeBoxFormat.IsDuration;
+var TypeGuard = class {
+	isBigInt = (value) => TypeBox.IsString(value) && "format" in value && value.format === "bigint";
+	isUUID = (value) => TypeBox.IsString(value) && "format" in value && value.format === "uuid";
+	isObject = TypeBox.IsObject;
+	isNumber = TypeBox.IsNumber;
+	isString = TypeBox.IsString;
+	isBoolean = TypeBox.IsBoolean;
+	isAny = TypeBox.IsAny;
+	isArray = TypeBox.IsArray;
+	isOptional = TypeBox.IsOptional;
+	isUnion = TypeBox.IsUnion;
+	isInteger = TypeBox.IsInteger;
+	isNull = TypeBox.IsNull;
+	isUndefined = TypeBox.IsUndefined;
+	isUnsafe = TypeBox.IsUnsafe;
+	isRecord = TypeBox.IsRecord;
+	isTuple = TypeBox.IsTuple;
+	isVoid = TypeBox.IsVoid;
+	isLiteral = TypeBox.IsLiteral;
+	isSchema = TypeBox.IsSchema;
+	isFile = isTypeFile;
+	isDateTime = (schema) => {
+		return t.schema.isString(schema) && schema.format === "date-time";
+	};
+	isDate = (schema) => {
+		return t.schema.isString(schema) && schema.format === "date";
+	};
+	isTime = (schema) => {
+		return t.schema.isString(schema) && schema.format === "time";
+	};
+	isDuration = (schema) => {
+		return t.schema.isString(schema) && schema.format === "duration";
+	};
+};
+var TypeProvider = class TypeProvider {
+	static format = TypeBoxFormat;
+	static {
+		TypeBoxFormat.Set("bigint", (value) => TypeProvider.isValidBigInt(value));
+	}
+	static translateError(error, locale) {
+		if (!locale) return error.cause.message;
+		for (const [key, value] of Object.entries(Locale)) {
+			if (key === "Set" || key === "Get" || key === "Reset") continue;
+			if (key === locale || key.startsWith(`${locale}_`)) return value(error.cause);
+		}
+		return error.cause.message;
+	}
+	static setLocale(locale) {
+		for (const [key, value] of Object.entries(Locale)) {
+			if (key === "Set" || key === "Get" || key === "Reset") continue;
+			if (key === locale || key.startsWith(`${locale}_`)) {
+				Locale.Set(value);
+				return;
+			}
+		}
+		throw new AlephaError(`Locale not found: ${locale}`);
+	}
+	static isValidBigInt(value) {
+		if (typeof value === "number") return Number.isInteger(value);
+		if (!value.trim()) return false;
+		if (!/^-?\d+$/.test(value)) return false;
+		try {
+			BigInt(value);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Default maximum length for strings.
+	*
+	* It can be set to a larger value:
+	* ```ts
+	* TypeProvider.DEFAULT_STRING_MAX_LENGTH = 1000000;
+	* TypeProvider.DEFAULT_STRING_MAX_LENGTH = undefined; // no limit (not recommended)
+	* ```
+	*/
+	static DEFAULT_STRING_MAX_LENGTH = 255;
+	/**
+	* Maximum length for short strings, such as names or titles.
+	*/
+	static DEFAULT_SHORT_STRING_MAX_LENGTH = 64;
+	/**
+	* Maximum length for long strings, such as descriptions or comments.
+	* It can be overridden in the string options.
+	*
+	* It can be set to a larger value:
+	* ```ts
+	* TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH = 2048;
+	* ```
+	*/
+	static DEFAULT_LONG_STRING_MAX_LENGTH = 1024;
+	/**
+	* Maximum length for rich strings, such as HTML or Markdown.
+	* This is a large value to accommodate rich text content.
+	* > It's also the maximum length of PG's TEXT type.
+	*
+	* It can be overridden in the string options.
+	*
+	* It can be set to a larger value:
+	* ```ts
+	* TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH = 1000000;
+	* ```
+	*/
+	static DEFAULT_RICH_STRING_MAX_LENGTH = 65535;
+	/**
+	* Maximum number of items in an array.
+	* This is a default value to prevent excessive memory usage.
+	* It can be overridden in the array options.
+	*/
+	static DEFAULT_ARRAY_MAX_ITEMS = 1e3;
+	raw = Type;
+	any = Type.Any;
+	void = Type.Void;
+	undefined = Type.Undefined;
+	record = Type.Record;
+	union = Type.Union;
+	tuple = Type.Tuple;
+	null = Type.Null;
+	const = Type.Literal;
+	options = Type.Options;
+	/**
+	* Type guards to check the type of schema.
+	* This is not a runtime type check, but a compile-time type guard.
+	*
+	* @example
+	* ```ts
+	* if (t.schema.isString(schema)) {
+	*   // schema is TString
+	* }
+	* ```
+	*/
+	schema = new TypeGuard();
+	extend(schema, properties, options) {
+		return Type.Interface(Array.isArray(schema) ? schema : [schema], properties, {
+			additionalProperties: false,
+			...options
+		});
+	}
+	pick(schema, keys, options) {
+		return Type.Pick(schema, keys, {
+			additionalProperties: false,
+			...options
+		});
+	}
+	omit(schema, keys, options) {
+		return Type.Omit(schema, keys, {
+			additionalProperties: false,
+			...options
+		});
+	}
+	partial(schema, options) {
+		return Type.Partial(schema, {
+			additionalProperties: false,
+			...options
+		});
+	}
+	/**
+	* Create a schema for an object.
+	* By default, additional properties are not allowed.
+	*
+	* @example
+	* ```ts
+	* const userSchema = t.object({
+	*   id: t.integer(),
+	*   name: t.string(),
+	* });
+	* ```
+	*/
+	object(properties, options) {
+		return Type.Object(properties, {
+			additionalProperties: false,
+			...options
+		});
+	}
+	/**
+	* Create a schema for an array.
+	* By default, the maximum number of items is limited to prevent excessive memory usage.
+	*
+	* @see TypeProvider.DEFAULT_ARRAY_MAX_ITEMS
+	*/
+	array(schema, options) {
+		return Type.Array(schema, {
+			maxItems: TypeProvider.DEFAULT_ARRAY_MAX_ITEMS,
+			...options
+		});
+	}
+	/**
+	* Create a schema for a string.
+	* For db or input fields, consider using `t.text()` instead, which has length limits.
+	*
+	* If you need a string with specific format (e.g. email, uuid), consider using the corresponding method (e.g. `t.email()`, `t.uuid()`).
+	*/
+	string(options = {}) {
+		return Type.String({ ...options });
+	}
+	/**
+	* Create a schema for a string with length limits.
+	* For internal strings without length limits, consider using `t.string()` instead.
+	*
+	* Default size is "regular", which has a max length of 255 characters.
+	*/
+	text(options = {}) {
+		const { size, ...rest } = options;
+		const maxLength = size === "short" ? TypeProvider.DEFAULT_SHORT_STRING_MAX_LENGTH : size === "long" ? TypeProvider.DEFAULT_LONG_STRING_MAX_LENGTH : size === "rich" ? TypeProvider.DEFAULT_RICH_STRING_MAX_LENGTH : TypeProvider.DEFAULT_STRING_MAX_LENGTH;
+		return Type.String({
+			maxLength,
+			"~options": {
+				trim: options.trim ?? true,
+				lowercase: options.lowercase ?? false
+			},
+			...rest
+		});
+	}
+	/**
+	* Create a schema for a JSON object.
+	* This is a record with string keys and any values.
+	*/
+	json(options) {
+		return t.record(t.text(), t.any(), options);
+	}
+	/**
+	* Create a schema for a boolean.
+	*/
+	boolean(options) {
+		return Type.Boolean({ ...options });
+	}
+	/**
+	* Create a schema for a number.
+	*/
+	number(options) {
+		return Type.Number({ ...options });
+	}
+	/**
+	* Create a schema for an integer.
+	*/
+	integer(options) {
+		return Type.Integer({ ...options });
+	}
+	int32(options) {
+		return Type.Integer({
+			minimum: -2147483647,
+			maximum: 2147483647,
+			...options
+		});
+	}
+	/**
+	* Mimic a signed 64-bit integer.
+	*
+	* This is NOT a true int64, as JavaScript cannot represent all int64 values.
+	* It is a number that is an integer and between -9007199254740991 and 9007199254740991.
+	* Use `t.bigint()` for true int64 values represented as strings.
+	*/
+	int64(options) {
+		return Type.Number({
+			format: "int64",
+			multipleOf: 1,
+			minimum: -9007199254740991,
+			maximum: 9007199254740991,
+			...options
+		});
+	}
+	/**
+	* Make a schema optional.
+	*/
+	optional(schema) {
+		return Type.Optional(schema);
+	}
+	/**
+	* Make a schema nullable.
+	*/
+	nullable(schema, options) {
+		return Type.Union([Type.Null(), schema], options);
+	}
+	/**
+	* Create a schema that maps all properties of an object schema to nullable.
+	*/
+	nullify = (schema, options) => Type.Mapped(Type.Identifier("K"), Type.KeyOf(schema), Type.Ref("K"), Type.Union([Type.Index(schema, Type.Ref("K")), Type.Null()]), options);
+	/**
+	* Create a schema for a string enum.
+	*/
+	enum(values, options) {
+		return Type.Unsafe(t.text({
+			enum: values,
+			pattern: values.map((v) => `^${v}$`).join("|"),
+			...options
+		}));
+	}
+	/**
+	* Create a schema for a bigint represented as a string.
+	* This is a string that validates bigint format (e.g. "123456789").
+	*/
+	bigint(options) {
+		return t.string({
+			...options,
+			format: "bigint"
+		});
+	}
+	/**
+	* Create a schema for a URL represented as a string.
+	*/
+	url(options) {
+		return this.string({
+			...options,
+			format: "url"
+		});
+	}
+	/**
+	* Create a schema for binary data represented as a base64 string.
+	*/
+	binary(options) {
+		return this.string({
+			...options,
+			format: "binary"
+		});
+	}
+	/**
+	* Create a schema for uuid.
+	*/
+	uuid(options) {
+		return this.string({
+			...options,
+			format: "uuid"
+		});
+	}
+	/**
+	* Create a schema for a file-like object.
+	*
+	* File like mimics the File API in browsers, but is adapted to work in Node.js as well.
+	*
+	* Implementation of file-like objects is handled by "alepha/file" package.
+	*/
+	file(options) {
+		return Type.Unsafe(Type.Any({
+			[OPTIONS]: options,
+			format: "binary"
+		}));
+	}
+	/**
+	* @experimental
+	*/
+	stream() {
+		return Type.Unsafe(Type.Any({
+			format: "stream",
+			type: "string"
+		}));
+	}
+	email(options) {
+		return this.text({
+			...options,
+			format: "email",
+			trim: true,
+			lowercase: true
+		});
+	}
+	e164(options) {
+		return this.text({
+			...options,
+			description: "Phone number in E.164 format, e.g. +1234567890.",
+			pattern: "^\\+[1-9]\\d{1,14}$"
+		});
+	}
+	bcp47(options) {
+		return this.text({
+			...options,
+			description: "BCP 47 language tag, e.g. en, en-US, fr, fr-CA.",
+			pattern: "^[a-z]{2,3}(?:-[A-Z]{2})?$"
+		});
+	}
+	/**
+	* Create a schema for short text, such as names or titles.
+	* Default max length is 64 characters.
+	*/
+	shortText(options) {
+		return this.text({
+			size: "short",
+			...options
+		});
+	}
+	/**
+	* Create a schema for long text, such as descriptions or comments.
+	* Default max length is 1024 characters.
+	*/
+	longText(options) {
+		return this.text({
+			size: "long",
+			...options
+		});
+	}
+	/**
+	* Create a schema for rich text, such as HTML or Markdown.
+	* Default max length is 65535 characters.
+	*/
+	richText(options) {
+		return this.text({
+			size: "rich",
+			...options
+		});
+	}
+	/**
+	* Create a schema for a string enum e.g. LIKE_THIS.
+	*/
+	snakeCase = (options) => this.text({
+		pattern: "^[A-Z_-]+$",
+		...options
+	});
+	/**
+	* Create a schema for an object with a value and label.
+	*/
+	valueLabel = (options) => this.object({
+		value: this.snakeCase({ description: "Machine-readable value." }),
+		label: this.text({ description: "Human-readable label." }),
+		description: this.optional(this.text({
+			description: "Description of the value.",
+			size: "long"
+		}))
+	}, options);
+	datetime = (options) => t.text({
+		...options,
+		format: "date-time"
+	});
+	date = (options) => t.text({
+		...options,
+		format: "date"
+	});
+	time = (options) => t.text({
+		...options,
+		format: "time"
+	});
+	duration = (options) => t.text({
+		...options,
+		format: "duration"
+	});
+};
+const t = new TypeProvider();
+
+//#endregion
+//#region src/core/primitives/$env.ts
+/**
+* Get typed values from environment variables.
+*
+* @example
+* ```ts
+* const alepha = Alepha.create({
+*   env: {
+*     // Alepha.create() will also use process.env when running on Node.js
+*     HELLO: "world",
+*   }
+* });
+*
+* class App {
+*   log = $logger();
+*
+*   // program expect a var env "HELLO" as string to works
+*   env = $env(t.object({
+*     HELLO: t.text()
+*   }));
+*
+*   sayHello = () => this.log.info("Hello ${this.env.HELLO}")
+* }
+*
+* run(alepha.with(App));
+* ```
+*/
+const $env = (type) => {
+	const { alepha } = $context();
+	if (!t.schema.isObject(type)) throw new AlephaError("Type must be an TObject");
+	return alepha.parseEnv(type);
+};
+
+//#endregion
+//#region src/core/primitives/$hook.ts
+/**
+* Registers a new hook.
+*
+* ```ts
+* import { $hook } from "alepha";
+*
+* class MyProvider {
+*   onStart = $hook({
+*     name: "start", // or "configure", "ready", "stop", ...
+*     handler: async (app) => {
+*       // await db.connect(); ...
+*     }
+*   });
+* }
+* ```
+*
+* Hooks are used to run async functions from all registered providers/services.
+*
+* You can't register a hook after the App has started.
+*
+* It's used under the hood by the `configure`, `start`, and `stop` methods.
+* Some modules also use hooks to run their own logic. (e.g. `alepha/server`).
+*
+* You can create your own hooks by using module augmentation:
+*
+* ```ts
+* declare module "alepha" {
+*
+*   interface Hooks {
+*     "my:custom:hook": {
+*       arg1: string;
+*     }
+*   }
+* }
+*
+* await alepha.events.emit("my:custom:hook", { arg1: "value" });
+* ```
+*
+*/
+const $hook = (options) => createPrimitive(HookPrimitive, options);
+var HookPrimitive = class extends Primitive {
+	called = 0;
+	onInit() {
+		this.alepha.events.on(this.options.on, {
+			caller: this.config.service,
+			priority: this.options.priority,
+			callback: async (args) => {
+				this.called += 1;
+				await this.options.handler(args);
+			}
+		});
+	}
+};
+$hook[KIND] = HookPrimitive;
+
+//#endregion
+//#region src/core/primitives/$use.ts
+/**
+* Subscribes to an atom's state and returns its current value for use in components.
+*
+* Creates a reactive connection between an atom and a component, automatically registering
+* the atom in the application state if not already registered. The returned value is reactive
+* and will update when the atom's state changes.
+*
+* **Use Cases**: Accessing global state, sharing data between components, reactive UI updates
+*
+* @example
+* ```ts
+* const userState = $atom({ schema: t.object({ name: t.text(), role: t.text() }) });
+*
+* class UserComponent {
+*   user = $use(userState); // Reactive reference to atom state
+*
+*   render() {
+*     return <div>Hello {this.user.name}!</div>;
+*   }
+* }
+* ```
+*/
+const $use = (atom) => {
+	const { alepha } = $context();
+	alepha.store.register(atom);
+	const init = alepha.store.get(atom.key);
+	return {
+		[OPTIONS]: { getter: atom.key },
+		...init
+	};
+};
+
+//#endregion
+//#region src/core/schemas/pageQuerySchema.ts
+const pageQuerySchema = t.object({
+	page: t.optional(t.integer({
+		description: "The page number to retrieve.",
+		minimum: 0,
+		default: 0
+	})),
+	size: t.optional(t.integer({
+		description: "The number of items per page.",
+		minimum: 1,
+		maximum: 100,
+		default: 10
+	})),
+	sort: t.optional(t.text({ description: "Sort by field(s). Multiple columns separated by comma. Prefix with '-' for DESC. Examples: 'name' (ASC), '-createdAt' (DESC), 'role,-name' (role ASC, name DESC)" }))
+});
+
+//#endregion
+//#region src/core/schemas/pageSchema.ts
+const pageMetadataSchema = t.object({
+	number: t.integer({ description: "Page number, starting from 0" }),
+	size: t.integer({ description: "Number of items per page (requested page size)" }),
+	offset: t.integer({ description: "Offset in the dataset (page × size)" }),
+	numberOfElements: t.integer({ description: "Number of elements in THIS page (content.length). Different from totalElements which is the total across all pages." }),
+	totalElements: t.optional(t.integer({ description: "Total number of elements across all pages. Only available when counting is enabled." })),
+	totalPages: t.optional(t.integer({ description: "Total number of pages. Only available when `totalElements` is present." })),
+	isEmpty: t.boolean({ description: "Indicates if the current page has no items (numberOfElements === 0)" }),
+	isFirst: t.boolean({ description: "Indicates if this is the first page (number === 0)" }),
+	isLast: t.boolean({ description: "Indicates if this is the last page (no more pages after this)" }),
+	sort: t.optional(t.object({
+		sorted: t.boolean({ description: "Whether the results are sorted" }),
+		fields: t.array(t.object({
+			field: t.text({ description: "The field used for sorting" }),
+			direction: t.enum(["asc", "desc"], { description: "The direction of the sort. Either 'asc' or 'desc'" })
+		}))
+	}))
+});
+/**
+* Create a pagination schema for the given object schema.
+*
+* Provides a standardized pagination response format compatible with Spring Data's Page interface.
+* This schema can be used across any data source (databases, APIs, caches, etc.).
+*
+* @example
+* ```ts
+* const userSchema = t.object({ id: t.integer(), name: t.text() });
+* const userPageSchema = pageSchema(userSchema);
+* ```
+*
+* @example In an API endpoint
+* ```ts
+* $action({
+*   output: pageSchema(UserSchema),
+*   handler: async () => {
+*     return await userRepo.paginate();
+*   }
+* })
+* ```
+*/
+const pageSchema = (objectSchema, options) => t.object({
+	content: t.array(objectSchema),
+	page: pageMetadataSchema
+}, options);
+TypeProvider.prototype.page = (itemSchema) => pageSchema(itemSchema);
+
+//#endregion
+//#region src/core/index.native.ts
+if (!Promise.withResolvers) Promise.withResolvers = () => {
+	let resolve;
+	let reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+};
+const run = (entry, opts) => {
+	const alepha = entry instanceof Alepha ? entry : Alepha.create({ env: { ...opts?.env } });
+	if (!(entry instanceof Alepha)) {
+		const entries = Array.isArray(entry) ? entry : [entry];
+		for (const e of entries) alepha.with(e);
+	}
+	return alepha;
+};
+
+//#endregion
+export { $atom, $context, $env, $hook, $inject, $module, $use, Alepha, AlephaError, AlsProvider, AppNotStartedError, Atom, CircularDependencyError, CodecManager, ContainerLockedError, EventManager, HookPrimitive, InjectPrimitive, JsonSchemaCodec, KIND, Module, OPTIONS, Primitive, SchemaCodec, StateManager, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, createPagination, createPrimitive, isClass, isDate, isDateTime, isDuration, isEmail, isFileLike, isTime, isTypeFile, isURL, isUUID, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
+//# sourceMappingURL=index.native.js.map