@geekmidas/constructs 4.0.0 → 5.0.0

package/src/queue/QueueBuilder.ts

@@ -0,0 +1,115 @@
+import type { Logger } from '@geekmidas/logger';
+import { DEFAULT_LOGGER } from '@geekmidas/logger/console';
+import type { Service } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Queue, type QueueHandler } from './Queue';
+
+/**
+ * Builds a {@link Queue} worker — `q.queue('orders').services([db]).message(schema).handle(fn)`.
+ * Services are an array (sniffed for required env vars); `message` is the typed
+ * job payload; `handle` is the single consumer. The queue name is captured as a
+ * literal so `queue.publisher` is typed to `{ type: '<name>', payload }`.
+ */
+export class QueueBuilder<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 | undefined = undefined,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> {
+	private _name?: string;
+	private _messageSchema?: TMessage;
+	private _timeout = 30000;
+	private _batchSize?: number;
+	private _fifo?: boolean;
+	private _services: TServices = [] as Service[] as TServices;
+	private _logger: TLogger = DEFAULT_LOGGER as TLogger;
+
+	/** The queue name — drives the infra queue and its `<NAME>_*` env vars. */
+	queue<T extends string>(
+		name: T,
+	): QueueBuilder<T, TMessage, TServices, TLogger> {
+		this._name = name;
+		return this as unknown as QueueBuilder<T, TMessage, TServices, TLogger>;
+	}
+
+	timeout(timeout: number): this {
+		this._timeout = timeout;
+		return this;
+	}
+
+	/** SQS event-source batch size (deployed). */
+	batchSize(batchSize: number): this {
+		this._batchSize = batchSize;
+		return this;
+	}
+
+	/** Mark the queue as FIFO (deployed). */
+	fifo(fifo = true): this {
+		this._fifo = fifo;
+		return this;
+	}
+
+	services<T extends Service[]>(
+		services: T,
+	): QueueBuilder<TName, TMessage, [...TServices, ...T], TLogger> {
+		this._services = [...this._services, ...services] as unknown as TServices;
+		return this as unknown as QueueBuilder<
+			TName,
+			TMessage,
+			[...TServices, ...T],
+			TLogger
+		>;
+	}
+
+	logger<T extends Logger>(
+		logger: T,
+	): QueueBuilder<TName, TMessage, TServices, T> {
+		this._logger = logger as unknown as TLogger;
+		return this as unknown as QueueBuilder<TName, TMessage, TServices, T>;
+	}
+
+	/** The typed message (job) payload the queue carries. */
+	message<T extends StandardSchemaV1>(
+		schema: T,
+	): QueueBuilder<TName, T, TServices, TLogger> {
+		this._messageSchema = schema as unknown as TMessage;
+		return this as unknown as QueueBuilder<TName, T, TServices, TLogger>;
+	}
+
+	handle(
+		fn: QueueHandler<NonNullable<TMessage>, TServices, TLogger>,
+	): Queue<TName, NonNullable<TMessage>, TServices, TLogger> {
+		if (!this._name) {
+			throw new Error(
+				'Queue requires a name — call .queue(name) before .handle().',
+			);
+		}
+		if (!this._messageSchema) {
+			throw new Error(
+				'Queue requires a message schema — call .message(schema) before .handle().',
+			);
+		}
+
+		const queue = new Queue<TName, NonNullable<TMessage>, TServices, TLogger>(
+			this._name as TName,
+			fn,
+			this._messageSchema as NonNullable<TMessage>,
+			this._timeout,
+			this._services,
+			this._logger,
+			this._batchSize,
+			this._fifo,
+		);
+
+		// Reset builder state to prevent pollution across reuse.
+		this._name = undefined;
+		this._messageSchema = undefined;
+		this._timeout = 30000;
+		this._batchSize = undefined;
+		this._fifo = undefined;
+		this._services = [] as Service[] as TServices;
+		this._logger = DEFAULT_LOGGER as TLogger;
+
+		return queue;
+	}
+}

package/src/queue/TestQueueAdaptor.ts

