@xeno-js/shared 2.0.1 → 3.0.0

package/dist/common.types-DT8JtZ0E.d.ts

@@ -0,0 +1,214 @@
+/**
+ * @description Represents a value that may be `null`.
+ * Prefer this over `T | null` in all public APIs so intent is self-documenting.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Nullable<T> = T | null;
+/**
+ * @description Represents a value that may be `undefined`.
+ * Prefer this over `T | undefined` in all public APIs.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Optional<T> = T | undefined;
+/**
+ * @description Represents a value that may be either `null` or `undefined`.
+ * Use when a value is absent regardless of the reason.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Maybe<T> = T | null | undefined;
+/**
+ * @description Represents a concrete (instantiable) class.
+ * Used by IoC containers and auto-wiring utilities to bind concrete implementations.
+ *
+ * @template T  The instance type produced by `new`.
+ * @template TArgs  Constructor parameter tuple; defaults to `any[]`.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Constructor<T, TArgs extends Dictionary[] = Dictionary[]> = new (...args: TArgs) => T;
+/**
+ * @description Represents an abstract class that cannot be instantiated directly.
+ * Used for binding abstract base classes in the IoC container without requiring
+ * a concrete constructor signature.
+ *
+ * @template T  The instance type produced by subclasses.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type AbstractConstructor<T> = abstract new (...args: Dictionary[]) => T;
+/**
+ * @description A plain-object dictionary with string keys and uniform value type.
+ * Prefer over `{ [key: string]: V }` for self-documenting intent.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Dictionary<V = unknown> = Record<string, V>;
+/**
+ * @description Produces a new type with only the keys `K` made required;
+ * all other keys retain their original optionality.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * @description Produces a new type where property `K` is overridden with type `V`.
+ * Useful for narrowing a property inside a generic base type.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Override<T, K extends keyof T, V> = Omit<T, K> & Record<K, V>;
+/**
+ * @description Extracts only the keys of `T` whose values are assignable to `V`.
+ *
+ * @example
+ * type StringKeys = KeysOfType<{ a: string; b: number; c: string }, string>;
+ * // => 'a' | 'c'
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type KeysOfType<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * @description Generic factory function that produces a value of type `T`.
+ *
+ * `TArgs` defaults to an empty tuple for zero-argument factories, enabling
+ * usage both as a plain provider (`Factory<T>`) and as a parameterised
+ * creator (`Factory<T, [config: MyConfig]>`).
+ *
+ * @template T     The type of the value produced.
+ * @template TArgs Tuple of constructor/factory argument types.
+ *
+ * @example
+ * // Zero-argument factory
+ * const makeLogger: Factory<ILoggerService> = () => new ConsoleLogger();
+ *
+ * // Parameterised factory
+ * const makeRepo: Factory<IRepository<Entity>, [tx: Transaction]> =
+ *   (tx) => new DrizzleRepository(tx);
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Factory<T, TArgs extends unknown[] = []> = (...args: TArgs) => T;
+/**
+ * @description Async variant of `Factory<T, TArgs>`.
+ * Use when the construction process involves I/O (e.g. DB pool acquisition).
+ *
+ * @template T     The type of the resolved value.
+ * @template TArgs Tuple of factory argument types.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type AsyncFactory<T, TArgs extends unknown[] = []> = (...args: TArgs) => Promise<T>;
+/**
+ * @description Delegate used by application-layer services to perform lazy,
+ * symbol-keyed dependency resolution without coupling to the concrete container.
+ *
+ * This is the **only** sanctioned way to resolve dependencies at runtime outside
+ * of constructor injection. Never inject the raw IoC container into services.
+ *
+ * @template T  Narrows the return type at each call site.
+ *
+ * @example
+ * class NexusMediator {
+ *   constructor(private readonly resolve: Resolver) {}
+ *
+ *   send<TResult>(command: ICommand): Promise<TResult> {
+ *     const handler = this.resolve<ICommandHandler<typeof command, TResult>>(
+ *       command.resolverToken,
+ *     );
+ *     return handler.execute(command);
+ *   }
+ * }
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Resolver<T = unknown> = (token: symbol) => T;
+/**
+ * @description Async variant of `Resolver` for containers that resolve
+ * dependencies asynchronously (e.g. lazy module loading, remote config).
+ *
+ * @template T  Narrows the resolved type at each call site.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type AsyncResolver = <T>(token: symbol) => Promise<T>;
+/**
+ * @description Represents a globally unique identifier (GUID/UUID) as a string.
+ * The format is typically 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type Guid = `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * @description Represents a function that performs setup or configuration
+ * based on the provided options of type `T`.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+type SetupAction<T, E = undefined> = (options: T, config: E) => void;
+
+export type { AbstractConstructor as A, Constructor as C, Dictionary as D, Factory as F, Guid as G, KeysOfType as K, Maybe as M, Nullable as N, Optional as O, RequireKeys as R, SetupAction as S, AsyncFactory as a, AsyncResolver as b, Override as c, Resolver as d };

package/dist/iauth-service.contracts-DotziBbm.d.ts

@@ -0,0 +1,230 @@
+import { O as Optional, G as Guid, M as Maybe } from './common.types-DT8JtZ0E.js';
+import { R as ResultType } from './result.types-DRyxvpQs.js';
+
+/**
+ * @file auth.types.ts
+ * @description Defines types related to authentication and authorization.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+/**
+ * @description An interface representing the claims associated with an authenticated user. This typically includes standard claims such as 'sub' (subject) and 'email', as well as any additional claims that may be relevant to the application's authorization logic.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface AuthClaims {
+    /**
+     * The unique identifier for the user (subject).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly sub: string;
+    /**
+     * The user's email
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly email: Optional<string>;
+    readonly name: Optional<string>;
+    /**
+     * The tenant ID associated with the user, if applicable. This is useful in multi-tenant applications to identify which tenant the user belongs to.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly tenantId: Optional<string>;
+    /**
+     * An array of roles assigned to the user. This can be used for role-based access control (RBAC) to determine what actions the user is authorized to perform.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly roles: Optional<string[]>;
+    /**
+     * An array of permissions assigned to the user. This can be used for permission-based access control to determine what specific operations the user is authorized to perform.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly permissions: Optional<string[]>;
+}
+/**
+ * @description An interface representing the context of an authenticated user, including their unique identifier and tenant ID. This context can be used throughout the application to enforce authorization rules and access control based on the user's identity and associated claims.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface UserContext {
+    /**
+     * The unique identifier for the user (subject).
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly userId: Optional<Guid>;
+    /**
+     * The tenant ID associated with the user, if applicable. This is useful in multi-tenant applications to identify which tenant the user belongs to.
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly tenantId: Optional<Guid>;
+}
+interface Session {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresAt: Optional<number>;
+    readonly user: AuthClaims;
+}
+type Provider = 'apple' | 'discord' | 'facebook' | 'github' | 'gitlab' | 'google' | 'linkedin' | 'linkedin_oidc' | 'spotify';
+
+/**
+ *  @description Generic mapper interface defining a contract for mapping objects of type TSource to type TDestination. Mappers are used to convert data between different layers of the application, such as transforming DTOs to domain entities or vice versa. This interface defines a contract that all mappers must implement, ensuring consistency and maintainability of the code.
+ *  @template TSource The type of the source object to be mapped.
+ *  @template TDestination The type of the destination object resulting from the mapping.
+ *  @example
+ *  // Example of a UserMapper that maps a UserDTO to a UserEntity
+ *  class UserMapper implements IBaseMapper<UserDTO, UserEntity> {
+ *      map(source: UserDTO): UserEntity {
+ *          // Mapping logic here
+ *      }
+ *  }
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IBaseMapper<TSource, TDestination> {
+    /**
+     * @description Maps an object of type TSource to an object of type TDestination. The implementation of this method should contain the logic for transforming the source object into the desired destination format, which may involve copying properties, converting data types, or applying any necessary transformations to ensure that the resulting object is correctly structured for its intended use.
+     * @param source The source object of type TSource that needs to be mapped to type TDestination. This object contains the data that will be transformed and returned as a new object of the destination type.
+     * @returns An object of type TDestination that is the result of mapping the source object. The returned object should be a new instance that represents the transformed data according to the mapping logic defined in the implementation of this method.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    map(source: TSource): TDestination;
+}
+
+/**
+ * @description IAuthService defines the contract for authentication services.
+ * It provides methods to check if a user is authenticated and to retrieve the user's claims.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface IBaseAuthService {
+    /**
+     * Checks if the user is authenticated.
+     * @returns A promise that resolves to true if the user is authenticated, false otherwise.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Retrieves the user's claims.
+     * @returns A promise that resolves to the user's claims, or null if not authenticated.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getUser(): Promise<ResultType<Maybe<AuthClaims>>>;
+    /**
+     * Authenticates a user based on a token.
+     * @param token The token to authenticate the user.
+     * @returns A promise that resolves to the user's claims, or null if not authenticated.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    authenticate(token: string): Promise<ResultType<AuthClaims>>;
+}
+/**
+ * @description IAuthService defines the contract for authentication services.
+ * It provides methods to check if a user is authenticated and to retrieve the user's claims.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IAuthService {
+    /**
+     * Signs in a user by the specified provider.
+     * @param provider The provider to use for signing in the user.
+     * @returns A promise that resolves to the URL for the specified provider.
+     */
+    signInWithProvider(provider: Provider): Promise<ResultType<{
+        url: string;
+    }>>;
+    /**
+     * @description Gets the current session of the user.
+     * @returns A promise that resolves to the current session of the user.
+     */
+    getSession(): Promise<ResultType<Maybe<Session>>>;
+    /**
+     * @description Signs out the user.
+     * @returns A promise that resolves when the user is signed out.
+     */
+    signOut(): Promise<ResultType<void>>;
+    /**
+     * @description Exchanges the code for a session.
+     * @param code the code to exchange for a session
+     * @returns A promise that resolves to the session wit
+     */
+    exchangeCodeForSession(code: string): Promise<ResultType<Optional<Session>>>;
+}
+/**
+ * @description An extended version of the IAuthService interface that includes additional methods for managing user sessions.
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface IExtendendAuthService extends IBaseAuthService, IAuthService {
+}
+
+export type { AuthClaims as A, IAuthService as I, Provider as P, Session as S, UserContext as U, IBaseAuthService as a, IBaseMapper as b, IExtendendAuthService as c };

package/dist/iauth-service.contracts-DyFYvLdb.d.cts

@@ -0,0 +1,230 @@
+import { O as Optional, G as Guid, M as Maybe } from './common.types-DT8JtZ0E.cjs';
+import { R as ResultType } from './result.types-BNTzjCgR.cjs';
+
+/**
+ * @file auth.types.ts
+ * @description Defines types related to authentication and authorization.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+/**
+ * @description An interface representing the claims associated with an authenticated user. This typically includes standard claims such as 'sub' (subject) and 'email', as well as any additional claims that may be relevant to the application's authorization logic.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface AuthClaims {
+    /**
+     * The unique identifier for the user (subject).
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly sub: string;
+    /**
+     * The user's email
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly email: Optional<string>;
+    readonly name: Optional<string>;
+    /**
+     * The tenant ID associated with the user, if applicable. This is useful in multi-tenant applications to identify which tenant the user belongs to.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly tenantId: Optional<string>;
+    /**
+     * An array of roles assigned to the user. This can be used for role-based access control (RBAC) to determine what actions the user is authorized to perform.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly roles: Optional<string[]>;
+    /**
+     * An array of permissions assigned to the user. This can be used for permission-based access control to determine what specific operations the user is authorized to perform.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly permissions: Optional<string[]>;
+}
+/**
+ * @description An interface representing the context of an authenticated user, including their unique identifier and tenant ID. This context can be used throughout the application to enforce authorization rules and access control based on the user's identity and associated claims.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface UserContext {
+    /**
+     * The unique identifier for the user (subject).
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly userId: Optional<Guid>;
+    /**
+     * The tenant ID associated with the user, if applicable. This is useful in multi-tenant applications to identify which tenant the user belongs to.
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    readonly tenantId: Optional<Guid>;
+}
+interface Session {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresAt: Optional<number>;
+    readonly user: AuthClaims;
+}
+type Provider = 'apple' | 'discord' | 'facebook' | 'github' | 'gitlab' | 'google' | 'linkedin' | 'linkedin_oidc' | 'spotify';
+
+/**
+ *  @description Generic mapper interface defining a contract for mapping objects of type TSource to type TDestination. Mappers are used to convert data between different layers of the application, such as transforming DTOs to domain entities or vice versa. This interface defines a contract that all mappers must implement, ensuring consistency and maintainability of the code.
+ *  @template TSource The type of the source object to be mapped.
+ *  @template TDestination The type of the destination object resulting from the mapping.
+ *  @example
+ *  // Example of a UserMapper that maps a UserDTO to a UserEntity
+ *  class UserMapper implements IBaseMapper<UserDTO, UserEntity> {
+ *      map(source: UserDTO): UserEntity {
+ *          // Mapping logic here
+ *      }
+ *  }
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IBaseMapper<TSource, TDestination> {
+    /**
+     * @description Maps an object of type TSource to an object of type TDestination. The implementation of this method should contain the logic for transforming the source object into the desired destination format, which may involve copying properties, converting data types, or applying any necessary transformations to ensure that the resulting object is correctly structured for its intended use.
+     * @param source The source object of type TSource that needs to be mapped to type TDestination. This object contains the data that will be transformed and returned as a new object of the destination type.
+     * @returns An object of type TDestination that is the result of mapping the source object. The returned object should be a new instance that represents the transformed data according to the mapping logic defined in the implementation of this method.
+    
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    map(source: TSource): TDestination;
+}
+
+/**
+ * @description IAuthService defines the contract for authentication services.
+ * It provides methods to check if a user is authenticated and to retrieve the user's claims.
+ *
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface IBaseAuthService {
+    /**
+     * Checks if the user is authenticated.
+     * @returns A promise that resolves to true if the user is authenticated, false otherwise.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Retrieves the user's claims.
+     * @returns A promise that resolves to the user's claims, or null if not authenticated.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    getUser(): Promise<ResultType<Maybe<AuthClaims>>>;
+    /**
+     * Authenticates a user based on a token.
+     * @param token The token to authenticate the user.
+     * @returns A promise that resolves to the user's claims, or null if not authenticated.
+     *
+     * @author Xeno
+     * @version 1.0.0
+     * @since 2025-09-30
+     * @link https://github.com/xeno-js/xeno-js
+     */
+    authenticate(token: string): Promise<ResultType<AuthClaims>>;
+}
+/**
+ * @description IAuthService defines the contract for authentication services.
+ * It provides methods to check if a user is authenticated and to retrieve the user's claims.
+
+   *
+   * @author Xeno
+   * @version 1.0.0
+   * @since 2025-09-30
+   * @link https://github.com/xeno-js/xeno-js
+   */
+interface IAuthService {
+    /**
+     * Signs in a user by the specified provider.
+     * @param provider The provider to use for signing in the user.
+     * @returns A promise that resolves to the URL for the specified provider.
+     */
+    signInWithProvider(provider: Provider): Promise<ResultType<{
+        url: string;
+    }>>;
+    /**
+     * @description Gets the current session of the user.
+     * @returns A promise that resolves to the current session of the user.
+     */
+    getSession(): Promise<ResultType<Maybe<Session>>>;
+    /**
+     * @description Signs out the user.
+     * @returns A promise that resolves when the user is signed out.
+     */
+    signOut(): Promise<ResultType<void>>;
+    /**
+     * @description Exchanges the code for a session.
+     * @param code the code to exchange for a session
+     * @returns A promise that resolves to the session wit
+     */
+    exchangeCodeForSession(code: string): Promise<ResultType<Optional<Session>>>;
+}
+/**
+ * @description An extended version of the IAuthService interface that includes additional methods for managing user sessions.
+ * @author Xeno
+ * @version 1.0.0
+ * @since 2025-09-30
+ * @link https://github.com/xeno-js/xeno-js
+ */
+interface IExtendendAuthService extends IBaseAuthService, IAuthService {
+}
+
+export type { AuthClaims as A, IAuthService as I, Provider as P, Session as S, UserContext as U, IBaseAuthService as a, IBaseMapper as b, IExtendendAuthService as c };