@geekmidas/services 1.0.4 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/{ServiceDiscovery-CadEgTKz.d.mts → ServiceDiscovery-BO8W-RY8.d.cts} +2 -2
  3. package/dist/{ServiceDiscovery-DF4OKEZp.d.cts.map → ServiceDiscovery-BO8W-RY8.d.cts.map} +1 -1
  4. package/dist/{ServiceDiscovery-DF4OKEZp.d.cts → ServiceDiscovery-CRq_bGbi.d.mts} +2 -2
  5. package/dist/{ServiceDiscovery-CadEgTKz.d.mts.map → ServiceDiscovery-CRq_bGbi.d.mts.map} +1 -1
  6. package/dist/{ServiceDiscovery-SujDuYHr.mjs → ServiceDiscovery-DO_uDfuG.mjs} +2 -2
  7. package/dist/{ServiceDiscovery-SujDuYHr.mjs.map → ServiceDiscovery-DO_uDfuG.mjs.map} +1 -1
  8. package/dist/{ServiceDiscovery-Cxus7ber.cjs → ServiceDiscovery-m3XkNh32.cjs} +2 -2
  9. package/dist/{ServiceDiscovery-Cxus7ber.cjs.map → ServiceDiscovery-m3XkNh32.cjs.map} +1 -1
  10. package/dist/{context-BojeLlxs.mjs → context-C9DCrFWA.mjs} +5 -2
  11. package/dist/context-C9DCrFWA.mjs.map +1 -0
  12. package/dist/{context-D5pIUGkm.d.cts → context-CU-87vsM.d.mts} +2 -2
  13. package/dist/{context-D5pIUGkm.d.cts.map → context-CU-87vsM.d.mts.map} +1 -1
  14. package/dist/{context-CkCPt2Fe.cjs → context-Cf2Ig5qr.cjs} +11 -2
  15. package/dist/context-Cf2Ig5qr.cjs.map +1 -0
  16. package/dist/{context-OmKid3Mr.d.mts → context-D2owD3ac.d.cts} +2 -2
  17. package/dist/{context-OmKid3Mr.d.mts.map → context-D2owD3ac.d.cts.map} +1 -1
  18. package/dist/context.cjs +1 -1
  19. package/dist/context.d.cts +2 -2
  20. package/dist/context.d.mts +2 -2
  21. package/dist/context.mjs +1 -1
  22. package/dist/index.cjs +2 -2
  23. package/dist/index.d.cts +3 -3
  24. package/dist/index.d.mts +3 -3
  25. package/dist/index.mjs +2 -2
  26. package/dist/middy.cjs +120 -0
  27. package/dist/middy.cjs.map +1 -0
  28. package/dist/middy.d.cts +146 -0
  29. package/dist/middy.d.cts.map +1 -0
  30. package/dist/middy.d.mts +146 -0
  31. package/dist/middy.d.mts.map +1 -0
  32. package/dist/middy.mjs +118 -0
  33. package/dist/middy.mjs.map +1 -0
  34. package/dist/trpc.cjs +66 -0
  35. package/dist/trpc.cjs.map +1 -0
  36. package/dist/trpc.d.cts +86 -0
  37. package/dist/trpc.d.cts.map +1 -0
  38. package/dist/trpc.d.mts +86 -0
  39. package/dist/trpc.d.mts.map +1 -0
  40. package/dist/trpc.mjs +65 -0
  41. package/dist/trpc.mjs.map +1 -0
  42. package/dist/{types-B99KrvXR.d.mts → types-Bgk-0NOO.d.cts} +2 -2
  43. package/dist/{types-B99KrvXR.d.mts.map → types-Bgk-0NOO.d.cts.map} +1 -1
  44. package/dist/{types-BY9yrY6Y.d.cts → types-BoyOCa57.d.mts} +2 -2
  45. package/dist/{types-BY9yrY6Y.d.cts.map → types-BoyOCa57.d.mts.map} +1 -1
  46. package/docs/request-scoped-logging.md +14 -0
  47. package/package.json +37 -1
  48. package/src/__tests__/middy.spec.ts +218 -0
  49. package/src/__tests__/trpc.spec.ts +218 -0
  50. package/src/context.ts +7 -5
  51. package/src/middy.ts +226 -0
  52. package/src/trpc.ts +190 -0
  53. package/tsdown.config.ts +11 -1
  54. package/dist/ServiceDiscovery.cjs +0 -4
  55. package/dist/ServiceDiscovery.d.cts +0 -3
  56. package/dist/ServiceDiscovery.d.mts +0 -3
  57. package/dist/ServiceDiscovery.mjs +0 -4
  58. package/dist/context-BojeLlxs.mjs.map +0 -1
  59. package/dist/context-CkCPt2Fe.cjs.map +0 -1
  60. package/dist/types.cjs +0 -0
  61. package/dist/types.d.cts +0 -2
  62. package/dist/types.d.mts +0 -2
  63. package/dist/types.mjs +0 -0