@@ -0,0 +1,63 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import type { Logger } from '@geekmidas/logger';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import { runWithRequestContext, ServiceDiscovery } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Queue } from './Queue';
+
+/**
+ * In-memory test driver for a {@link Queue} worker. Hand it a batch of messages
+ * and it registers the queue's services, runs the handler in a request context,
+ * and returns the handler result — no SQS/pg-boss required.
+ *
+ * @example
+ * const adapter = new TestQueueAdaptor(ordersQueue);
+ * await adapter.invoke({ messages: [{ orderId: '123' }] });
+ */
+export class TestQueueAdaptor<
+	TName extends string = string,
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+	TLogger extends Logger = Logger,
+> {
+	static getDefaultServiceDiscovery() {
+		return ServiceDiscovery.getInstance(new EnvironmentParser({}));
+	}
+
+	constructor(
+		private readonly queue: Queue<TName, TMessage, TServices, TLogger>,
+		private serviceDiscovery: ServiceDiscovery<any> = TestQueueAdaptor.getDefaultServiceDiscovery(),
+	) {}
+
+	async invoke(
+		request: TestQueueRequest<TMessage, TServices>,
+	): Promise<unknown> {
+		const logger = this.queue.logger.child({ test: true }) as TLogger;
+
+		const services =
+			request.services ??
+			((await this.serviceDiscovery.register(
+				this.queue.services,
+			)) as ServiceRecord<TServices>);
+
+		const requestId = `test-${Date.now()}`;
+		const startTime = Date.now();
+
+		return runWithRequestContext({ logger, requestId, startTime }, () =>
+			this.queue.handler({
+				messages: request.messages,
+				services,
+				logger,
+			}),
+		);
+	}
+}
+
+export type TestQueueRequest<
+	TMessage extends StandardSchemaV1 = StandardSchemaV1,
+	TServices extends Service[] = [],
+> = {
+	messages: InferStandardSchema<TMessage>[];
+	services?: ServiceRecord<TServices>;
+};

package/src/queue/__tests__/QueueBuilder.spec.ts

@@ -0,0 +1,137 @@
+import type { Service } from '@geekmidas/services';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { Queue } from '../Queue';
+import { QueueBuilder } from '../QueueBuilder';
+import { TestQueueAdaptor } from '../TestQueueAdaptor';
+
+const schema = z.object({ orderId: z.string() });
+
+const svc = (name: string): Service<string, object> => ({
+	serviceName: name,
+	async register() {
+		return {};
+	},
+});
+
+describe('QueueBuilder', () => {
+	it('builds a Queue from .queue().message().handle()', () => {
+		const handler = async () => {};
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.message(schema)
+			.handle(handler);
+
+		expect(Queue.isQueue(queue)).toBe(true);
+		expect(queue.name).toBe('orders');
+		expect(queue.messageSchema).toBe(schema);
+		expect(queue.handler).toBe(handler);
+		expect(queue.services).toEqual([]);
+	});
+
+	it('collects services as an array', () => {
+		const a = svc('a');
+		const queue = new QueueBuilder()
+			.queue('jobs')
+			.services([a])
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.services).toEqual([a]);
+	});
+
+	it('captures batchSize and fifo', () => {
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.batchSize(5)
+			.fifo()
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.batchSize).toBe(5);
+		expect(queue.fifo).toBe(true);
+	});
+
+	it('throws when the name is missing', () => {
+		expect(() =>
+			new QueueBuilder().message(schema).handle(async () => {}),
+		).toThrow(/name/);
+	});
+
+	it('throws when the message schema is missing', () => {
+		const builder = new QueueBuilder().queue('x');
+		expect(() =>
+			(builder as QueueBuilder<'x', typeof schema>).handle(async () => {}),
+		).toThrow(/message/);
+	});
+
+	it('resets builder state after handle', () => {
+		const builder = new QueueBuilder();
+		builder
+			.queue('first')
+			.services([svc('x')])
+			.message(schema)
+			.handle(async () => {});
+		// State cleared — a second handle with no name throws.
+		expect(() =>
+			(builder as QueueBuilder<string, typeof schema>).handle(async () => {}),
+		).toThrow(/name/);
+	});
+});
+
+describe('Queue.publisher', () => {
+	it('exposes a `<name>Publisher` producer service', () => {
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.message(schema)
+			.handle(async () => {});
+
+		expect(queue.publisher.serviceName).toBe('ordersPublisher');
+	});
+
+	it('requires the namespaced connection-string env var (sniffed into the manifest)', async () => {
+		const producer = new QueueBuilder()
+			.queue('orderEvents')
+			.message(schema)
+			.handle(async () => {});
+
+		// Inject the publisher into a construct's services so getEnvironment sniffs it.
+		const consumer = new QueueBuilder()
+			.queue('caller')
+			.services([producer.publisher])
+			.message(schema)
+			.handle(async () => {});
+
+		const env = await consumer.getEnvironment();
+		expect(env).toContain('ORDER_EVENTS_PUBLISHER_CONNECTION_STRING');
+	});
+});
+
+describe('TestQueueAdaptor', () => {
+	it('invokes the handler with the batch of messages and services', async () => {
+		const seen: { messages: unknown[]; hadDb: boolean }[] = [];
+		const db = svc('db');
+
+		const queue = new QueueBuilder()
+			.queue('orders')
+			.services([db])
+			.message(schema)
+			.handle(async ({ messages, services }) => {
+				seen.push({
+					messages,
+					hadDb: 'db' in (services as Record<string, unknown>),
+				});
+				return { processed: messages.length };
+			});
+
+		const adapter = new TestQueueAdaptor(queue);
+		const result = await adapter.invoke({
+			messages: [{ orderId: '1' }, { orderId: '2' }],
+		});
+
+		expect(result).toEqual({ processed: 2 });
+		expect(seen).toHaveLength(1);
+		expect(seen[0]?.messages).toEqual([{ orderId: '1' }, { orderId: '2' }]);
+		expect(seen[0]?.hadDb).toBe(true);
+	});
+});

