@geekmidas/constructs 7.0.1 → 10.0.0-alpha.0

package/src/telemetry.ts

@@ -1,103 +0,0 @@
-/**
- * Telemetry interface for endpoint instrumentation
- *
- * This provides a framework-agnostic way to add telemetry to endpoints.
- * Implementations can use OpenTelemetry, DataDog, or any other system.
- */
-import type { Context as LambdaContext } from 'aws-lambda';
-
-/**
- * Context object returned by onRequestStart, passed to subsequent hooks
- */
-export interface TelemetryContext {
-	/**
-	 * Any data the telemetry implementation needs to track across the request lifecycle
-	 */
-	[key: string]: unknown;
-}
-
-/**
- * Request information passed to telemetry hooks
- */
-export interface TelemetryRequest {
-	/**
-	 * The raw Lambda event
-	 */
-	event: any;
-
-	/**
-	 * The Lambda context
-	 */
-	context: LambdaContext;
-}
-
-/**
- * Response information passed to onRequestEnd
- */
-export interface TelemetryResponse {
-	/**
-	 * HTTP status code
-	 */
-	statusCode: number;
-
-	/**
-	 * Response body (may be stringified JSON)
-	 */
-	body?: string;
-
-	/**
-	 * Response headers
-	 */
-	headers?: Record<string, string>;
-}
-
-/**
- * Telemetry interface for instrumenting endpoint requests
- *
- * @example
- * ```typescript
- * const telemetry: Telemetry = {
- *   onRequestStart(req) {
- *     const span = tracer.startSpan('http.request');
- *     return { span };
- *   },
- *   onRequestEnd(ctx, response) {
- *     ctx.span.setStatus(response.statusCode);
- *     ctx.span.end();
- *   },
- *   onRequestError(ctx, error) {
- *     ctx.span.recordException(error);
- *     ctx.span.end();
- *   },
- * };
- *
- * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
- *   telemetry,
- * });
- * ```
- */
-export interface Telemetry {
-	/**
-	 * Called at the start of each request
-	 *
-	 * @param request - The incoming request information
-	 * @returns Context object that will be passed to onRequestEnd/onRequestError
-	 */
-	onRequestStart(request: TelemetryRequest): TelemetryContext;
-
-	/**
-	 * Called when the request completes successfully
-	 *
-	 * @param ctx - The context returned by onRequestStart
-	 * @param response - The response information
-	 */
-	onRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;
-
-	/**
-	 * Called when the request fails with an error
-	 *
-	 * @param ctx - The context returned by onRequestStart
-	 * @param error - The error that occurred
-	 */
-	onRequestError(ctx: TelemetryContext, error: Error): void;
-}

package/src/topic/Topic.ts

@@ -1,103 +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 } 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

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

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

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

package/src/types.ts

@@ -1,13 +0,0 @@
-export type RemoveUndefined<T> = {
-	[K in keyof T as T[K] extends undefined ? never : K]: T[K];
-};
-
-export type HttpMethod =
-	| 'GET'
-	| 'POST'
-	| 'PUT'
-	| 'PATCH'
-	| 'DELETE'
-	| 'OPTIONS';
-
-export type LowerHttpMethod<T extends HttpMethod> = Lowercase<T>;

package/test.ts

@@ -1,91 +0,0 @@
-import type { Cache } from '@geekmidas/cache';
-import { UpstashCache } from '@geekmidas/cache/upstash';
-import { e } from '@geekmidas/constructs/endpoints';
-import type { EnvironmentParser } from '@geekmidas/envkit';
-import { UnauthorizedError } from '@geekmidas/errors';
-import type { EventPublisher } from '@geekmidas/events';
-import { ConsoleLogger } from '@geekmidas/logger/console';
-import z4 from 'zod/v4';
-import { isValidJWT } from 'zod/v4/core';
-
-export type CacheClient = Cache<string>;
-
-export class CacheService {
-	private static client: CacheClient;
-	static serviceName = 'cache' as const;
-
-	private static config = (envParser: EnvironmentParser<{}>) =>
-		envParser.create((get) => ({
-			url: get('UPSTASH_URL').string(),
-			token: get('UPSTASH_TOKEN').string(),
-		}));
-
-	static register(envParser: EnvironmentParser<{}>): CacheClient {
-		if (!CacheService.client) {
-			const config = CacheService.config(envParser).parse();
-			CacheService.client = new UpstashCache(config.url, config.token);
-		}
-		return CacheService.client;
-	}
-}
-
-export class EventsService {
-	public static instance: ShortstaffEventPublisher;
-	static serviceName = 'events' as const;
-
-	public static config = (envParser: EnvironmentParser<{}>) =>
-		envParser.create((get) => ({
-			topicArn: get('NOTIFICATION_TOPIC_ARN').string(),
-			region: get('AWS_REGION').string(),
-			accessKeyId: get('AWS_ACCESS_KEY_ID').string().optional(),
-			secretAccessKey: get('AWS_SECRET_ACCESS_KEY').string().optional(),
-			endpoint: get('AWS_ENDPOINT_URL').string().optional(),
-		}));
-
-	static register(_envParser: EnvironmentParser<{}>): ShortstaffEventPublisher {
-		return EventsService.instance;
-	}
-}
-
-export type ShortstaffEventPublisher = EventPublisher<{
-	type: 'user';
-	payload: {};
-}>;
-
-export const r = e
-	.logger(new ConsoleLogger())
-	.services([CacheService])
-	.publisher(EventsService);
-
-export const sessionRouter = r.session(async ({ header, services }) => {
-	const authHeader = header('authorization');
-
-	if (!authHeader || !authHeader.startsWith('Bearer ')) {
-		throw new UnauthorizedError('Authorization header required');
-	}
-
-	const token = authHeader.substring(7);
-
-	if (!isValidJWT(token)) {
-		throw new UnauthorizedError('Invalid token format');
-	}
-
-	return { token };
-});
-
-const LoginUserSchema = z4.object({
-	username: z4.string().min(3),
-	password: z4.string().min(6),
-});
-
-const LoginResponseSchema = z4.object({
-	token: z4.string(),
-});
-
-export const login = r
-	.post('/auth/login')
-	.body(LoginUserSchema)
-	.output(LoginResponseSchema)
-	.handle(async ({ body, services, header }, _res) => {
-		return { token: 'mock-jwt-token' };
-	});

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "composite": true
-  },
-  "include": ["src/**/*"]
-}

package/tsdown.config.ts

@@ -1,34 +0,0 @@
-import { defineConfig } from 'tsdown';
-
-export default defineConfig({
-	entry: [
-		'src/index.ts',
-		'src/types.ts',
-		'src/endpoints/index.ts',
-		'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',
-	],
-	clean: true,
-	outDir: 'dist',
-	format: ['cjs', 'esm'],
-	sourcemap: true,
-	dts: true,
-	outExtensions: (ctx) => ({
-		js: ctx.format === 'es' ? '.mjs' : '.cjs',
-	}),
-	// Bundle lodash utilities — they are not hoisted to the workspace root
-	// and would fail to resolve when consumers load the dist from the root context.
-	noExternal: [
-		'lodash.compact',
-		'lodash.get',
-		'lodash.pick',
-		'lodash.set',
-		'lodash.uniqby',
-	],
-});