@@ -0,0 +1,218 @@
1
+ import { EnvironmentParser } from '@geekmidas/envkit';
2
+ import type { Logger } from '@geekmidas/logger';
3
+ import { initTRPC } from '@trpc/server';
4
+ import { beforeEach, describe, expect, it, vi } from 'vitest';
5
+ import { serviceContext } from '../context';
6
+ import { ServiceDiscovery } from '../ServiceDiscovery';
7
+ import {
8
+ createRequestContextMiddleware,
9
+ createServicesMiddleware,
10
+ } from '../trpc';
11
+ import type { Service } from '../types';
12
+
13
+ beforeEach(() => {
14
+ // ServiceDiscovery is a process-wide singleton that caches resolved
15
+ // instances. Reset so each test gets a fresh registry.
16
+ ServiceDiscovery.reset();
17
+ });
18
+
19
+ function makeLogger(): Logger {
20
+ const logger: Logger = {
21
+ debug: vi.fn(),
22
+ info: vi.fn(),
23
+ warn: vi.fn(),
24
+ error: vi.fn(),
25
+ fatal: vi.fn(),
26
+ trace: vi.fn(),
27
+ child: vi.fn(() => logger),
28
+ };
29
+ return logger;
30
+ }
31
+
32
+ describe('createServicesMiddleware (with envParser)', () => {
33
+ it('resolves services and merges them onto ctx', async () => {
34
+ const databaseService = {
35
+ serviceName: 'database' as const,
36
+ register: () => ({ query: (sql: string) => `result: ${sql}` }),
37
+ } satisfies Service<'database', { query: (sql: string) => string }>;
38
+
39
+ const t = initTRPC.context<{ logger: Logger }>().create();
40
+ const withServices = createServicesMiddleware(
41
+ t.middleware,
42
+ new EnvironmentParser({}),
43
+ );
44
+
45
+ const caller = t.router({
46
+ run: t.procedure
47
+ .use(withServices([databaseService]))
48
+ .query(({ ctx }) => ctx.database.query('select 1')),
49
+ });
50
+
51
+ const result = await caller.createCaller({ logger: makeLogger() }).run();
52
+
53
+ expect(result).toBe('result: select 1');
54
+ });
55
+
56
+ it('makes serviceContext.getLogger() readable from inside a service method', async () => {
57
+ let observedLogger: Logger | null = null;
58
+ const dbService = {
59
+ serviceName: 'database' as const,
60
+ register: () => ({
61
+ touch() {
62
+ observedLogger = serviceContext.getLogger();
63
+ observedLogger.info('touched');
64
+ return 'ok';
65
+ },
66
+ }),
67
+ } satisfies Service<'database', { touch: () => string }>;
68
+
69
+ const t = initTRPC.context<{ logger: Logger }>().create();
70
+ const withServices = createServicesMiddleware(
71
+ t.middleware,
72
+ new EnvironmentParser({}),
73
+ );
74
+
75
+ const requestLogger = makeLogger();
76
+
77
+ const caller = t.router({
78
+ run: t.procedure
79
+ .use(withServices([dbService]))
80
+ .query(({ ctx }) => ctx.database.touch()),
81
+ });
82
+
83
+ await caller.createCaller({ logger: requestLogger }).run();
84
+
85
+ // getLogger() returns a request-scoped proxy (not the raw logger), so we
86
+ // assert it delegates to the request logger rather than checking identity.
87
+ expect(observedLogger).not.toBeNull();
88
+ expect(requestLogger.info).toHaveBeenCalledWith('touched');
89
+ });
90
+
91
+ it('throws cleanly when service code runs outside the procedure', () => {
92
+ // Sanity check that serviceContext stays scoped to the procedure call —
93
+ // reads outside any procedure must throw.
94
+ expect(() => serviceContext.getLogger()).toThrow();
95
+ });
96
+ });
97
+
98
+ describe('createServicesMiddleware (context-supplied discovery)', () => {
99
+ it('uses ctx.serviceDiscovery when no envParser is provided', async () => {
100
+ const cacheService = {
101
+ serviceName: 'cache' as const,
102
+ register: () => ({ get: (key: string) => `cached:${key}` }),
103
+ } satisfies Service<'cache', { get: (key: string) => string }>;
104
+
105
+ type Ctx = { logger: Logger; serviceDiscovery: ServiceDiscovery };
106
+ const t = initTRPC.context<Ctx>().create();
107
+ const withServices = createServicesMiddleware<Ctx, object>(t.middleware);
108
+
109
+ const caller = t.router({
110
+ run: t.procedure
111
+ .use(withServices([cacheService]))
112
+ .query(({ ctx }) => ctx.cache.get('k')),
113
+ });
114
+
115
+ const discovery = ServiceDiscovery.getInstance(new EnvironmentParser({}));
116
+
117
+ const result = await caller
118
+ .createCaller({ logger: makeLogger(), serviceDiscovery: discovery })
119
+ .run();
120
+
121
+ expect(result).toBe('cached:k');
122
+ });
123
+ });
124
+
125
+ describe('createRequestContextMiddleware', () => {
126
+ it('exposes ctx.logger via serviceContext.getLogger() for the handler', async () => {
127
+ const t = initTRPC.context<{ logger: Logger }>().create();
128
+ const withRequestContext = createRequestContextMiddleware(t.middleware);
129
+
130
+ let observed: Logger | null = null;
131
+ const caller = t.router({
132
+ run: t.procedure.use(withRequestContext).query(() => {
133
+ observed = serviceContext.getLogger();
134
+ observed.info('handled');
135
+ return 'done';
136
+ }),
137
+ });
138
+
139
+ const requestLogger = makeLogger();
140
+ const result = await caller.createCaller({ logger: requestLogger }).run();
141
+
142
+ expect(result).toBe('done');
143
+ // The request-scoped proxy delegates to ctx.logger.
144
+ expect(observed).not.toBeNull();
145
+ expect(requestLogger.info).toHaveBeenCalledWith('handled');
146
+ });
147
+
148
+ it('auto-generates requestId and startTime when ctx does not provide them', async () => {
149
+ const t = initTRPC.context<{ logger: Logger }>().create();
150
+ const withRequestContext = createRequestContextMiddleware(t.middleware);
151
+
152
+ let requestId: string | null = null;
153
+ let startTime: number | null = null;
154
+
155
+ const caller = t.router({
156
+ run: t.procedure.use(withRequestContext).query(() => {
157
+ requestId = serviceContext.getRequestId();
158
+ startTime = serviceContext.getRequestStartTime();
159
+ return 'ok';
160
+ }),
161
+ });
162
+
163
+ await caller.createCaller({ logger: makeLogger() }).run();
164
+
165
+ expect(requestId).toBeTypeOf('string');
166
+ expect(requestId!.length).toBeGreaterThan(0);
167
+ expect(typeof startTime).toBe('number');
168
+ });
169
+
170
+ it('honors caller-supplied requestId and startTime when present on ctx', async () => {
171
+ type Ctx = { logger: Logger; requestId?: string; startTime?: number };
172
+ const t = initTRPC.context<Ctx>().create();
173
+ const withRequestContext = createRequestContextMiddleware(t.middleware);
174
+
175
+ let observedId: string | null = null;
176
+ let observedStart: number | null = null;
177
+
178
+ const caller = t.router({
179
+ run: t.procedure.use(withRequestContext).query(() => {
180
+ observedId = serviceContext.getRequestId();
181
+ observedStart = serviceContext.getRequestStartTime();
182
+ return 'ok';
183
+ }),
184
+ });
185
+
186
+ await caller
187
+ .createCaller({
188
+ logger: makeLogger(),
189
+ requestId: 'req_abc',
190
+ startTime: 12345,
191
+ })
192
+ .run();
193
+
194
+ expect(observedId).toBe('req_abc');
195
+ expect(observedStart).toBe(12345);
196
+ });
197
+ });
198
+
199
+ describe('tagging for tooling', () => {
200
+ it('attaches the resolved services tuple to the inner middleware', () => {
201
+ const svc = {
202
+ serviceName: 'sample' as const,
203
+ register: () => ({}),
204
+ } satisfies Service<'sample', {}>;
205
+
206
+ const t = initTRPC.context<{ logger: Logger }>().create();
207
+ const withServices = createServicesMiddleware(
208
+ t.middleware,
209
+ new EnvironmentParser({}),
210
+ );
211
+
212
+ const builder = withServices([svc]);
213
+ const middlewares = (
214
+ builder as unknown as { _middlewares: Array<{ _services?: Service[] }> }
215
+ )._middlewares;
216
+ expect(middlewares?.at(-1)?._services).toEqual([svc]);
217
+ });
218
+ });
package/src/context.ts CHANGED
@@ -85,16 +85,18 @@ function createRequestScopedLogger(bindings: object[] = []): Logger {
85
85
  if (prop === 'then' || typeof prop === 'symbol') {
86
86
  return undefined;
87
87
  }
88
- const value = (resolve() as Record<string, unknown>)[prop];
88
+ const value = (resolve() as unknown as Record<string, unknown>)[prop];
89
89
  // Functions are re-resolved at *call* time so detached references
90
90
  // (`const info = logger.info`) still target the current request's
91
91
  // logger. Non-function members (e.g. `level`) forward as their live
92
92
  // value on the current request's logger.
93
93
  return typeof value === 'function'
94
- ? (...args: unknown[]) =>
95
- (resolve() as Record<string, (...a: unknown[]) => unknown>)[prop](
96
- ...args,
97
- )
94
+ ? (...args: unknown[]) => {
95
+ const fn = (resolve() as unknown as Record<string, unknown>)[
96
+ prop
97
+ ] as (...a: unknown[]) => unknown;
98
+ return fn(...args);
99
+ }
98
100
  : value;
99
101
  },