package/src/queue/index.ts

@@ -0,0 +1,12 @@
+export {
+	Queue,
+	type QueueContext,
+	type QueueHandler,
+	type QueueMessage,
+} from './Queue';
+
+import { QueueBuilder } from './QueueBuilder';
+
+export { QueueBuilder } from './QueueBuilder';
+
+export const q = new QueueBuilder();

package/src/subscribers/Subscriber.ts

@@ -63,6 +63,13 @@ export class Subscriber<
 			TEventPublisherServiceName,
 			TEventPublisher
 		>,
+		/**
+		 * The name of the {@link Topic} this subscriber binds to (via
+		 * `s.topic(topic)`), recorded for the manifest so infra wires the SNS
+		 * subscription. Undefined when the subscriber's events are typed from a
+		 * (hand-written) publisher instead.
+		 */
+		public readonly topicName?: string,
 	) {
 		super(
 			ConstructType.Subscriber,

package/src/subscribers/SubscriberBuilder.ts

@@ -6,6 +6,7 @@ import type { Logger } from '@geekmidas/logger';
 import { DEFAULT_LOGGER } from '@geekmidas/logger/console';
 import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Topic, TopicEvents, TopicMessage } from '../topic/Topic';
 import { Subscriber, type SubscriberHandler } from './Subscriber';
 
 export class SubscriberBuilder<
@@ -22,11 +23,44 @@ export class SubscriberBuilder<
 	private _services: TServices = [] as Service[] as TServices;
 	private _logger: TLogger = DEFAULT_LOGGER;
 	private _publisher?: Service<TEventPublisherServiceName, TEventPublisher>;
+	private _topicName?: string;
 
 	constructor() {
 		this._timeout = 30000; // Default timeout
 	}
 
+	/**
+	 * Bind this subscriber to a {@link Topic} — the preferred way to type and wire
+	 * a fan-out consumer. It supplies the subscribable event types (and their
+	 * payloads) from the topic's contract and records the binding for the manifest,
+	 * so infra wires the SNS subscription.
+	 *
+	 * Prefer this over typing via a hand-written publisher service: a consumer does
+	 * not publish, so binding a topic does *not* require the topic's publisher
+	 * connection string (least privilege). Use `.publisher(...)` only when the
+	 * subscriber actually publishes follow-up events.
+	 */
+	topic<TName extends string, TEvents extends TopicEvents>(
+		topic: Topic<TName, TEvents>,
+	): SubscriberBuilder<
+		TServices,
+		TLogger,
+		OutSchema,
+		EventPublisher<TopicMessage<TEvents>>,
+		TEventPublisherServiceName,
+		TSubscribedEvents
+	> {
+		this._topicName = topic.name;
+		return this as unknown as SubscriberBuilder<
+			TServices,
+			TLogger,
+			OutSchema,
+			EventPublisher<TopicMessage<TEvents>>,
+			TEventPublisherServiceName,
+			TSubscribedEvents
+		>;
+	}
+
 	timeout(timeout: number): this {
 		this._timeout = timeout;
 		return this;
@@ -135,12 +169,14 @@ export class SubscriberBuilder<
 			this._services,
 			this._logger,
 			this._publisher,
+			this._topicName,
 		);
 
 		// Reset builder state after creating the subscriber to prevent pollution
 		this._services = [] as Service[] as TServices;
 		this._logger = DEFAULT_LOGGER;
 		this._publisher = undefined;
+		this._topicName = undefined;
 		this._subscribedEvents = [] as any;
 		this._timeout = 30000; // Reset to default
 		this.outputSchema = undefined;

package/src/topic/Topic.ts

@@ -0,0 +1,103 @@
+import { environmentCase } from '@geekmidas/envkit';
+import {
+	type EventPublisher,
+	type EventPublisherConnectionString,
+	type PublishableMessage,
+	Publisher,
+} from '@geekmidas/events';
+import type { Logger } from '@geekmidas/logger';
+import { ConsoleLogger } from '@geekmidas/logger/console';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { Construct, ConstructType } from '../Construct';
+
+const DEFAULT_LOGGER = new ConsoleLogger() as unknown as Logger;
+
+/** A topic's event contract — a map of event type → payload schema. */
+export type TopicEvents = Record<string, StandardSchemaV1>;
+
+/**
+ * The union of wire messages a topic carries, derived from its event map:
+ * `{ type: 'user.created'; payload: … } | { type: 'user.updated'; payload: … }`.
+ */
+export type TopicMessage<TEvents extends TopicEvents> = {
+	[K in keyof TEvents & string]: PublishableMessage<
+		K,
+		InferStandardSchema<TEvents[K]>
+	>;
+}[keyof TEvents & string];
+
+/**
+ * A topic — pub/sub fan-out. Unlike a `Queue` (point-to-point, one consumer), a
+ * topic is a *resource* owned by no single handler: it declares the event
+ * contract, derives a typed producer (`topic.publisher`), and any number of
+ * subscribers (`s.topic(topic)`) bind to it. `gkm build` discovers it into the
+ * manifest's `topics` field; infra provisions an SNS topic.
+ *
+ * This replaces hand-writing a publisher `Service`: the publisher is *derived*
+ * from the declared event contract, the same way `Queue` derives its publisher.
+ */
+export class Topic<
+	TName extends string = string,
+	TEvents extends TopicEvents = TopicEvents,
+> extends Construct {
+	__IS_TOPIC__ = true;
+
+	static isTopic(obj: unknown): obj is Topic<string, TopicEvents> {
+		return Boolean(
+			obj &&
+				(obj as { __IS_TOPIC__?: boolean }).__IS_TOPIC__ === true &&
+				(obj as Construct).type === ConstructType.Topic,
+		);
+	}
+
+	constructor(
+		public readonly name: TName,
+		/**
+		 * The event contract — a map of event type → payload schema. Named
+		 * `eventSchemas` (not `events`) to avoid clashing with `Construct.events`,
+		 * which is the array of `MappedEvent`s a construct *publishes*.
+		 */
+		public readonly eventSchemas: TEvents,
+		logger: Logger = DEFAULT_LOGGER,
+	) {
+		super(ConstructType.Topic, logger, [], []);
+	}
+
+	/** The event type names this topic carries. */
+	get eventTypes(): (keyof TEvents & string)[] {
+		return Object.keys(this.eventSchemas) as (keyof TEvents & string)[];
+	}
+
+	/**
+	 * The producer side — a `Service` exposing an `EventPublisher` typed to the
+	 * union of this topic's events. Inject via `.publisher(topic.publisher)` (for
+	 * declarative `.event(...)`) or `.services([topic.publisher])` (to publish
+	 * imperatively). Reads `<NAME>_PUBLISHER_CONNECTION_STRING` and selects the
+	 * transport from the URL protocol — `pgboss://` locally, `sns://` deployed.
+	 *
+	 * Because it's a `Service`, the connection-string requirement is sniffed into
+	 * the manifest of whatever construct injects it (least-privilege linking).
+	 */
+	get publisher(): Service<
+		`${TName}Publisher`,
+		EventPublisher<TopicMessage<TEvents>>
+	> {
+		const envVar = `${environmentCase(this.name)}_PUBLISHER_CONNECTION_STRING`;
+		return {
+			serviceName: `${this.name}Publisher`,
+			async register({ envParser }) {
+				const { connectionString } = envParser
+					.create((get) => ({
+						connectionString: get(envVar).string(),
+					}))
+					.parse();
+
+				return Publisher.fromConnectionString<TopicMessage<TEvents>>(
+					connectionString as EventPublisherConnectionString,
+				);
+			},
+		};
+	}
+}

package/src/topic/TopicBuilder.ts

@@ -0,0 +1,51 @@
+import type { Logger } from '@geekmidas/logger';
+import { DEFAULT_LOGGER } from '@geekmidas/logger/console';
+import { Topic, type TopicEvents } from './Topic';
+
+/**
+ * Builds a {@link Topic} — `t.topic('users').events({ 'user.created': schema, … })`.
+ * The event map is the topic's contract: it types the derived `topic.publisher`
+ * and the subscribers that bind via `s.topic(topic)`.
+ */
+export class TopicBuilder<
+	TName extends string = string,
+	TEvents extends TopicEvents = TopicEvents,
+> {
+	private _name?: string;
+	private _logger: Logger = DEFAULT_LOGGER;
+
+	/** The topic name — drives the infra topic and its `<NAME>_*` env vars. */
+	topic<T extends string>(name: T): TopicBuilder<T, TEvents> {
+		this._name = name;
+		return this as unknown as TopicBuilder<T, TEvents>;
+	}
+
+	logger(logger: Logger): this {
+		this._logger = logger;
+		return this;
+	}
+
+	/**
+	 * The event contract — a map of event type → payload schema. Building the
+	 * topic requires this; it's what types the publisher and subscribers.
+	 */
+	events<T extends TopicEvents>(events: T): Topic<TName, T> {
+		if (!this._name) {
+			throw new Error(
+				'Topic requires a name — call .topic(name) before .events().',
+			);
+		}
+
+		const topic = new Topic<TName, T>(
+			this._name as TName,
+			events,
+			this._logger,
+		);
+
+		// Reset builder state to prevent pollution across reuse.
+		this._name = undefined;
+		this._logger = DEFAULT_LOGGER;
+
+		return topic;
+	}
+}

package/src/topic/__tests__/TopicBuilder.spec.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { s } from '../../subscribers';
+import { Topic } from '../Topic';
+import { TopicBuilder } from '../TopicBuilder';
+
+const events = {
+	'user.created': z.object({ userId: z.string(), email: z.string() }),
+	'user.updated': z.object({
+		userId: z.string(),
+		changes: z.array(z.string()),
+	}),
+};
+
+describe('TopicBuilder', () => {
+	it('builds a Topic from .topic().events()', () => {
+		const topic = new TopicBuilder().topic('users').events(events);
+
+		expect(Topic.isTopic(topic)).toBe(true);
+		expect(topic.name).toBe('users');
+		expect(topic.eventSchemas).toBe(events);
+		expect(topic.eventTypes.sort()).toEqual(['user.created', 'user.updated']);
+	});
+
+	it('throws when the name is missing', () => {
+		expect(() => new TopicBuilder().events(events)).toThrow(/name/);
+	});
+
+	it('resets builder state after events()', () => {
+		const builder = new TopicBuilder();
+		builder.topic('first').events(events);
+		expect(() => builder.events(events)).toThrow(/name/);
+	});
+});
+
+describe('Topic.publisher', () => {
+	it('exposes a `<name>Publisher` producer service', () => {
+		const topic = new TopicBuilder().topic('users').events(events);
+		expect(topic.publisher.serviceName).toBe('usersPublisher');
+	});
+
+	it('requires the namespaced connection-string env var when injected', async () => {
+		const topic = new TopicBuilder().topic('userEvents').events(events);
+
+		// A construct that injects the publisher (a producer) requires its env var.
+		const producer = s
+			.services([topic.publisher])
+			.subscribe('noop')
+			.handle(async () => {});
+
+		const env = await producer.getEnvironment();
+		expect(env).toContain('USER_EVENTS_PUBLISHER_CONNECTION_STRING');
+	});
+});
+
+describe('subscriber .topic() binding', () => {
+	it('binds the topic name and does NOT require the publisher env (least privilege)', async () => {
+		const topic = new TopicBuilder().topic('users').events(events);
+
+		const subscriber = s
+			.topic(topic)
+			.subscribe(['user.created', 'user.updated'])
+			.handle(async ({ events }) => {
+				// payloads are typed from the topic contract
+				for (const event of events) {
+					if (event.type === 'user.created') {
+						void event.payload.email;
+					}
+				}
+			});
+
+		expect(subscriber.topicName).toBe('users');
+		expect(subscriber.subscribedEvents).toEqual([
+			'user.created',
+			'user.updated',
+		]);
+
+		// A consumer does not publish, so binding a topic requires no publisher env.
+		const env = await subscriber.getEnvironment();
+		expect(env).not.toContain('USERS_PUBLISHER_CONNECTION_STRING');
+	});
+});

package/src/topic/index.ts

@@ -0,0 +1,11 @@
+export {
+	Topic,
+	type TopicEvents,
+	type TopicMessage,
+} from './Topic';
+
+import { TopicBuilder } from './TopicBuilder';
+
+export { TopicBuilder } from './TopicBuilder';
+
+export const t = new TopicBuilder();

package/tsdown.config.ts

@@ -8,6 +8,8 @@ export default defineConfig({
 		'src/functions/index.ts',
 		'src/crons/index.ts',
 		'src/subscribers/index.ts',
+		'src/queue/index.ts',
+		'src/topic/index.ts',
 		'src/adaptors/hono.ts',
 		'src/adaptors/aws.ts',
 		'src/adaptors/testing.ts',