@geekmidas/constructs 7.0.1 → 10.0.0-alpha.0

package/src/queue/AWSLambdaQueueAdaptor.ts

@@ -1,162 +0,0 @@
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import { wrapError } from '@geekmidas/errors';
-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 {
-	Context,
-	Handler,
-	SQSBatchResponse,
-	SQSEvent,
-	SQSRecord,
-} from 'aws-lambda';
-import type { Queue } from './Queue';
-
-export type AWSLambdaHandler<TEvent = any, TResult = any> = Handler<
-	TEvent,
-	TResult
->;
-
-/**
- * Runs a {@link Queue} worker as an AWS Lambda backed by an SQS event-source
- * mapping. Unlike a subscriber, a queue drains *every* record (no type filter):
- * each record body (`{ type, payload }`, as written by the SQS publisher) is
- * unwrapped to its `payload`, validated against the queue's `messageSchema`, and
- * the whole batch is handed to the handler as `messages`.
- *
- * Uses SQS partial-batch responses: a record that fails to parse, validate, or
- * (when the handler throws) process is returned in `batchItemFailures` so SQS
- * retries only those records.
- */
-export class AWSLambdaQueue<
-	TName extends string = string,
-	TMessage extends StandardSchemaV1 = StandardSchemaV1,
-	TServices extends Service[] = [],
-	TLogger extends Logger = Logger,
-> {
-	private _services?: ServiceRecord<TServices>;
-
-	constructor(
-		private readonly envParser: EnvironmentParser<{}>,
-		readonly queue: Queue<TName, TMessage, TServices, TLogger>,
-	) {}
-
-	get logger(): TLogger {
-		return this.queue.logger;
-	}
-
-	private async getServices(): Promise<ServiceRecord<TServices>> {
-		if (this._services) {
-			return this._services;
-		}
-
-		const serviceDiscovery = ServiceDiscovery.getInstance(this.envParser);
-
-		this._services =
-			this.queue.services.length > 0
-				? ((await serviceDiscovery.register(
-						this.queue.services,
-					)) as ServiceRecord<TServices>)
-				: ({} as ServiceRecord<TServices>);
-
-		return this._services;
-	}
-
-	private safeJsonParse(value: string): unknown {
-		try {
-			return JSON.parse(value);
-		} catch {
-			return null;
-		}
-	}
-
-	/**
-	 * Unwrap the queue payload from an SQS record. The SQS publisher writes
-	 * `{ type, payload }`; a payload-only body is also accepted as-is.
-	 */
-	private extractPayload(record: SQSRecord): unknown {
-		const body = this.safeJsonParse(record.body);
-		if (body && typeof body === 'object' && 'payload' in body) {
-			return (body as { payload: unknown }).payload;
-		}
-		return body ?? record.body;
-	}
-
-	private async _handler(
-		event: SQSEvent,
-		context: Context,
-	): Promise<SQSBatchResponse> {
-		const logger = this.queue.logger.child({
-			queue: {
-				name: this.queue.name,
-				fn: context.functionName,
-			},
-			req: { id: context.awsRequestId },
-		}) as TLogger;
-
-		const services = await this.getServices();
-		const schema = this.queue.messageSchema;
-
-		const batchItemFailures: { itemIdentifier: string }[] = [];
-		const messages: InferStandardSchema<TMessage>[] = [];
-
-		for (const record of event.Records) {
-			try {
-				const payload = this.extractPayload(record);
-				const validation = await schema['~standard'].validate(payload);
-				if (validation.issues) {
-					logger.error(
-						{ issues: validation.issues, messageId: record.messageId },
-						'Queue message failed validation',
-					);
-					batchItemFailures.push({ itemIdentifier: record.messageId });
-					continue;
-				}
-				messages.push(validation.value as InferStandardSchema<TMessage>);
-			} catch (error) {
-				logger.error(
-					{ error, messageId: record.messageId },
-					'Failed to parse SQS record',
-				);
-				batchItemFailures.push({ itemIdentifier: record.messageId });
-			}
-		}
-
-		if (messages.length === 0) {
-			return { batchItemFailures };
-		}
-
-		try {
-			await this.queue.handler({ messages, services, logger });
-		} catch (error) {
-			logger.error(wrapError(error), 'Queue handler failed; retrying batch');
-			// Handler processes the batch atomically — fail the whole batch so SQS
-			// retries every (valid) record.
-			for (const record of event.Records) {
-				if (
-					!batchItemFailures.some((f) => f.itemIdentifier === record.messageId)
-				) {
-					batchItemFailures.push({ itemIdentifier: record.messageId });
-				}
-			}
-		}
-
-		return { batchItemFailures };
-	}
-
-	get handler(): AWSLambdaHandler<SQSEvent, SQSBatchResponse> {
-		const handler = this._handler.bind(this);
-
-		return (async (event: SQSEvent, context: Context) => {
-			const startTime = Date.now();
-			const requestId = context.awsRequestId;
-			const logger = this.queue.logger.child({ requestId }) as TLogger;
-
-			return runWithRequestContext({ logger, requestId, startTime }, () =>
-				handler(event, context),
-			);
-		}) as unknown as AWSLambdaHandler<SQSEvent, SQSBatchResponse>;
-	}
-}