100
102
  // Keep `'prop' in logger` / hasOwnProperty truthful against the underlying
package/src/middy.ts ADDED
@@ -0,0 +1,226 @@
1
+ import type { EnvironmentParser } from '@geekmidas/envkit';
2
+ import type { Logger } from '@geekmidas/logger';
3
+ import type { MiddlewareObj } from '@middy/core';
4
+ import type { Context } from 'aws-lambda';
5
+ import { enterRequestContext, exitRequestContext } from './context';
6
+ import { ServiceDiscovery, type ServiceRecord } from './ServiceDiscovery';
7
+ import type { Service } from './types';
8
+
9
+ /**
10
+ * Middy middleware helpers that bring `@geekmidas/services` request context and
11
+ * service discovery to **standalone** Middy Lambda handlers — i.e. functions
12
+ * that aren't built with the `@geekmidas/constructs` Function/Cron constructs
13
+ * but still want `serviceContext.getLogger()` and resolved services.
14
+ *
15
+ * Why middleware (and not `runWithRequestContext`)? Middy runs `before → handler
16
+ * → after` as sequential awaits in a single async context, so establishing the
17
+ * context with `AsyncLocalStorage.enterWith` (via `enterRequestContext`) in a
18
+ * `before` hook propagates to the handler. `after`/`onError` reset it.
19
+ *
20
+ * Teardown is best-effort: like `enterRequestContext`, the reset is observable
21
+ * to code the handler reaches but not necessarily to the frame that invoked the
22
+ * Middy handler. This is fine for Lambda, where each invocation runs in its own
23
+ * fresh async context — `requestContext` always establishes a brand-new context
24
+ * per invocation, so requests never inherit a previous invocation's logger.
25
+ *
26
+ * @module
27
+ */
28
+
29
+ /**
30
+ * Options for {@link requestContext}. Generic over the logger type so a custom
31
+ * logger that extends {@link Logger} is preserved rather than widened.
32
+ */
33
+ export interface RequestContextOptions<TLogger extends Logger = Logger> {
34
+ /**
35
+ * Logger to derive the per-request child logger from. Required — the caller
36
+ * decides which logger to use (there is no implicit default).
37
+ */
38
+ logger: TLogger;
39
+ /**
40
+ * Derive the request id from the event/context.
41
+ * Defaults to `context.awsRequestId` (always present in a Lambda invocation).
42
+ */
43
+ getRequestId?: (event: unknown, context: Context) => string;
44
+ /**
45
+ * Extra bindings to attach to the per-request child logger.
46
+ */
47
+ bindings?: (event: unknown, context: Context) => Record<string, unknown>;
48
+ }
49
+
50
+ /**
51
+ * Options for {@link addServices} — how services are resolved. No logger is
52
+ * needed because resolving services doesn't establish a request context.
53
+ */
54
+ export interface ServiceResolverOptions {
55
+ /**
56
+ * Environment parser used to build the {@link ServiceDiscovery}. Required —
57
+ * the caller supplies the parser (there is no implicit `process.env` default).
58
+ */
59
+ envParser: EnvironmentParser<{}>;
60
+ /**
61
+ * Explicit {@link ServiceDiscovery} to resolve services from. Takes
62
+ * precedence over `envParser`.
63
+ */
64
+ serviceDiscovery?: ServiceDiscovery;
65
+ }
66
+
67
+ /**
68
+ * Options for {@link withServices}: request context (logger) + service resolution.
69
+ */
70
+ export type ServiceMiddlewareOptions<TLogger extends Logger = Logger> =
71
+ RequestContextOptions<TLogger> & ServiceResolverOptions;
72
+
73
+ function deriveRequestId(
74
+ options: RequestContextOptions,
75
+ event: unknown,
76
+ context: Context,
77
+ ): string {
78
+ // Lambda always populates context.awsRequestId; getRequestId can override it.
79
+ return options.getRequestId?.(event, context) ?? context.awsRequestId;
80
+ }
81
+
82
+ function buildLogger(
83
+ baseLogger: Logger,
84
+ options: RequestContextOptions,
85
+ requestId: string,
86
+ event: unknown,
87
+ context: Context,
88
+ ): Logger {
89
+ return baseLogger.child({
90
+ requestId,
91
+ ...(options.bindings?.(event, context) ?? {}),
92
+ });
93
+ }
94
+
95
+ /**
96
+ * Middy middleware that establishes a request context for the handler so any
97
+ * code it reaches — including `@geekmidas/services` service methods — can call
98
+ * `serviceContext.getLogger()` / `getRequestId()` / `getRequestStartTime()`.
99
+ *
100
+ * Use this on standalone functions that need request-scoped logging. To also
101
+ * resolve services, pair it with {@link addServices}, or use
102
+ * {@link withServices} which bundles both.
103
+ *
104
+ * @example
105
+ * ```ts
106
+ * import middy from '@middy/core';
107
+ * import { serviceContext } from '@geekmidas/services';
108
+ * import { requestContext } from '@geekmidas/services/middy';
109
+ *
110
+ * export const handler = middy(async () => {
111
+ * serviceContext.getLogger().info('tick');
112
+ * }).use(requestContext({ logger }));
113
+ * ```
114
+ */
115
+ export function requestContext<TLogger extends Logger = Logger>(
116
+ options: RequestContextOptions<TLogger>,
117
+ ): MiddlewareObj<unknown, unknown, Error, Context> {
118
+ const baseLogger = options.logger;
119
+ return {
120
+ before: (request) => {
121
+ const { event, context } = request;
122
+ const requestId = deriveRequestId(options, event, context);
123
+ const logger = buildLogger(
124
+ baseLogger,
125
+ options,
126
+ requestId,
127
+ event,
128
+ context,
129
+ );
130
+ enterRequestContext({ logger, requestId, startTime: Date.now() });
131
+ },
132
+ after: () => {
133
+ exitRequestContext();
134
+ },
135
+ onError: () => {
136
+ exitRequestContext();
137
+ },
138
+ };
139
+ }
140
+
141
+ function resolveDiscovery(options: ServiceResolverOptions): ServiceDiscovery {
142
+ return (
143
+ options.serviceDiscovery ?? ServiceDiscovery.getInstance(options.envParser)
144
+ );
145
+ }
146
+
147
+ /**
148
+ * Event augmentation applied by {@link addServices} / {@link withServices}:
149
+ * resolved services keyed by `serviceName`. Intersect it with your own event
150
+ * type to type the handler, e.g. `(event: EventServices<T> & APIGatewayEvent)`.
151
+ */
152
+ export type EventServices<T extends Service[]> = {
153
+ services: ServiceRecord<T>;
154
+ };
155
+
156
+ /**
157
+ * Middy middleware that resolves an array of {@link Service}s via
158
+ * {@link ServiceDiscovery} and attaches the resolved record to `event.services`
159
+ * (keyed by each service's `serviceName`), matching how the `Function`/`Cron`
160
+ * constructs expose services on the event.
161
+ *
162
+ * This middleware only resolves services; it does **not** establish a request
163
+ * context. If your services read `serviceContext` (e.g. `getLogger()`), pair it
164
+ * with {@link requestContext}, or use {@link withServices} which bundles both.
165
+ *
166
+ * Chainable — `.use(addServices([a])).use(addServices([b]))` accumulates onto
167
+ * `event.services`.
168
+ *
169
+ * @example
170
+ * ```ts
171
+ * import middy from '@middy/core';
172
+ * import { addServices, requestContext } from '@geekmidas/services/middy';
173
+ *
174
+ * export const handler = middy(async (event) => {
175
+ * await event.services.database.users.deletePast();
176
+ * event.services.cache.clear();
177
+ * })
178
+ * .use(requestContext())
179
+ * .use(addServices([databaseService, cacheService], { envParser }));
180
+ * ```
181
+ */
182
+ export function addServices<const T extends Service[]>(
183
+ services: [...T],
184
+ options: ServiceResolverOptions,
185
+ ): MiddlewareObj<EventServices<T>, unknown, Error, Context> {
186
+ const discovery = resolveDiscovery(options);
187
+
188
+ return {
189
+ before: async (request) => {
190
+ const resolved = await discovery.register(services);
191
+ const event = request.event as { services?: Record<string, unknown> };
192
+ // Merge so chained addServices(...) calls accumulate on event.services.
193
+ event.services = { ...(event.services ?? {}), ...resolved };
194
+ },
195
+ };
196
+ }
197
+
198
+ /**
199
+ * Batteries-included Middy setup for service-backed handlers: returns a pair of
200
+ * middlewares — {@link requestContext} followed by {@link addServices} — so a
201
+ * single `.use(withServices([...]))` gives the handler both a request context
202
+ * and the resolved services on `event.services`.
203
+ *
204
+ * @example
205
+ * ```ts
206
+ * import middy from '@middy/core';
207
+ * import { withServices } from '@geekmidas/services/middy';
208
+ *
209
+ * export const handler = middy(async (event) => {
210
+ * await event.services.database.users.deletePast();
211
+ * event.services.cache.clear();
212
+ * }).use(withServices([databaseService, cacheService], { envParser }));
213
+ * ```
214
+ */
215
+ export function withServices<
216
+ const T extends Service[],
217
+ TLogger extends Logger = Logger,
218
+ >(
219
+ services: [...T],
220
+ options: ServiceMiddlewareOptions<TLogger>,
221
+ ): [
222
+ MiddlewareObj<unknown, unknown, Error, Context>,
223
+ MiddlewareObj<EventServices<T>, unknown, Error, Context>,
224
+ ] {
225
+ return [requestContext(options), addServices(services, options)];
226
+ }
package/src/trpc.ts ADDED
@@ -0,0 +1,190 @@
1
+ import { randomUUID } from 'node:crypto';
2
+ import type { EnvironmentParser } from '@geekmidas/envkit';
3
+ import type { Logger } from '@geekmidas/logger';
4
+ import type {
5
+ TRPCMiddlewareBuilder,
6
+ TRPCMiddlewareFunction,
7
+ } from '@trpc/server';
8
+ import { runWithRequestContext } from './context';
9
+ import { ServiceDiscovery, type ServiceRecord } from './ServiceDiscovery';
10
+ import type { Service } from './types';
11
+
12
+ /**
13
+ * Shape of `t.middleware` from `@trpc/server`. We accept this rather than the
14
+ * initialized `t` object so callers retain ownership of their tRPC instance
15
+ * (no double-initialization, no opinion on context/meta shape).
16
+ */
17
+ type CreateMiddleware<TContext, TMeta> = <$ContextOverrides>(
18
+ fn: TRPCMiddlewareFunction<
19
+ TContext,
20
+ TMeta,
21
+ object,
22
+ $ContextOverrides,
23
+ unknown
24
+ >,
25
+ ) => TRPCMiddlewareBuilder<TContext, TMeta, $ContextOverrides, unknown>;
26
+
27
+ /**
28
+ * Result of `createServicesMiddleware`: a function that accepts a service
29
+ * tuple and returns a tRPC middleware that merges resolved services onto the
30
+ * context.
31
+ */
32
+ export type ServicesMiddleware<
33
+ TContext extends object,
34
+ TMeta extends object,
35
+ > = <const T extends Service[]>(
36
+ services: [...T],
37
+ ) => TRPCMiddlewareBuilder<TContext, TMeta, ServiceRecord<T>, unknown>;
38
+
39
+ /**
40
+ * Context shape required by `createServicesMiddleware` overload 2.
41
+ * Procedures that pull services via context-stored discovery must expose it
42
+ * under `serviceDiscovery`.
43
+ */
44
+ export interface ContextWithServiceDiscovery {
45
+ serviceDiscovery: ServiceDiscovery;
46
+ }
47
+
48
+ /**
49
+ * Minimum context required for request-context propagation. `logger` must be
50
+ * present so services can call `serviceContext.getLogger()`. `requestId` and
51
+ * `startTime` are auto-generated if missing.
52
+ */
53
+ export interface ContextWithLogger {
54
+ logger: Logger;
55
+ requestId?: string;
56
+ startTime?: number;
57
+ }
58
+
59
+ /**
60
+ * Create a tRPC middleware that:
61
+ *
62
+ * 1. Resolves the requested services via `ServiceDiscovery`.
63
+ * 2. Wraps the downstream call in `runWithRequestContext` so any code reached
64
+ * by the procedure (including service method implementations) can read the
65
+ * current logger/request id via `serviceContext`.
66
+ * 3. Merges the resolved services onto the tRPC context so handlers can access
67
+ * them by service name (`ctx.database`, `ctx.cache`, ...).
68
+ *
69
+ * Two overloads:
70
+ * - Pass an `envParser` to create a per-request `ServiceDiscovery` instance.
71
+ * - Omit `envParser` to read `ctx.serviceDiscovery` from the tRPC context.
72
+ *
73
+ * @example
74
+ * ```ts
75
+ * import { initTRPC } from '@trpc/server';
76
+ * import { createServicesMiddleware } from '@geekmidas/services/trpc';
77
+ *
78
+ * const t = initTRPC.context<Context>().create();
79
+ * const withServices = createServicesMiddleware(t.middleware, envParser);
80
+ *
81
+ * export const authedProcedure = t.procedure.use(
82
+ * withServices([databaseService, cacheService]),
83
+ * );
84
+ * ```
85
+ */
86
+ export function createServicesMiddleware<
87
+ TContext extends ContextWithLogger & object,
88
+ TMeta extends object,
89
+ >(
90
+ mw: CreateMiddleware<TContext, TMeta>,
91
+ envParser: EnvironmentParser<{}>,
92
+ ): ServicesMiddleware<TContext, TMeta>;
93
+ export function createServicesMiddleware<
94
+ TContext extends ContextWithLogger & ContextWithServiceDiscovery & object,
95
+ TMeta extends object,
96
+ >(mw: CreateMiddleware<TContext, TMeta>): ServicesMiddleware<TContext, TMeta>;
97
+ export function createServicesMiddleware<
98
+ TContext extends ContextWithLogger & object,
99
+ TMeta extends object,
100
+ >(
101
+ mw: CreateMiddleware<TContext, TMeta>,
102
+ envParser?: EnvironmentParser<{}>,
103
+ ): ServicesMiddleware<TContext, TMeta> {
104
+ return (<const T extends Service[]>(services: [...T]) => {
105
+ const builder = mw(async (opts) => {
106
+ const ctx = opts.ctx as TContext & Partial<ContextWithServiceDiscovery>;
107
+
108
+ const discovery =
109
+ ctx.serviceDiscovery ??
110
+ ServiceDiscovery.getInstance(
111
+ envParser ??
112
+ (() => {
113
+ // Hit only if overload 2 was selected but ctx.serviceDiscovery is
114
+ // missing at runtime — surface the mistake immediately rather
115
+ // than letting an undefined env parser fail deep inside register.
116
+ throw new Error(
117
+ 'createServicesMiddleware: no `envParser` provided and ' +
118
+ '`ctx.serviceDiscovery` is missing. Pass an EnvironmentParser ' +
119
+ 'to createServicesMiddleware(), or attach a ServiceDiscovery ' +
120
+ 'instance to the tRPC context.',
121
+ );
122
+ })(),
123
+ );
124
+
125
+ const requestId = ctx.requestId ?? randomUUID();
126
+ const startTime = ctx.startTime ?? Date.now();
127
+
128
+ return runWithRequestContext(
129
+ { logger: ctx.logger, requestId, startTime },
130
+ async () => {
131
+ const resolved = await discovery.register(services);
132
+ return opts.next({
133
+ ctx: { ...opts.ctx, ...resolved } as typeof opts.ctx &
134
+ ServiceRecord<T>,
135
+ });
136
+ },
137
+ );
138
+ });
139
+
140
+ // Tag the inner middleware function with the requested services so external
141
+ // tooling (e.g. detect-procedures route generators) can introspect a
142
+ // procedure's service dependencies without re-executing middleware.
143
+ const middlewares = (
144
+ builder as unknown as { _middlewares?: Array<{ _services?: Service[] }> }
145
+ )._middlewares;
146
+ if (middlewares?.length) {
147
+ const last = middlewares[middlewares.length - 1];
148
+ if (last) last._services = services as unknown as Service[];
149
+ }
150
+
151
+ return builder as TRPCMiddlewareBuilder<
152
+ TContext,
153
+ TMeta,
154
+ ServiceRecord<T>,
155
+ unknown
156
+ >;
157
+ }) as ServicesMiddleware<TContext, TMeta>;
158
+ }
159
+
160
+ /**
161
+ * Create a tRPC middleware that establishes a request context for downstream
162
+ * code without resolving any services. Useful when services aren't needed on
163
+ * a procedure but the handler (or libraries it calls) still wants to read
164
+ * `serviceContext.getLogger()` / `getRequestId()` / `getRequestStartTime()`.
165
+ *
166
+ * `requestId` and `startTime` are pulled from the tRPC context when present,
167
+ * otherwise generated (`randomUUID()` and `Date.now()`).
168
+ *
169
+ * @example
170
+ * ```ts
171
+ * const withRequestContext = createRequestContextMiddleware(t.middleware);
172
+ * export const baseProcedure = t.procedure.use(withRequestContext);
173
+ * ```
174
+ */
175
+ export function createRequestContextMiddleware<
176
+ TContext extends ContextWithLogger & object,
177
+ TMeta extends object,
178
+ >(
179
+ mw: CreateMiddleware<TContext, TMeta>,
180
+ ): TRPCMiddlewareBuilder<TContext, TMeta, object, unknown> {
181
+ return mw(async (opts) => {
182
+ const ctx = opts.ctx as TContext;
183
+ const requestId = ctx.requestId ?? randomUUID();
184
+ const startTime = ctx.startTime ?? Date.now();
185
+ return runWithRequestContext(
186
+ { logger: ctx.logger, requestId, startTime },
187
+ () => opts.next(),
188
+ );
189
+ });
190
+ }
package/tsdown.config.ts CHANGED
@@ -1,3 +1,13 @@
1
1
  import { defineConfig } from 'tsdown';
