alepha 0.13.0 → 0.13.2

package/dist/core/index.js

@@ -10,7 +10,7 @@ import * as TypeBoxValue from "typebox/value";
 
 //#region src/core/constants/KIND.ts
 /**
-* Used for identifying descriptors.
+* Used for identifying primitives.
 *
 * @internal
 */
@@ -28,7 +28,7 @@ const MODULE = Symbol.for("Alepha.Module");
 //#endregion
 //#region src/core/constants/OPTIONS.ts
 /**
-* Used for descriptors options.
+* Used for primitives options.
 *
 * @internal
 */
@@ -43,98 +43,6 @@ var AlephaError = class extends Error {
 	name = "AlephaError";
 };
 
-//#endregion
-//#region src/core/descriptors/$module.ts
-/**
-* Wrap Services and Descriptors 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 = [], descriptors = [], 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 descriptors) 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/errors/CircularDependencyError.ts
 var CircularDependencyError = class extends AlephaError {
@@ -183,7 +91,7 @@ const __alephaRef = {};
 /**
 * Note:
 *
-* This file is used to share context between $descriptors and the Alepha core during the injection phase.
+* 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).
 *
@@ -222,11 +130,11 @@ const __alephaRef = {};
 */
 
 //#endregion
-//#region src/core/descriptors/$context.ts
+//#region src/core/primitives/$context.ts
 /**
 * Get Alepha instance and current service from the current context.
 *
-* It can only be used inside $descriptor functions.
+* It can only be used inside $primitive functions.
 *
 * ```ts
 * import { $context } from "alepha";
@@ -235,7 +143,7 @@ const __alephaRef = {};
 *   const { alepha, service, module } = $context();
 *
 *   // alepha - alepha instance
-*   // service - class which is creating this descriptor, this is NOT the instance but the service definition
+*   // service - class which is creating this primitive, this is NOT the instance but the service definition
 *   // module - module definition, if any
 *
 *   return {};
@@ -260,8 +168,8 @@ const $context = () => {
 };
 
 //#endregion
-//#region src/core/helpers/descriptor.ts
-var Descriptor = class {
+//#region src/core/helpers/primitive.ts
+var Primitive = class {
 	alepha;
 	options;
 	config;
@@ -275,14 +183,14 @@ var Descriptor = class {
 		};
 	}
 	/**
-	* Called automatically by Alepha after the descriptor is created.
+	* Called automatically by Alepha after the primitive is created.
 	*/
 	onInit() {}
 };
