@geekmidas/services 9.0.2 → 10.0.0-alpha.0

package/README.md

@@ -49,11 +49,11 @@ export { databaseService };
 ### Use Services in Constructs
 
 ```typescript
-import { e } from '@geekmidas/constructs/endpoints';
+import { api } from '../constructs/api';
 import { databaseService } from './services/database';
 import { z } from 'zod';
 
-export const getUser = e
+export const getUser = api
   .get('/users/:id')
   .params(z.object({ id: z.string() }))
   .services([databaseService])
@@ -210,17 +210,17 @@ const userEventPublisher = {
 Inject multiple services into a construct:
 
 ```typescript
-import { e } from '@geekmidas/constructs/endpoints';
+import { api } from '../constructs/api';
 import { databaseService } from './services/database';
 import { cacheService } from './services/cache';
 import { emailService } from './services/email';
 import { z } from 'zod';
 
-export const createUser = e
+export const createUser = api
   .post('/users')
   .body(z.object({
     name: z.string(),
-    email: z.string().email()
+    email: z.email()
   }))
   .services([databaseService, cacheService, emailService])
   .handle(async ({ body, services }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/services",
-  "version": "9.0.2",
+  "version": "10.0.0-alpha.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -45,6 +45,9 @@
       }
     }
   },
+  "files": [
+    "dist"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/geekmidas/toolbox"
@@ -58,8 +61,8 @@
     "@middy/core": ">=6.3.1",
     "@trpc/server": ">=11.0.0",
     "@types/aws-lambda": ">=8.10.92",
-    "@geekmidas/envkit": "^9.0.2",
-    "@geekmidas/logger": "^9.0.2"
+    "@geekmidas/envkit": "^10.0.0-alpha.0",
+    "@geekmidas/logger": "^10.0.0-alpha.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/envkit": {
@@ -83,8 +86,8 @@
     "@trpc/server": "~11.16.0",
     "@types/aws-lambda": "~8.10.147",
     "@types/node": "~24.9.1",
-    "@geekmidas/envkit": "^9.0.2",
-    "@geekmidas/logger": "^9.0.2"
+    "@geekmidas/envkit": "^10.0.0-alpha.0",
+    "@geekmidas/logger": "^10.0.0-alpha.0"
   },
   "scripts": {
     "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"

package/CHANGELOG.md

@@ -1,109 +0,0 @@
-# @geekmidas/services
-
-## 9.0.2
-
-### Patch Changes
-
-- [#12](https://github.com/geekmidas/toolbox/pull/12) [`d53863a`](https://github.com/geekmidas/toolbox/commit/d53863a84db2e4ab5420e08f79128b637043fc42) Thanks [@geekmidas](https://github.com/geekmidas)! - Align every published package on a single version and keep them in step.
-
-  All packages now share one version, enforced by a changesets `fixed` group. The
-  baseline is 9.0.1 — @geekmidas/client's published version — so nothing moves
-  backwards; this release takes the whole set to 9.0.2 together.
-
-  Independent versions made "which version of the docs applies to me"
-  unanswerable: a reader on constructs@7 and cli@2 was on no version at all. One
-  number per release makes versioned documentation possible, and lets 9 freeze as
-  the current paradigm while the constructs rework is developed against it.
-
-  Every release now publishes every package, and a major anywhere is a major
-  everywhere. Peer ranges get simpler in return.
-
-- Updated dependencies [[`d53863a`](https://github.com/geekmidas/toolbox/commit/d53863a84db2e4ab5420e08f79128b637043fc42)]:
-  - @geekmidas/envkit@9.0.2
-  - @geekmidas/logger@9.0.2
-
-## 2.0.1
-
-### Patch Changes
-
-- 🐛 [#11](https://github.com/geekmidas/toolbox/pull/11) [`40f4dc0`](https://github.com/geekmidas/toolbox/commit/40f4dc095911b2223a255029d8f776caf7781309) Thanks [@geekmidas](https://github.com/geekmidas)! - Patch release across all packages to realign published versions with the
-  registry. The previous release only published the four packages that had
-  version bumps; the remaining packages failed with "cannot publish over the
-  previously published versions" because their versions were unchanged.
-- Updated dependencies [[`40f4dc0`](https://github.com/geekmidas/toolbox/commit/40f4dc095911b2223a255029d8f776caf7781309)]:
-  - @geekmidas/envkit@1.1.1
-  - @geekmidas/logger@1.0.3
-
-## 2.0.0
-
-### Patch Changes
-
-- Updated dependencies [[`7323f34`](https://github.com/geekmidas/toolbox/commit/7323f34176d63170dd53450889ac0b5959420c3c), [`79e2929`](https://github.com/geekmidas/toolbox/commit/79e292978d3dbc8927e25814bdb051d1c380600a)]:
-  - @geekmidas/envkit@1.1.0
-
-## 1.1.1
-
-### Patch Changes
-
-- 🐛 [`9f02e9c`](https://github.com/geekmidas/toolbox/commit/9f02e9c8419db1e41692e996e177f2473237ca76) Thanks [@geekmidas](https://github.com/geekmidas)! - fix(services): bind `this` when invoking request-scoped logger methods
-
-  The request-scoped logger proxy re-resolved log methods at call time but
-  invoked them unbound. Pino's log methods read internal state off the
-  receiver (`this[Symbol(pino.msgPrefix)]`), so calling them without `this`
-  threw "Cannot read properties of undefined (reading 'Symbol(pino.msgPrefix)')"
-  in production (pino), while dev/test console & spy loggers were unaffected.
-  The proxy now invokes the resolved method with the current request's logger
-  as `this`.
-
-## 1.1.0
-
-### Minor Changes
-
-- [#5](https://github.com/geekmidas/toolbox/pull/5) [`811d740`](https://github.com/geekmidas/toolbox/commit/811d740ae3875d59ad1b0dc50261266963c8cb76) Thanks [@geekmidas](https://github.com/geekmidas)! - Move the tRPC and Middy service integrations from `@geekmidas/constructs` to `@geekmidas/services`, where they belong — they depend only on `@geekmidas/services`, not on any construct.
-  - ✨ **`@geekmidas/constructs`:** the `@geekmidas/constructs/trpc` and `@geekmidas/constructs/middy` entry points are removed (they were only just added). Import from `@geekmidas/services/trpc` and `@geekmidas/services/middy` instead. (`@trpc/server` is no longer a peer dependency of `@geekmidas/constructs`.)
-  - ✨ **`@geekmidas/services`:** adds `/trpc` (`createServicesMiddleware`, `createRequestContextMiddleware`) and `/middy` (`requestContext`, `addServices`, `withServices`, `EventServices`) exports.
-
-  The Middy middlewares were also tightened:
-  - `requestContext` / `withServices` now require an explicit `logger` (no `ConsoleLogger` default) and are generic over `TLogger extends Logger`, so a custom logger type is preserved.
-  - `addServices` / `withServices` now require an `envParser` (no implicit `process.env` default).
-  - 🐛 Resolved services are attached to `event.services` (matching the `Function`/`Cron` constructs).
-
-## 1.0.4
-
-### Patch Changes
-
-- 🐛 [#3](https://github.com/geekmidas/toolbox/pull/3) [`42fda53`](https://github.com/geekmidas/toolbox/commit/42fda532bdf4489a3352f6a684f5f30beafccedd) Thanks [@geekmidas](https://github.com/geekmidas)! - Fix stale logger from service initialization
-
-## 1.0.3
-
-### Patch Changes
-
-- ✨ [`351f73b`](https://github.com/geekmidas/toolbox/commit/351f73b032bc0742b7f611a9fbcdfc85bbfd69a8) Thanks [@geekmidas](https://github.com/geekmidas)! - Update request context and add support for trpc
-
-## 1.0.2
-
-### Patch Changes
-
-- 🐛 [`d70c6c0`](https://github.com/geekmidas/toolbox/commit/d70c6c0aeb8a79da2473ac77dbd8255a4a2f5651) Thanks [@geekmidas](https://github.com/geekmidas)! - Fix `package.json` exports so TypeScript declarations resolve correctly under NodeNext/Bundler module resolution. Each subpath export now nests `types` inside its `import`/`require` condition, pointing at the `.d.mts` and `.d.cts` files that `tsdown` actually emits (previously the exports referenced non-existent `.d.ts` files, causing type-resolution failures for consumers). Both ESM (`.mjs`) and CJS (`.cjs`) runtime entry points are preserved. Additionally, `@geekmidas/ui` had `import` paths pointing at `.js` files that were never emitted — those are corrected to `.mjs`.
-
-- Updated dependencies [[`d70c6c0`](https://github.com/geekmidas/toolbox/commit/d70c6c0aeb8a79da2473ac77dbd8255a4a2f5651)]:
-  - @geekmidas/envkit@1.0.7
-  - @geekmidas/logger@1.0.2
-
-## 1.0.1
-
-### Patch Changes
-
-- 🔥 [`4bed570`](https://github.com/geekmidas/toolbox/commit/4bed57049db24417ef81279bc88fa0e1255f7b9a) Thanks [@geekmidas](https://github.com/geekmidas)! - Remove singleton enforcement so people can use it how they see fit
-
-## 1.0.0
-
-### Major Changes
-
-- [`ff7b115`](https://github.com/geekmidas/toolbox/commit/ff7b11599f60f84ac6cdc73714c853ecf786b2e8) Thanks [@geekmidas](https://github.com/geekmidas)! - Version 1 Stable release
-
-### Patch Changes
-
-- Updated dependencies [[`ff7b115`](https://github.com/geekmidas/toolbox/commit/ff7b11599f60f84ac6cdc73714c853ecf786b2e8)]:
-  - @geekmidas/envkit@1.0.0
-  - @geekmidas/logger@1.0.0

package/docs/request-scoped-logging.md

@@ -1,167 +0,0 @@
-# Request-Scoped Logging in Singleton Services
-
-## Problem
-
-Services in `@geekmidas/services` are **singletons**. `ServiceDiscovery.register()`
-(and `get()`) instantiates a service **once**, caches the instance in an internal
-`Map`, and returns that same instance for every subsequent request:
-
-```ts
-// ServiceDiscovery.register()
-if (this.instances.has(name)) {
-  return this.instances.get(name); // cached — register() does NOT run again
-}
-const instance = await service.register({ envParser, context: serviceContext });
-this.instances.set(name, instance);
-```
-
-The per-request logger, on the other hand, is **not** a singleton. On every request
-an adaptor builds a fresh child logger with request-specific bindings and stores it
-in `AsyncLocalStorage` via `runWithRequestContext`:
-
-```ts
-// e.g. HonoEndpointAdaptor
-const logger = endpoint.logger.child({
-  requestId,          // unique per request
-  endpoint, route, host, method, path,
-});
-
-return runWithRequestContext({ logger, requestId, startTime }, async () => {
-  const services = await serviceDiscovery.register(endpoint.services);
-  // ...handle request...
-});
-```
-
-### The bug
-
-`service.register()` runs **inside the first request's context**. If a service reads
-the logger **at registration time** and stores the concrete reference:
-
-```ts
-const databaseService = {
-  serviceName: 'database' as const,
-  register({ context }) {
-    const logger = context.getLogger(); // ❌ resolved ONCE, during request #1
-
-    return {
-      async query(sql: string) {
-        logger.debug({ sql }, 'Executing query'); // always request #1's logger
-      },
-    };
-  },
-} satisfies Service<'database', Database>;
-```
-
-…then `logger` is frozen to the **first** request's logger forever, because
-`register()` never runs again. Every later request reuses the cached service
-instance, so its logs carry the **first** request's `requestId` (and any user/session
-bindings).
-
-**Symptom:** logs make it look like the user who made the *first* request after a
-cold start is responsible for actions actually performed by *other* users on later
-requests. Request correlation, per-user log filtering, and audit trails are all
-silently wrong.
-
-This is an easy mistake to make because `register()` is handed a `context` object,
-and "grab the logger once and reuse it" looks reasonable — but it is incompatible
-with the singleton lifecycle.
-
-## Solution
-
-`serviceContext.getLogger()` returns a **stable, request-scoped proxy logger**
-instead of the raw logger. The proxy holds no logger of its own — on **every** log
-call it re-resolves the current request's logger from `AsyncLocalStorage`:
-
-```
-proxy.info('x')  →  asyncLocalStorage.getStore().logger.info('x')   // resolved at call time
-```
-
-Because resolution happens per call (not at capture time), capturing the logger once
-during `register()` is now **safe**: the single captured reference routes each call
-to whichever request is currently executing.
-
-```ts
-register({ context }) {
-  const logger = context.getLogger(); // ✅ now safe to capture — it's a live proxy
-
-  return {
-    async query(sql: string) {
-      logger.debug({ sql }, 'Executing query'); // logs to the CURRENT request
-    },
-  };
-}
-```
-
-### Child loggers compose correctly too
-
-`proxy.child(bindings)` returns **another** proxy carrying the bindings, applied lazily
-on top of the current request's logger at call time:
-
-```ts
-register({ context }) {
-  // Captured once. `{ svc: 'db' }` is the static part; the per-request bindings
-  // (requestId, user, ...) come from whichever base logger is current.
-  const logger = context.getLogger().child({ svc: 'db' });
-
-  return {
-    async query(sql: string) {
-      // request A → loggerA.child({ svc: 'db' }).debug(...)
-      // request B → loggerB.child({ svc: 'db' }).debug(...)
-      logger.debug({ sql }, 'Executing query');
-    },
-  };
-}
-```
-
-### Implementation
-
-See `createRequestScopedLogger` in
-[`src/context.ts`](../src/context.ts):
-
-- `getLogger()` still **throws eagerly** if called with no active request context,
-  preserving the "catch bugs early" contract.
-- The returned object is a shared, process-wide proxy. It carries no request state,
-  so sharing it across requests is safe — `AsyncLocalStorage` provides correct
-  per-async-context isolation, and each resolve/log call is synchronous (no `await`
-  between resolving and using the logger), so it is concurrency-safe.
-- Each `child()` call returns a new proxy that remembers its bindings and rebuilds
-  the child chain off the current base logger, memoised per underlying logger to
-  avoid rebuilding the chain on every log line.
-
-## Guidance for service authors
-
-- ✅ You **may** capture `context.getLogger()` (or a `.child()` of it) once in
-  `register()` and reuse it — it stays correct per request.
-- ✅ You **may** also call `context.getLogger()` inside each method; behaviour is
-  identical.
-- ⚠️ Do **not** wrap the proxy in something that snapshots a concrete logger, e.g.
-  `const real = someConcreteLogger; ...` outside the proxy. Resolution only stays
-  live while you go through the proxy returned by `getLogger()`/`.child()`.
-- ⚠️ Calling a log method outside any request context throws
-  (`called outside request context`). Guard background work with
-  `serviceContext.hasContext()` if it may run detached from a request.
-
-## Tests
-
-Regression coverage lives in
-[`src/__tests__/context.spec.ts`](../src/__tests__/context.spec.ts):
-
-- `captured-once logger follows each request (singleton service fix)` — a logger
-  captured during the first request still logs to the second request's logger.
-- `child loggers also follow the current request` — the same guarantee for
-  `.child()` proxies.
-- `should delegate to the current request logger` — basic delegation.
-
-## Establishing the context
-
-The request context this relies on is established by the adaptors that run your
-code:
-
-- **Constructs** (`Endpoint`, `Function`, `Cron`, `Subscriber`) wrap each
-  invocation in `runWithRequestContext` automatically.
-- **Standalone Middy handlers** can opt in with the
-  `@geekmidas/services/middy` middlewares (`requestContext`, `addServices`,
-  `withServices`), which establish the context (and optionally resolve services)
-  before the handler runs.
-- **Tests** can use `@geekmidas/testkit`'s `runInRequestContext` /
-  `requestContextFixture`.

package/src/ServiceDiscovery.ts

@@ -1,252 +0,0 @@
-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;
-	}
-
-	/**
-	 *
-	 * @param envParser - Environment parser for service configuration
-	 */
-	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;
-};