@geekmidas/services 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -1,193 +1,4 @@
-//#region src/index.ts
-/**
-* Service discovery container that manages service registration and retrieval.
-* Implements a singleton pattern with lazy initialization of services.
-*
-* @template TServices - Record type mapping service names to their instance types
-* @template TLogger - Logger type for internal logging
-*
-* @example
-* ```typescript
-* // Define service types
-* interface MyServices {
-*   database: Database;
-*   cache: CacheService;
-*   auth: AuthService;
-* }
-*
-* // Get service discovery instance
-* const discovery = ServiceDiscovery.getInstance<MyServices>(logger, envParser);
-*
-* // Register services
-* await discovery.register([
-*   new DatabaseService(),
-*   new CacheService(),
-*   new AuthService()
-* ]);
-*
-* // Retrieve services
-* const db = await discovery.get('database');
-* const { cache, auth } = await discovery.getMany(['cache', 'auth']);
-* ```
-*/
-var ServiceDiscovery = class ServiceDiscovery {
-	/** Singleton instance of ServiceDiscovery */
-	static _instance;
-	/** Map of registered service definitions */
-	services = /* @__PURE__ */ new Map();
-	/** Map of instantiated service instances */
-	instances = /* @__PURE__ */ new Map();
-	/**
-	* Gets the singleton instance of ServiceDiscovery.
-	* Creates a new instance if one doesn't exist.
-	*
-	* @template T - Record type mapping service names to their instance types
-	* @template TLogger - Logger type for internal logging
-	* @param logger - Logger instance for service logging
-	* @param envParser - Environment parser for service configuration
-	* @returns The ServiceDiscovery singleton instance
-	*
-	* @example
-	* ```typescript
-	* const services = ServiceDiscovery.getInstance<MyServices>(logger, envParser);
-	* ```
-	*/
-	static getInstance(logger, envParser) {
-		if (!ServiceDiscovery._instance) ServiceDiscovery._instance = new ServiceDiscovery(logger, envParser);
-		return ServiceDiscovery._instance;
-	}
-	/**
-	* Resets the singleton instance. Use only for testing purposes.
-	* This clears all cached services and allows a fresh instance to be created.
-	*
-	* @example
-	* ```typescript
-	* // In test teardown
-	* afterEach(() => {
-	*   ServiceDiscovery.reset();
-	* });
-	* ```
-	*/
-	static reset() {
-		ServiceDiscovery._instance = void 0;
-	}
-	/**
-	* Private constructor to enforce singleton pattern.
-	*
-	* @param logger - Logger instance for service logging
-	* @param envParser - Environment parser for service configuration
-	* @private
-	*/
-	constructor(logger, envParser) {
-		this.logger = logger;
-		this.envParser = envParser;
-	}
-	/**
-	* Register multiple services with the service discovery.
-	* Services are instantiated lazily on first access.
-	* Already instantiated services are returned from cache.
-	*
-	* @template T - Array type of services to register
-	* @param services - Array of services to register
-	* @returns Promise resolving to a record of service names to instances
-	*
-	* @example
-	* ```typescript
-	* const services = await discovery.register([
-	*   new DatabaseService(),
-	*   new CacheService(),
-	*   new AuthService()
-	* ]);
-	*
-	* // services = {
-	* //   database: Database instance,
-	* //   cache: CacheService instance,
-	* //   auth: AuthService instance
-	* // }
-	* ```
-	*/
-	async register(services) {
-		const registeredServices = {};
-		for (const service of services) {
-			const name = service.serviceName;
-			if (this.instances.has(name)) {
-				registeredServices[name] = this.instances.get(name);
-				continue;
-			}
-			const instance = await service.register(this.envParser);
-			this.instances.set(name, instance);
-			registeredServices[name] = instance;
-		}
-		return registeredServices;
-	}
-	/**
-	* Get a service from the service discovery.
-	* Services are instantiated on first access if not already cached.
-	*
-	* @template K - The service name key
-	* @param name - The name of the service to get
-	* @returns Promise resolving to the service instance
-	* @throws {Error} If the service is not registered
-	*
-	* @example
-	* ```typescript
-	* const database = await discovery.get('database');
-	* const users = await database.query('SELECT * FROM users');
-	* ```
-	*/
-	get(name) {
-		const service = this.services.get(name);
-		if (!service) throw new Error(`Service '${name}' not found in service discovery`);
-		return service.register(this.envParser);
-	}
-	/**
-	* Get multiple services from the service discovery.
-	* Useful for retrieving multiple dependencies at once.
-	*
-	* @template K - Array of service name keys
-	* @param names - Array of service names to retrieve
-	* @returns Promise resolving to an object containing the service instances
-	*
-	* @example
-	* ```typescript
-	* const { database, cache, auth } = await discovery.getMany([
-	*   'database',
-	*   'cache',
-	*   'auth'
-	* ]);
-	* ```
-	*/
-	async getMany(names) {
-		const result = {};
-		for (const name of names) result[name] = await this.get(name);
-		return result;
-	}
-	/**
-	* Check if a service exists in the service discovery.
-	* Can check by service name or service instance.
-	*
-	* @param service - The service name or service instance to check
-	* @returns True if the service exists, false otherwise
-	*
-	* @example
-	* ```typescript
-	* if (discovery.has('database')) {
-	*   const db = await discovery.get('database');
-	* }
-	*
-	* // Or check with service instance
-	* const dbService = new DatabaseService();
-	* if (!discovery.has(dbService)) {
-	*   await discovery.register([dbService]);
-	* }
-	* ```
-	*/
-	has(service) {
-		if (typeof service === "string") return this.services.has(service);
-		return this.services.has(service.serviceName);
-	}
-};
+import { runWithRequestContext, serviceContext } from "./context-B5YTspJR.mjs";
+import { ServiceDiscovery } from "./ServiceDiscovery-DLMyH_yM.mjs";
 
