@geekmidas/constructs 4.0.1 → 5.0.0

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',

package/dist/Subscriber-C0v9iOrI.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Subscriber-C0v9iOrI.d.mts","names":[],"sources":["../src/subscribers/Subscriber.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/Subscriber-C6YXAmTp.d.cts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Subscriber-C6YXAmTp.d.cts","names":[],"sources":["../src/subscribers/Subscriber.ts"],"sourcesContent":[],"mappings":"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"}