-const createDescriptor = (descriptor, options) => {
+const createPrimitive = (primitive, options) => {
 	const { alepha, service } = $context();
-	if (MODULE in descriptor && descriptor[MODULE]) alepha.with(descriptor[MODULE]);
-	return alepha.inject(descriptor, {
+	if (MODULE in primitive && primitive[MODULE]) alepha.with(primitive[MODULE]);
+	return alepha.inject(primitive, {
 		lifetime: "transient",
 		args: [{
 			options,
@@ -300,6 +208,98 @@ function isClass(func) {
 	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 {
@@ -333,7 +333,7 @@ var AlsProvider = class AlsProvider {
 };
 
 //#endregion
-//#region src/core/descriptors/$inject.ts
+//#region src/core/primitives/$inject.ts
 /**
 * Get the instance of the specified type from the context.
 *
@@ -352,7 +352,7 @@ const $inject = (type, opts = {}) => {
 		...opts
 	});
 };
-var InjectDescriptor = class extends Descriptor {};
+var InjectPrimitive = class extends Primitive {};
 
 //#endregion
 //#region src/core/providers/Json.ts
@@ -620,7 +620,7 @@ var EventManager = class {
 };
 
 //#endregion
-//#region src/core/descriptors/$atom.ts
+//#region src/core/primitives/$atom.ts
 /**
 * Define an atom for state management.
 *
@@ -823,7 +823,7 @@ var StateManager = class {
 * // You can access the environment variables using alepha.env
 * console.log(alepha.env.MY_VAR); // "value"
 *
-* // But you should use $env() descriptor to get typed values from the environment.
+* // But you should use $env() primitive to get typed values from the environment.
 * class App {
 *   env = $env(
 *     t.object({
@@ -836,7 +836,7 @@ var StateManager = class {
 * ### Modules
 *
 * Modules are a way to group services together.
-* You can register a module using the `$module` descriptor.
+* You can register a module using the `$module` primitive.
 *
 * ```ts
 * import { $module } from "alepha";
@@ -854,7 +854,7 @@ var StateManager = class {
 * ### Hooks
 *
 * Hooks are a way to run async functions from all registered providers/services.
-* You can register a hook using the `$hook` descriptor.
+* You can register a hook using the `$hook` primitive.
 *
 * ```ts
 * import { $hook } from "alepha";
@@ -915,7 +915,7 @@ var Alepha = class Alepha {
 			try {
 				onTestFinished?.(() => alepha.stop());
 			} catch (_error) {}
-			alepha.state.set("alepha.test.beforeAll", beforeAll).set("alepha.test.afterAll", afterAll).set("alepha.test.afterEach", afterEach).set("alepha.test.onTestFinished", onTestFinished);
+			alepha.store.set("alepha.test.beforeAll", beforeAll).set("alepha.test.afterAll", afterAll).set("alepha.test.afterEach", afterEach).set("alepha.test.onTestFinished", onTestFinished);
 		}
 		return alepha;
 	}
@@ -969,9 +969,9 @@ var Alepha = class Alepha {
 	*/
 	substitutions = /* @__PURE__ */ new Map();
 	/**
-	* Registry of descriptors.
+	* Registry of primitives.
 	*/
-	descriptorRegistry = /* @__PURE__ */ new Map();
+	primitiveRegistry = /* @__PURE__ */ new Map();
 	/**
 	*  List of all services + how they are provided.
 	*/
@@ -995,7 +995,7 @@ var Alepha = class Alepha {
 	/**
 	* State manager to store arbitrary values.
 	*/
-	get state() {
+	get store() {
 		this.events;
 		return this.inject(StateManager, { args: [this.init] });
 	}
@@ -1011,13 +1011,13 @@ var Alepha = class Alepha {
 	* Get logger instance.
 	*/
 	get log() {
-		return this.state.get("alepha.logger");
+		return this.store.get("alepha.logger");
 	}
 	/**
 	* The environment variables for the App.
 	*/
 	get env() {
-		return this.state.get("env") ?? {};
+		return this.store.get("env") ?? {};
 	}
 	constructor(init = {}) {
 		this.init = init;
@@ -1106,7 +1106,7 @@ var Alepha = class Alepha {
 	* Starts the App.
 	*
 	* - Lock any further changes to the container.
-	* - Run "configure" hook for all services. Descriptors will be processed.
+	* - 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.
 	*
@@ -1126,10 +1126,10 @@ var Alepha = class Alepha {
 		const now = Date.now();
 		this.log?.info("Starting App...");
 		for (const [key] of this.substitutions.entries()) this.inject(key);
-		const target = this.state.get("alepha.target");
+		const target = this.store.get("alepha.target");
 		if (target) {
 			this.registry = /* @__PURE__ */ new Map();
-			this.descriptorRegistry = /* @__PURE__ */ new Map();
+			this.primitiveRegistry = /* @__PURE__ */ new Map();
 			this.with(target);
 		}
 		this.locked = true;
@@ -1323,19 +1323,19 @@ var Alepha = class Alepha {
 		return list;
 	}
 	/**
-	* Get all descriptors of the specified type.
+	* Get all primitives of the specified type.
 	*/
-	descriptors(factory) {
+	primitives(factory) {
 		if (typeof factory === "string") {
 			const key1 = factory.toLowerCase().replace("$", "");
-			const key2 = `${key1}descriptor`;
-			for (const [key, value] of this.descriptorRegistry.entries()) {
+			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.descriptorRegistry.get(factory[KIND]) ?? [];
+		return this.primitiveRegistry.get(factory[KIND]) ?? [];
 	}
 	new(service, args = []) {
 		this.pendingInstantiations.push(service);
@@ -1344,10 +1344,10 @@ var Alepha = class Alepha {
 		const instance = isClass(service) ? new service(...args) : service(...args) ?? {};
 		const obj = instance;
 		for (const [key, value] of Object.entries(obj)) {
-			if (value instanceof Descriptor) this.processDescriptor(value, key);
+			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.state.get(getter) });
+				Object.defineProperty(obj, key, { get: () => this.store.get(getter) });
 			}
 		}
 		this.pendingInstantiations.pop();
@@ -1355,15 +1355,95 @@ var Alepha = class Alepha {
 		__alephaRef.service = this.pendingInstantiations[this.pendingInstantiations.length - 1];
 		return instance;
 	}
-	processDescriptor(value, propertyKey = "") {
+	processPrimitive(value, propertyKey = "") {
 		value.config.propertyKey = propertyKey;
 		value.onInit();
 		const kind = value.constructor;
-		const list = this.descriptorRegistry.get(kind) ?? [];
-		this.descriptorRegistry.set(kind, [...list, value]);
+		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) => {
@@ -1819,7 +1899,7 @@ var TypeProvider = class TypeProvider {
 const t = new TypeProvider();
 
 //#endregion
-//#region src/core/descriptors/$env.ts
+//#region src/core/primitives/$env.ts
 /**
 * Get typed values from environment variables.
 *
@@ -1853,7 +1933,7 @@ const $env = (type) => {
 };
 
 //#endregion
-//#region src/core/descriptors/$hook.ts
+//#region src/core/primitives/$hook.ts
 /**
 * Registers a new hook.
 *
@@ -1893,8 +1973,8 @@ const $env = (type) => {
 * ```
 *
 */
-const $hook = (options) => createDescriptor(HookDescriptor, options);
-var HookDescriptor = class extends Descriptor {
+const $hook = (options) => createPrimitive(HookPrimitive, options);
+var HookPrimitive = class extends Primitive {
 	called = 0;
 	onInit() {
 		this.alepha.events.on(this.options.on, {
@@ -1907,10 +1987,10 @@ var HookDescriptor = class extends Descriptor {
 		});
 	}
 };
-$hook[KIND] = HookDescriptor;
+$hook[KIND] = HookPrimitive;
 
 //#endregion
-//#region src/core/descriptors/$use.ts
+//#region src/core/primitives/$use.ts
 /**
 * Subscribes to an atom's state and returns its current value for use in components.
 *
@@ -1935,94 +2015,14 @@ $hook[KIND] = HookDescriptor;
 */
 const $use = (atom) => {
 	const { alepha } = $context();
-	alepha.state.register(atom);
-	const init = alepha.state.get(atom.key);
+	alepha.store.register(atom);
+	const init = alepha.store.get(atom.key);
 	return {
 		[OPTIONS]: { getter: atom.key },
 		...init
 	};
 };
 
-//#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/schemas/pageQuerySchema.ts
 const pageQuerySchema = t.object({
@@ -2172,5 +2172,5 @@ const withCluster = (entry, opts) => {
 };
 
 //#endregion
-export { $atom, $context, $env, $hook, $inject, $module, $use, Alepha, AlephaError, AlsProvider, AppNotStartedError, Atom, CircularDependencyError, CodecManager, ContainerLockedError, Descriptor, EventManager, HookDescriptor, InjectDescriptor, JsonSchemaCodec, KIND, Module, OPTIONS, SchemaCodec, StateManager, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxFormat, TypeBoxValue, TypeGuard, TypeProvider, createDescriptor, createPagination, isClass, isDate, isDateTime, isDuration, isEmail, isFileLike, isTime, isTypeFile, isURL, isUUID, pageMetadataSchema, pageQuerySchema, pageSchema, run, t };
+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.js.map