@geekmidas/constructs 9.0.2 → 9.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "9.0.2",
+  "version": "9.1.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -54,6 +54,16 @@
         "default": "./dist/topic/index.cjs"
       }
     },
+    "./monitors": {
+      "import": {
+        "types": "./dist/monitors/index.d.mts",
+        "default": "./dist/monitors/index.mjs"
+      },
+      "require": {
+        "types": "./dist/monitors/index.d.cts",
+        "default": "./dist/monitors/index.cjs"
+      }
+    },
     "./crons": {
       "import": {
         "types": "./dist/crons/index.d.mts",
@@ -146,33 +156,33 @@
     "pg": "~8.16.3",
     "msw": "~2.10.3",
     "zod": "~4.1.13",
-    "@geekmidas/audit": "^9.0.2",
-    "@geekmidas/cache": "^9.0.2",
-    "@geekmidas/db": "^9.0.2",
-    "@geekmidas/envkit": "^9.0.2",
-    "@geekmidas/errors": "^9.0.2",
-    "@geekmidas/events": "^9.0.2",
-    "@geekmidas/logger": "^9.0.2",
-    "@geekmidas/rate-limit": "^9.0.2",
-    "@geekmidas/schema": "^9.0.2",
-    "@geekmidas/services": "^9.0.2",
-    "@geekmidas/testkit": "^9.0.2"
+    "@geekmidas/cache": "^9.1.0",
+    "@geekmidas/audit": "^9.1.0",
+    "@geekmidas/db": "^9.1.0",
+    "@geekmidas/envkit": "^9.1.0",
+    "@geekmidas/errors": "^9.1.0",
+    "@geekmidas/events": "^9.1.0",
+    "@geekmidas/rate-limit": "^9.1.0",
+    "@geekmidas/schema": "^9.1.0",
+    "@geekmidas/logger": "^9.1.0",
+    "@geekmidas/services": "^9.1.0",
+    "@geekmidas/testkit": "^9.1.0"
   },
   "peerDependencies": {
     "@middy/core": ">=6.3.1",
     "@types/aws-lambda": ">=8.10.92",
     "hono": ">=4.8.2",
     "msw": ">=2.0.0",
-    "@geekmidas/audit": "^9.0.2",
-    "@geekmidas/cache": "^9.0.2",
-    "@geekmidas/db": "^9.0.2",
-    "@geekmidas/envkit": "^9.0.2",
-    "@geekmidas/errors": "^9.0.2",
-    "@geekmidas/events": "^9.0.2",
-    "@geekmidas/logger": "^9.0.2",
-    "@geekmidas/rate-limit": "^9.0.2",
-    "@geekmidas/schema": "^9.0.2",
-    "@geekmidas/services": "^9.0.2"
+    "@geekmidas/audit": "^9.1.0",
+    "@geekmidas/cache": "^9.1.0",
+    "@geekmidas/db": "^9.1.0",
+    "@geekmidas/envkit": "^9.1.0",
+    "@geekmidas/errors": "^9.1.0",
+    "@geekmidas/events": "^9.1.0",
+    "@geekmidas/logger": "^9.1.0",
+    "@geekmidas/rate-limit": "^9.1.0",
+    "@geekmidas/schema": "^9.1.0",
+    "@geekmidas/services": "^9.1.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/audit": {

package/src/Construct.ts

@@ -9,6 +9,7 @@ import type { Logger } from '@geekmidas/logger';
 import type { Service, ServiceContext } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import compact from 'lodash.compact';
+import type { MonitorService } from './monitor';
 
 // Cache for service environment variables to handle singleton services
 // Stores both the full list and the optional subset so the same sniff result
@@ -60,6 +61,9 @@ export abstract class Construct<
 	/** Database service for this construct (used by Endpoint for RLS/audit context) */
 	public databaseService?: Service<TDatabaseServiceName, TDatabase>;
 
+	/** Monitors told about each run of this construct (see `.monitor()`). */
+	public monitors: MonitorService[] = [];
+
 	constructor(
 		public readonly type: ConstructType,
 		public readonly logger: TLogger,
@@ -111,6 +115,7 @@ export abstract class Construct<
 			this.publisherService,
 			this.auditorStorageService,
 			this.databaseService,
+			...this.monitors,
 		]);
 
 		try {

package/src/__tests__/builder-reuse.spec.ts

@@ -0,0 +1,587 @@
+/**
+ * Builder reuse: a configured base works, and nothing crosses between chains.
+ *
+ * Two properties, asserted for every field on every builder that carries state.
+ *
+ * **Persistence** — `const base = c.logger(log).timeout(60_000)` keeps its
+ * configuration for every construct built from it. It used to survive exactly
+ * one `.handle()`: the reset block at the end put every field back to its
+ * default, so the second cron silently came back on the console logger and
+ * the default timeout.
+ *
+ * **Isolation** — two chains off one base get only what each declared. They
+ * used to be the same object, so a chain's function came out holding the other
+ * chain's services too.
+ *
+ * Table-driven because the two properties are the same question asked of every
+ * field, and the failure mode being guarded against is precisely a field nobody
+ * remembered to handle.
+ */
+
+import type { AuditStorage } from '@geekmidas/audit';
+import type { EventPublisher } from '@geekmidas/events';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import type { Service } from '@geekmidas/services';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { CronBuilder } from '../crons/CronBuilder';
+import { EndpointBuilder } from '../endpoints/EndpointBuilder';
+import { FunctionBuilder } from '../functions/FunctionBuilder';
+import { QueueBuilder } from '../queue/QueueBuilder';
+import { SubscriberBuilder } from '../subscribers/SubscriberBuilder';
+import { TopicBuilder } from '../topic/TopicBuilder';
+
+const serviceA = {
+	serviceName: 'a' as const,
+	async register() {
+		return {};
+	},
+};
+const serviceB = {
+	serviceName: 'b' as const,
+	async register() {
+		return {};
+	},
+};
+
+const loggerA = new ConsoleLogger({ which: 'a' });
+const loggerB = new ConsoleLogger({ which: 'b' });
+
+const schemaA = z.object({ a: z.string() });
+const schemaB = z.object({ b: z.string() });
+
+const publisherA = {
+	serviceName: 'pa' as const,
+	async register() {
+		return {} as EventPublisher<any>;
+	},
+};
+const publisherB = {
+	serviceName: 'pb' as const,
+	async register() {
+		return {} as EventPublisher<any>;
+	},
+};
+
+const auditA = {
+	serviceName: 'aa' as const,
+	async register() {
+		return {} as AuditStorage;
+	},
+};
+const auditB = {
+	serviceName: 'ab' as const,
+	async register() {
+		return {} as AuditStorage;
+	},
+};
+
+const dbA = {
+	serviceName: 'da' as const,
+	async register() {
+		return {};
+	},
+};
+const dbB = {
+	serviceName: 'db' as const,
+	async register() {
+		return {};
+	},
+};
+
+const topicA = new TopicBuilder()
+	.topic('alpha')
+	.events({ 'a.one': z.object({}) });
+const topicB = new TopicBuilder()
+	.topic('beta')
+	.events({ 'b.one': z.object({}) });
+
+/** One field: how to set it, and how to read it back off what was built. */
+interface Field<B> {
+	name: string;
+	a: unknown;
+	b: unknown;
+	set: (builder: B, value: any) => B;
+	get: (built: any) => unknown;
+}
+
+function reusable<B>(
+	label: string,
+	fresh: () => B,
+	build: (builder: B) => unknown,
+	fields: Field<B>[],
+) {
+	describe(label, () => {
+		for (const field of fields) {
+			it(`${field.name} — persists across builds off one base`, () => {
+				const base = field.set(fresh(), field.a);
+
+				// Built twice from the same base, with no clone in between: the
+				// terminal call must read the builder without resetting it.
+				expect(field.get(build(base))).toEqual(field.a);
+				expect(field.get(build(base))).toEqual(field.a);
+			});
+
+			it(`${field.name} — does not cross between chains off one base`, () => {
+				const base = fresh();
+				const one = field.set(base, field.a);
+				const two = field.set(base, field.b);
+
+				expect(field.get(build(one))).toEqual(field.a);
+				expect(field.get(build(two))).toEqual(field.b);
+			});
+
+			it(`${field.name} — leaves the base it was set on untouched`, () => {
+				const base = fresh();
+				const untouched = field.get(build(base));
+
+				field.set(base, field.a);
+
+				expect(field.get(build(base))).toEqual(untouched);
+			});
+		}
+	});
+}
+
+const names = (services: readonly Service[]) =>
+	services.map((s) => s.serviceName);
+
+reusable(
+	'FunctionBuilder',
+	() => new FunctionBuilder(),
+	(b) => b.handle(async () => null),
+	[
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (f) => f.logger,
+		},
+		{
+			name: 'timeout',
+			a: 1000,
+			b: 2000,
+			set: (b, v) => b.timeout(v),
+			get: (f) => f.timeout,
+		},
+		{
+			name: 'memorySize',
+			a: 128,
+			b: 256,
+			set: (b, v) => b.memorySize(v),
+			get: (f) => f.memorySize,
+		},
+		{
+			name: 'services',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.services([v[0] === 'a' ? serviceA : serviceB]),
+			get: (f) => names(f.services),
+		},
+		{
+			name: 'input',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.input(v),
+			get: (f) => f.input,
+		},
+		{
+			name: 'output',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.output(v),
+			get: (f) => f.outputSchema,
+		},
+		{
+			name: 'publisher',
+			a: publisherA,
+			b: publisherB,
+			set: (b, v) => b.publisher(v),
+			get: (f) => f.publisherService,
+		},
+		{
+			name: 'auditor',
+			a: auditA,
+			b: auditB,
+			set: (b, v) => b.auditor(v),
+			get: (f) => f.auditorStorageService,
+		},
+		{
+			name: 'database',
+			a: dbA,
+			b: dbB,
+			set: (b, v) => b.database(v),
+			get: (f) => f.databaseService,
+		},
+		// Accumulating, like services: each chain adds its own, so isolation
+		// means each holds only what it added — not that one holds more.
+		{
+			name: 'event',
+			a: ['ea'],
+			b: ['eb'],
+			set: (b, v) => b.event({ type: v[0] } as any),
+			get: (f) => f.events.map((e: any) => e.type),
+		},
+	] as Field<any>[],
+);
+
+reusable(
+	'CronBuilder',
+	() => new CronBuilder(),
+	(b) => b.handle(async () => null),
+	[
+		{
+			name: 'schedule',
+			a: 'rate(1 day)',
+			b: 'rate(2 days)',
+			set: (b, v) => b.schedule(v),
+			get: (c) => c.schedule,
+		},
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (c) => c.logger,
+		},
+		{
+			name: 'timeout',
+			a: 1000,
+			b: 2000,
+			set: (b, v) => b.timeout(v),
+			get: (c) => c.timeout,
+		},
+		{
+			name: 'memorySize',
+			a: 128,
+			b: 256,
+			set: (b, v) => b.memorySize(v),
+			get: (c) => c.memorySize,
+		},
+		{
+			name: 'services',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.services([v[0] === 'a' ? serviceA : serviceB]),
+			get: (c) => names(c.services),
+		},
+		{
+			name: 'input',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.input(v),
+			get: (c) => c.input,
+		},
+		{
+			name: 'output',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.output(v),
+			get: (c) => c.outputSchema,
+		},
+		{
+			name: 'publisher',
+			a: publisherA,
+			b: publisherB,
+			set: (b, v) => b.publisher(v),
+			get: (c) => c.publisherService,
+		},
+		{
+			name: 'database',
+			a: dbA,
+			b: dbB,
+			set: (b, v) => b.database(v),
+			get: (c) => c.databaseService,
+		},
+		{
+			name: 'event',
+			a: ['ea'],
+			b: ['eb'],
+			set: (b, v) => b.event({ type: v[0] } as any),
+			get: (c) => c.events.map((e: any) => e.type),
+		},
+	] as Field<any>[],
+);
+
+reusable(
+	'QueueBuilder',
+	() => new QueueBuilder().queue('base').message(z.object({})),
+	(b) => b.handle(async () => {}),
+	[
+		{
+			name: 'queue',
+			a: 'alpha',
+			b: 'beta',
+			set: (b, v) => b.queue(v),
+			get: (q) => q.name,
+		},
+		{
+			name: 'message',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.message(v),
+			get: (q) => q.messageSchema,
+		},
+		{
+			name: 'timeout',
+			a: 1000,
+			b: 2000,
+			set: (b, v) => b.timeout(v),
+			get: (q) => q.timeout,
+		},
+		{
+			name: 'batchSize',
+			a: 5,
+			b: 10,
+			set: (b, v) => b.batchSize(v),
+			get: (q) => q.batchSize,
+		},
+		{
+			name: 'fifo',
+			a: true,
+			b: false,
+			set: (b, v) => b.fifo(v),
+			get: (q) => q.fifo,
+		},
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (q) => q.logger,
+		},
+		{
+			name: 'services',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.services([v[0] === 'a' ? serviceA : serviceB]),
+			get: (q) => names(q.services),
+		},
+	] as Field<any>[],
+);
+
+reusable(
+	'SubscriberBuilder',
+	() => new SubscriberBuilder(),
+	(b) => b.handle(async () => null),
+	[
+		{
+			name: 'topic',
+			a: 'alpha',
+			b: 'beta',
+			set: (b, v) => b.topic(v === 'alpha' ? topicA : topicB),
+			get: (s) => s.topicName,
+		},
+		{
+			name: 'timeout',
+			a: 1000,
+			b: 2000,
+			set: (b, v) => b.timeout(v),
+			get: (s) => s.timeout,
+		},
+		{
+			name: 'output',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.output(v),
+			get: (s) => s.outputSchema,
+		},
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (s) => s.logger,
+		},
+		{
+			name: 'publisher',
+			a: publisherA,
+			b: publisherB,
+			set: (b, v) => b.publisher(v),
+			get: (s) => s.publisherService,
+		},
+		{
+			name: 'services',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.services([v[0] === 'a' ? serviceA : serviceB]),
+			get: (s) => names(s.services),
+		},
+		{
+			name: 'subscribe',
+			a: ['ea'],
+			b: ['eb'],
+			set: (b, v) => b.subscribe(v[0]),
+			get: (s) => s.subscribedEvents,
+		},
+	] as Field<any>[],
+);
+
+reusable(
+	'TopicBuilder',
+	// `.events()` is the terminal call and needs a name, so the base carries one.
+	() => new TopicBuilder().topic('base'),
+	(b) => b.events({ 'a.one': z.object({}) }),
+	[
+		{
+			name: 'topic',
+			a: 'alpha',
+			b: 'beta',
+			set: (b, v) => b.topic(v),
+			get: (t) => t.name,
+		},
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (t) => t.logger,
+		},
+	] as Field<any>[],
+);
+
+// Endpoints are usually built fresh per route by `EndpointFactory`, but a
+// builder can still be shared — `const base = e.post('/x').services([db])` —
+// and `body`/`query`/`params` used to write into one `schemas` object that
+// every clone of the base pointed at.
+reusable(
+	'EndpointBuilder',
+	() => new EndpointBuilder('/users', 'POST'),
+	(b) => b.handle(async () => ({})),
+	[
+		{
+			name: 'description',
+			a: 'one',
+			b: 'two',
+			set: (b, v) => b.description(v),
+			get: (e) => e.description,
+		},
+		{
+			name: 'status',
+			a: 201,
+			b: 202,
+			set: (b, v) => b.status(v),
+			get: (e) => e.status,
+		},
+		{
+			name: 'tags',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.tags(v),
+			get: (e) => e.tags,
+		},
+		{
+			name: 'memorySize',
+			a: 128,
+			b: 256,
+			set: (b, v) => b.memorySize(v),
+			get: (e) => e.memorySize,
+		},
+		{
+			name: 'timeout',
+			a: 1000,
+			b: 2000,
+			set: (b, v) => b.timeout(v),
+			get: (e) => e.timeout,
+		},
+		{
+			name: 'responseType',
+			a: 'text/plain',
+			b: 'text/csv',
+			set: (b, v) => b.responseType(v),
+			get: (e) => e.responseType,
+		},
+		{
+			name: 'body',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.body(v),
+			get: (e) => e.input?.body,
+		},
+		{
+			name: 'query',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.query(v),
+			get: (e) => e.input?.query,
+		},
+		{
+			name: 'params',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.params(v),
+			get: (e) => e.input?.params,
+		},
+		{
+			name: 'output',
+			a: schemaA,
+			b: schemaB,
+			set: (b, v) => b.output(v),
+			get: (e) => e.outputSchema,
+		},
+		{
+			name: 'logger',
+			a: loggerA,
+			b: loggerB,
+			set: (b, v) => b.logger(v),
+			get: (e) => e.logger,
+		},
+		{
+			name: 'services',
+			a: ['a'],
+			b: ['b'],
+			set: (b, v) => b.services([v[0] === 'a' ? serviceA : serviceB]),
+			get: (e) => names(e.services),
+		},
+		{
+			name: 'publisher',
+			a: publisherA,
+			b: publisherB,
+			set: (b, v) => b.publisher(v),
+			get: (e) => e.publisherService,
+		},
+		{
+			name: 'event',
+			a: ['ea'],
+			b: ['eb'],
+			set: (b, v) => b.event({ type: v[0] } as any),
+			get: (e) => e.events.map((ev: any) => ev.type),
+		},
+		{
+			name: 'auditor',
+			a: auditA,
+			b: auditB,
+			set: (b, v) => b.auditor(v),
+			get: (e) => e.auditorStorageService,
+		},
+		{
+			name: 'audit',
+			a: [{ type: 'a' }],
+			b: [{ type: 'b' }],
+			set: (b, v) => b.audit(v),
+			get: (e) => e.audits,
+		},
+		{
+			name: 'database',
+			a: dbA,
+			b: dbB,
+			set: (b, v) => b.database(v),
+			get: (e) => e.databaseService,
+		},
+		{
+			name: 'rateLimit',
+			a: { limit: 1, windowMs: 1000 },
+			b: { limit: 2, windowMs: 1000 },
+			set: (b, v) => b.rateLimit(v),
+			get: (e) => e.rateLimit,
+		},
+		{
+			name: 'rls',
+			a: { bypass: true, config: undefined },
+			b: { bypass: false, config: { prefix: 'b' } },
+			set: (b, v) => b.rls(v.bypass ? false : v.config),
+			get: (e) => ({ bypass: e.rlsBypass === true, config: e.rlsConfig }),
+		},
+	] as Field<any>[],
+);