-//#endregion
-export { ServiceDiscovery };
-//# sourceMappingURL=index.mjs.map
+export { ServiceDiscovery, runWithRequestContext, serviceContext };

package/dist/types-CcHmCx_U.d.mts

@@ -0,0 +1,86 @@
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Logger } from "@geekmidas/logger";
+
+//#region src/types.d.ts
+
+/**
+ * Request context available to services.
+ * Methods are guaranteed to return values when called within a request context.
+ * Throws if called outside a request context (catches bugs early).
+ */
+interface ServiceContext {
+  /**
+   * Get the current request's logger.
+   * @throws Error if called outside a request context
+   */
+  getLogger(): Logger;
+  /**
+   * Get the current request ID.
+   * @throws Error if called outside a request context
+   */
+  getRequestId(): string;
+  /**
+   * Get the current request's start time (from Date.now()).
+   * Useful for calculating request duration.
+   * @throws Error if called outside a request context
+   */
+  getRequestStartTime(): number;
+  /**
+   * Check if currently running inside a request context.
+   * Use this to guard calls if you need to handle both cases.
+   */
+  hasContext(): boolean;
+}
+/**
+ * Options passed to service register method.
+ */
+interface ServiceRegisterOptions {
+  /** Environment parser for configuration */
+  envParser: EnvironmentParser<{}>;
+  /** Request context for logging and tracing */
+  context: ServiceContext;
+}
+/**
+ * Service interface for the simplified service pattern.
+ * Services are objects with a serviceName and register method.
+ *
+ * @template TName - The literal string type for the service name
+ * @template TInstance - The type of the service instance that will be registered
+ *
+ * @example
+ * ```typescript
+ * const databaseService = {
+ *   serviceName: 'database' as const,
+ *   register({ envParser, context }: ServiceRegisterOptions) {
+ *     const config = envParser.create((get) => ({
+ *       url: get('DATABASE_URL').string()
+ *     })).parse();
+ *
+ *     return {
+ *       async query(sql: string) {
+ *         const logger = context.getLogger();
+ *         logger.debug({ sql }, 'Executing query');
+ *         // ... execute query
+ *       }
+ *     };
+ *   }
+ * } satisfies Service<'database', DatabaseInstance>;
+ * ```
+ */
+interface Service<TName extends string = string, TInstance = unknown> {
+  /**
+   * Unique name for the service, used for lookup via services.get()
+   */
+  serviceName: TName;
+  /**
+   * Register method that returns the actual service instance.
+   * Called once on first access, then cached.
+   *
+   * @param options - Registration options including envParser and context
+   */
+  register(options: ServiceRegisterOptions): TInstance | Promise<TInstance>;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+export { Service, ServiceContext, ServiceRegisterOptions };
+//# sourceMappingURL=types-CcHmCx_U.d.mts.map

package/dist/types-CcHmCx_U.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CcHmCx_U.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AA8BA;;AAEY,UAhCK,cAAA,CAgCL;EAAiB;AAEL;AA8BxB;;EAAwB,SAIV,EAAA,EA/DA,MA+DA;EAAK;;;;EAO4C,YAAA,EAAA,EAAA,MAAA;;;;;;;;;;;;;;;;UA7C9C,sBAAA;;aAEL;;WAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BO;;;;eAIH;;;;;;;oBAOK,yBAAyB,YAAY,QAAQ"}

package/dist/types-D7d_yeU5.d.cts

@@ -0,0 +1,86 @@
+import { EnvironmentParser } from "@geekmidas/envkit";
+import { Logger } from "@geekmidas/logger";
+
+//#region src/types.d.ts
+
+/**
+ * Request context available to services.
+ * Methods are guaranteed to return values when called within a request context.
+ * Throws if called outside a request context (catches bugs early).
+ */
+interface ServiceContext {
+  /**
+   * Get the current request's logger.
+   * @throws Error if called outside a request context
+   */
+  getLogger(): Logger;
+  /**
+   * Get the current request ID.
+   * @throws Error if called outside a request context
+   */
+  getRequestId(): string;
+  /**
+   * Get the current request's start time (from Date.now()).
+   * Useful for calculating request duration.
+   * @throws Error if called outside a request context
+   */
+  getRequestStartTime(): number;
+  /**
+   * Check if currently running inside a request context.
+   * Use this to guard calls if you need to handle both cases.
+   */
+  hasContext(): boolean;
+}
+/**
+ * Options passed to service register method.
+ */
+interface ServiceRegisterOptions {
+  /** Environment parser for configuration */
+  envParser: EnvironmentParser<{}>;
+  /** Request context for logging and tracing */
+  context: ServiceContext;
+}
+/**
+ * Service interface for the simplified service pattern.
+ * Services are objects with a serviceName and register method.
+ *
+ * @template TName - The literal string type for the service name
+ * @template TInstance - The type of the service instance that will be registered
+ *
+ * @example
+ * ```typescript
+ * const databaseService = {
+ *   serviceName: 'database' as const,
+ *   register({ envParser, context }: ServiceRegisterOptions) {
+ *     const config = envParser.create((get) => ({
+ *       url: get('DATABASE_URL').string()
+ *     })).parse();
+ *
+ *     return {
+ *       async query(sql: string) {
+ *         const logger = context.getLogger();
+ *         logger.debug({ sql }, 'Executing query');
+ *         // ... execute query
+ *       }
+ *     };
+ *   }
+ * } satisfies Service<'database', DatabaseInstance>;
+ * ```
+ */
+interface Service<TName extends string = string, TInstance = unknown> {
+  /**
+   * Unique name for the service, used for lookup via services.get()
+   */
+  serviceName: TName;
+  /**
+   * Register method that returns the actual service instance.
+   * Called once on first access, then cached.
+   *
+   * @param options - Registration options including envParser and context
+   */
+  register(options: ServiceRegisterOptions): TInstance | Promise<TInstance>;
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+export { Service, ServiceContext, ServiceRegisterOptions };
+//# sourceMappingURL=types-D7d_yeU5.d.cts.map

package/dist/types-D7d_yeU5.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-D7d_yeU5.d.cts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;;;;AAQA;AA8BA;;AAEY,UAhCK,cAAA,CAgCL;EAAiB;AAEL;AA8BxB;;EAAwB,SAIV,EAAA,EA/DA,MA+DA;EAAK;;;;EAO4C,YAAA,EAAA,EAAA,MAAA;;;;;;;;;;;;;;;;UA7C9C,sBAAA;;aAEL;;WAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA8BO;;;;eAIH;;;;;;;oBAOK,yBAAyB,YAAY,QAAQ"}

package/dist/types.d.cts

@@ -0,0 +1,2 @@
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-D7d_yeU5.cjs";
+export { Service, ServiceContext, ServiceRegisterOptions };

package/dist/types.d.mts

@@ -0,0 +1,2 @@
+import { Service, ServiceContext, ServiceRegisterOptions } from "./types-CcHmCx_U.mjs";
+export { Service, ServiceContext, ServiceRegisterOptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/services",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -8,6 +8,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "import": "./dist/context.mjs",
+      "require": "./dist/context.cjs"
     }
   },
   "repository": {
@@ -20,8 +25,8 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "@geekmidas/envkit": "^0.2.0",
-    "@geekmidas/logger": "^0.3.0"
+    "@geekmidas/logger": "^0.4.0",
+    "@geekmidas/envkit": "^0.3.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/envkit": {
@@ -32,8 +37,8 @@
     }
   },
   "devDependencies": {
-    "@geekmidas/envkit": "^0.2.0",
-    "@geekmidas/logger": "^0.3.0"
+    "@geekmidas/envkit": "^0.3.0",
+    "@geekmidas/logger": "^0.4.0"
   },
   "scripts": {
     "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"

package/src/ServiceDiscovery.ts

@@ -0,0 +1,254 @@
+import type { EnvironmentParser } from '@geekmidas/envkit';
+import { serviceContext } from './context';
+import type { Service } from './types';
+
+/**
+ * Service discovery container that manages service registration and retrieval.
+ * Implements a singleton pattern with lazy initialization of services.
+ *
+ * @template TServices - Record type mapping service names to their instance types
+ *
+ * @example
+ * ```typescript
+ * // Define service types
+ * interface MyServices {
+ *   database: Database;
+ *   cache: CacheService;
+ *   auth: AuthService;
+ * }
+ *
+ * // Get service discovery instance
+ * const discovery = ServiceDiscovery.getInstance<MyServices>(envParser);
+ *
+ * // Register services
+ * await discovery.register([
+ *   databaseService,
+ *   cacheService,
+ *   authService
+ * ]);
+ *
+ * // Retrieve services
+ * const db = await discovery.get('database');
+ * const { cache, auth } = await discovery.getMany(['cache', 'auth']);
+ * ```
+ */
+export class ServiceDiscovery<TServices extends Record<string, unknown> = {}> {
+	/** Singleton instance of ServiceDiscovery */
+	private static _instance: ServiceDiscovery<any>;
+	/** Map of registered service definitions */
+	private services = new Map<string, Service>();
+	/** Map of instantiated service instances */
+	private instances = new Map<keyof TServices, TServices[keyof TServices]>();
+
+	/**
+	 * Gets the singleton instance of ServiceDiscovery.
+	 * Creates a new instance if one doesn't exist.
+	 *
+	 * @template T - Record type mapping service names to their instance types
+	 * @param envParser - Environment parser for service configuration
+	 * @returns The ServiceDiscovery singleton instance
+	 *
+	 * @example
+	 * ```typescript
+	 * const services = ServiceDiscovery.getInstance<MyServices>(envParser);
+	 * ```
+	 */
+	static getInstance<T extends Record<any, unknown> = any>(
+		envParser: EnvironmentParser<{}>,
+	): ServiceDiscovery<T> {
+		if (!ServiceDiscovery._instance) {
+			ServiceDiscovery._instance = new ServiceDiscovery<T>(envParser);
+		}
+		return ServiceDiscovery._instance as ServiceDiscovery<T>;
+	}
+
+	/**
+	 * Resets the singleton instance. Use only for testing purposes.
+	 * This clears all cached services and allows a fresh instance to be created.
+	 *
+	 * @example
+	 * ```typescript
+	 * // In test teardown
+	 * afterEach(() => {
+	 *   ServiceDiscovery.reset();
+	 * });
+	 * ```
+	 */
+	static reset(): void {
+		ServiceDiscovery._instance = undefined as any;
+	}
+
+	/**
+	 * Private constructor to enforce singleton pattern.
+	 *
+	 * @param envParser - Environment parser for service configuration
+	 * @private
+	 */
+	private constructor(readonly envParser: EnvironmentParser<{}>) {}
+
+	/**
+	 * Register multiple services with the service discovery.
+	 * Services are instantiated lazily on first access.
+	 * Already instantiated services are returned from cache.
+	 *
+	 * @template T - Array type of services to register
+	 * @param services - Array of services to register
+	 * @returns Promise resolving to a record of service names to instances
+	 *
+	 * @example
+	 * ```typescript
+	 * const services = await discovery.register([
+	 *   databaseService,
+	 *   cacheService,
+	 *   authService
+	 * ]);
+	 *
+	 * // services = {
+	 * //   database: Database instance,
+	 * //   cache: CacheService instance,
+	 * //   auth: AuthService instance
+	 * // }
+	 * ```
+	 */
+	async register<T extends Service[]>(services: T): Promise<ServiceRecord<T>> {
+		const registeredServices = {} as ServiceRecord<T>;
+		for (const service of services) {
+			const name = service.serviceName as T[number]['serviceName'];
+			if (this.instances.has(name)) {
+				(registeredServices as any)[name] = this.instances.get(
+					name,
+				) as TServices[keyof TServices];
+				continue;
+			}
+
+			// Pass both envParser and context to service
+			const instance = await service.register({
+				envParser: this.envParser,
+				context: serviceContext,
+			});
+
+			this.instances.set(name, instance as TServices[keyof TServices]);
+			(registeredServices as any)[name] =
+				instance as TServices[keyof TServices];
+		}
+
+		return registeredServices;
+	}
+
+	/**
+	 * Get a service from the service discovery.
+	 * Services are instantiated on first access if not already cached.
+	 *
+	 * @template K - The service name key
+	 * @param name - The name of the service to get
+	 * @returns Promise resolving to the service instance
+	 * @throws {Error} If the service is not registered
+	 *
+	 * @example
+	 * ```typescript
+	 * const database = await discovery.get('database');
+	 * const users = await database.query('SELECT * FROM users');
+	 * ```
+	 */
+	get<K extends keyof TServices & string>(name: K): Promise<TServices[K]> {
+		const service = this.services.get(name);
+
+		if (!service) {
+			throw new Error(`Service '${name}' not found in service discovery`);
+		}
+
+		return service.register({
+			envParser: this.envParser,
+			context: serviceContext,
+		}) as Promise<TServices[K]>;
+	}
+	/**
+	 * Get multiple services from the service discovery.
+	 * Useful for retrieving multiple dependencies at once.
+	 *
+	 * @template K - Array of service name keys
+	 * @param names - Array of service names to retrieve
+	 * @returns Promise resolving to an object containing the service instances
+	 *
+	 * @example
+	 * ```typescript
+	 * const { database, cache, auth } = await discovery.getMany([
+	 *   'database',
+	 *   'cache',
+	 *   'auth'
+	 * ]);
+	 * ```
+	 */
+	async getMany<K extends (keyof TServices & string)[]>(
+		names: [...K],
+	): Promise<{ [P in K[number]]: TServices[P] }> {
+		const result = {} as { [P in K[number]]: TServices[P] };
+
+		for (const name of names) {
+			result[name] = await this.get(name);
+		}
+
+		return result;
+	}
+
+	/**
+	 * Check if a service exists in the service discovery.
+	 * Can check by service name or service instance.
+	 *
+	 * @param service - The service name or service instance to check
+	 * @returns True if the service exists, false otherwise
+	 *
+	 * @example
+	 * ```typescript
+	 * if (discovery.has('database')) {
+	 *   const db = await discovery.get('database');
+	 * }
+	 *
+	 * // Or check with service instance
+	 * if (!discovery.has(databaseService)) {
+	 *   await discovery.register([databaseService]);
+	 * }
+	 * ```
+	 */
+	has(service: string | Service): boolean {
+		if (typeof service === 'string') {
+			return this.services.has(service);
+		}
+
+		return this.services.has(service.serviceName);
+	}
+}
+
+/**
+ * Utility type to extract service names from an array of services.
+ *
+ * @template T - Array of Service types
+ *
+ * @example
+ * ```typescript
+ * type Names = ExtractServiceNames<[typeof databaseService, typeof cacheService]>;
+ * // type Names = 'database' | 'cache'
+ * ```
+ */
+export type ExtractServiceNames<T extends Service[]> = T[number]['serviceName'];
+
+/**
+ * Utility type to create a record type from an array of services.
+ * Maps service names to their registered instance types.
+ *
+ * @template T - Array of Service types
+ *
+ * @example
+ * ```typescript
+ * type MyServiceRecord = ServiceRecord<[typeof databaseService, typeof cacheService]>;
+ * // type MyServiceRecord = {
+ * //   database: DatabaseInstance;
+ * //   cache: CacheInstance;
+ * // }
+ * ```
+ */
+export type ServiceRecord<T extends Service[]> = {
+	[K in T[number] as K['serviceName']]: K extends Service
+		? Awaited<ReturnType<K['register']>>
+		: never;
+};