2
2
 
3
- export default defineConfig({});
3
+ export default defineConfig({
4
+ entry: ['src/index.ts', 'src/context.ts', 'src/trpc.ts', 'src/middy.ts'],
5
+ clean: true,
6
+ outDir: 'dist',
7
+ format: ['cjs', 'esm'],
8
+ sourcemap: true,
9
+ dts: true,
10
+ outExtensions: (ctx) => ({
11
+ js: ctx.format === 'es' ? '.mjs' : '.cjs',
12
+ }),
13
+ });
@@ -1,4 +0,0 @@
1
- require('./context-CkCPt2Fe.cjs');
2
- const require_ServiceDiscovery = require('./ServiceDiscovery-Cxus7ber.cjs');
3
-
4
- exports.ServiceDiscovery = require_ServiceDiscovery.ServiceDiscovery;
@@ -1,3 +0,0 @@
1
- import "./types-BY9yrY6Y.cjs";
2
- import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-DF4OKEZp.cjs";
3
- export { ExtractServiceNames, ServiceDiscovery, ServiceRecord };
@@ -1,3 +0,0 @@
1
- import "./types-B99KrvXR.mjs";
2
- import { ExtractServiceNames, ServiceDiscovery, ServiceRecord } from "./ServiceDiscovery-CadEgTKz.mjs";
3
- export { ExtractServiceNames, ServiceDiscovery, ServiceRecord };
@@ -1,4 +0,0 @@
1
- import "./context-BojeLlxs.mjs";
2
- import { ServiceDiscovery } from "./ServiceDiscovery-SujDuYHr.mjs";
3
-
4
- export { ServiceDiscovery };