package/src/queue/Queue.ts

@@ -1,128 +0,0 @@
-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, ServiceRecord } from '@geekmidas/services';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { Construct, ConstructType } from '../Construct';
-
-const DEFAULT_LOGGER = new ConsoleLogger() as unknown as Logger;
-
-/**
- * The wire message a queue carries: `{ type: <queue name>, payload: <message> }`.
- * The producer publishes this shape and the worker receives the `payload`s as
- * its `messages`. Typing `type` to the queue name keeps the publisher fully
- * typed and lets pg-boss (local) / SQS (deployed) route by name.
- */
-export type QueueMessage<
-	TName extends string,
-	TMessage extends StandardSchemaV1,
-> = PublishableMessage<TName, InferStandardSchema<TMessage>>;
-
-/**
- * A queue worker — a point-to-point SQS-style queue and its single consumer.
- * Unlike a `Subscriber` (topic fan-out, filtered by `subscribedEvents`), a queue
- * drains every message of its one `message` type. Build one with `q` (see
- * `QueueBuilder`); `gkm build` discovers it into the manifest's `queues` field.
- *
- * The producer side is {@link Queue.publisher} — a ready-to-inject `Service`
- * that any endpoint/function drops into `.services([...])` to send messages.
- */
-export class Queue<
-	TName extends string = string,
-	TMessage extends StandardSchemaV1 = StandardSchemaV1,
-	TServices extends Service[] = [],
-	TLogger extends Logger = Logger,
-> extends Construct<TLogger, string, undefined, undefined, TServices> {
-	__IS_QUEUE__ = true;
-
-	static isQueue(
-		obj: unknown,
-	): obj is Queue<string, StandardSchemaV1, Service[], Logger> {
-		return Boolean(
-			obj &&
-				(obj as { __IS_QUEUE__?: boolean }).__IS_QUEUE__ === true &&
-				(obj as Construct).type === ConstructType.Queue,
-		);
-	}
-
-	constructor(
-		public readonly name: TName,
-		public readonly handler: QueueHandler<TMessage, TServices, TLogger>,
-		public readonly messageSchema: TMessage,
-		public override readonly timeout: number = 30000,
-		public override readonly services: TServices = [] as unknown as TServices,
-		public override readonly logger: TLogger = DEFAULT_LOGGER as TLogger,
-		/** SQS event-source batch size (deployed). */
-		public readonly batchSize?: number,
-		/** Whether the queue is FIFO (deployed). */
-		public readonly fifo?: boolean,
-	) {
-		super(
-			ConstructType.Queue,
-			logger,
-			services,
-			[],
-			undefined,
-			undefined,
-			timeout,
-		);
-	}
-
-	/**
-	 * The producer side — a `Service` exposing an `EventPublisher` typed to this
-	 * queue's message. Inject it via `.services([queue.publisher])`; the handler
-	 * then calls `services.<name>Publisher.publish([{ type, payload }])`.
-	 *
-	 * It reads `<NAME>_PUBLISHER_CONNECTION_STRING` and builds the transport from
-	 * the URL protocol — `pgboss://` locally, `sqs://` deployed — so the same
-	 * code publishes to Postgres in dev and SQS in prod. Because it's a `Service`,
-	 * `Construct.getEnvironment()` sniffs it, so the env requirement flows into
-	 * the manifest and infra links exactly this queue with least privilege.
-	 */
-	get publisher(): Service<
-		`${TName}Publisher`,
-		EventPublisher<QueueMessage<TName, TMessage>>
-	> {
-		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<QueueMessage<TName, TMessage>>(
-					connectionString as EventPublisherConnectionString,
-				);
-			},
-		};
-	}
-}
-
-/** The context a queue handler receives — a batch of typed messages. */
-export type QueueContext<
-	TMessage extends StandardSchemaV1,
-	TServices extends Service[] = [],
-	TLogger extends Logger = Logger,
-> = {
-	messages: InferStandardSchema<TMessage>[];
-	services: ServiceRecord<TServices>;
-	logger: TLogger;
-};
-
-export type QueueHandler<
-	TMessage extends StandardSchemaV1,
-	TServices extends Service[] = [],
-	TLogger extends Logger = Logger,
-> = (
-	ctx: QueueContext<TMessage, TServices, TLogger>,
-) => unknown | Promise<unknown>;

package/src/queue/QueueBuilder.ts

@@ -1,115 +0,0 @@
-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

@@ -1,63 +0,0 @@
-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

@@ -1,137 +0,0 @@
-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

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