@geekmidas/constructs 4.0.0 → 5.0.0

package/dist/topic/index.d.mts

@@ -0,0 +1,32 @@
+import "../Construct-DCMuYOox.mjs";
+import { Topic, TopicEvents, TopicMessage } from "../Topic-DT10AqHk.mjs";
+import { Logger } from "@geekmidas/logger";
+
+//#region src/topic/TopicBuilder.d.ts
+
+/**
+ * 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)`.
+ */
+declare class TopicBuilder<TName extends string = string, TEvents extends TopicEvents = TopicEvents> {
+  private _name?;
+  private _logger;
+  /** The topic name — drives the infra topic and its `<NAME>_*` env vars. */
+  topic<T extends string>(name: T): TopicBuilder<T, TEvents>;
+  logger(logger: Logger): 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>;
+}
+//# sourceMappingURL=TopicBuilder.d.ts.map
+//#endregion
+//#region src/topic/index.d.ts
+declare const t: TopicBuilder<string, TopicEvents>;
+//# sourceMappingURL=index.d.ts.map
+
+//#endregion
+export { Topic, TopicBuilder, TopicEvents, TopicMessage, t };
+//# sourceMappingURL=index.d.mts.map

package/dist/topic/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/topic/TopicBuilder.ts","../../src/topic/index.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AASA;;AAEiB,cAFJ,YAEI,CAAA,cAAA,MAAA,GAAA,MAAA,EAAA,gBAAA,WAAA,GAAc,WAAd,CAAA,CAAA;EAAW,QAAG,KAAA;EAAW,QAMX,OAAA;EAAC;EAAiB,KAAE,CAAA,UAAA,MAAA,CAAA,CAAA,IAAA,EAApB,CAAoB,CAAA,EAAhB,YAAgB,CAAH,CAAG,EAAA,OAAA,CAAA;EAAO,MAAvB,CAAA,MAAA,EAKnB,MALmB,CAAA,EAAA,IAAA;EAAY;;;;EAcO,MAAE,CAAA,UAAtC,WAAsC,CAAA,CAAA,MAAA,EAAjB,CAAiB,CAAA,EAAb,KAAa,CAAP,KAAO,EAAA,CAAA,CAAA;;AAAR;;;cCrBnC,GAAC,qBAAqB,WAAA"}

package/dist/topic/index.mjs

@@ -0,0 +1,92 @@
+import { Construct, ConstructType } from "../Construct-DD8EaWzh.mjs";
+import { ConsoleLogger, DEFAULT_LOGGER } from "@geekmidas/logger/console";
+import { environmentCase } from "@geekmidas/envkit";
+import { Publisher } from "@geekmidas/events";
+
+//#region src/topic/Topic.ts
+const DEFAULT_LOGGER$1 = new ConsoleLogger();
+/**
+* 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.
+*/
+var Topic = class extends Construct {
+	__IS_TOPIC__ = true;
+	static isTopic(obj) {
+		return Boolean(obj && obj.__IS_TOPIC__ === true && obj.type === ConstructType.Topic);
+	}
+	constructor(name, eventSchemas, logger = DEFAULT_LOGGER$1) {
+		super(ConstructType.Topic, logger, [], []);
+		this.name = name;
+		this.eventSchemas = eventSchemas;
+	}
+	/** The event type names this topic carries. */
+	get eventTypes() {
+		return Object.keys(this.eventSchemas);
+	}
+	/**
+	* 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() {
+		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(connectionString);
+			}
+		};
+	}
+};
+
+//#endregion
+//#region src/topic/TopicBuilder.ts
+/**
+* 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)`.
+*/
+var TopicBuilder = class {
+	_name;
+	_logger = DEFAULT_LOGGER;
+	/** The topic name — drives the infra topic and its `<NAME>_*` env vars. */
+	topic(name) {
+		this._name = name;
+		return this;
+	}
+	logger(logger) {
+		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(events) {
+		if (!this._name) throw new Error("Topic requires a name — call .topic(name) before .events().");
+		const topic = new Topic(this._name, events, this._logger);
+		this._name = void 0;
+		this._logger = DEFAULT_LOGGER;
+		return topic;
+	}
+};
+
+//#endregion
+//#region src/topic/index.ts
+const t = new TopicBuilder();
+
+//#endregion
+export { Topic, TopicBuilder, t };
+//# sourceMappingURL=index.mjs.map

package/dist/topic/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["DEFAULT_LOGGER","obj: unknown","name: TName","eventSchemas: TEvents","logger: Logger","name: T","logger: Logger","events: T"],"sources":["../../src/topic/Topic.ts","../../src/topic/TopicBuilder.ts","../../src/topic/index.ts"],"sourcesContent":["import { environmentCase } from '@geekmidas/envkit';\nimport {\n\ttype EventPublisher,\n\ttype EventPublisherConnectionString,\n\ttype PublishableMessage,\n\tPublisher,\n} from '@geekmidas/events';\nimport type { Logger } from '@geekmidas/logger';\nimport { ConsoleLogger } from '@geekmidas/logger/console';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { Construct, ConstructType } from '../Construct';\n\nconst DEFAULT_LOGGER = new ConsoleLogger() as unknown as Logger;\n\n/** A topic's event contract — a map of event type → payload schema. */\nexport type TopicEvents = Record<string, StandardSchemaV1>;\n\n/**\n * The union of wire messages a topic carries, derived from its event map:\n * `{ type: 'user.created'; payload: … } | { type: 'user.updated'; payload: … }`.\n */\nexport type TopicMessage<TEvents extends TopicEvents> = {\n\t[K in keyof TEvents & string]: PublishableMessage<\n\t\tK,\n\t\tInferStandardSchema<TEvents[K]>\n\t>;\n}[keyof TEvents & string];\n\n/**\n * A topic — pub/sub fan-out. Unlike a `Queue` (point-to-point, one consumer), a\n * topic is a *resource* owned by no single handler: it declares the event\n * contract, derives a typed producer (`topic.publisher`), and any number of\n * subscribers (`s.topic(topic)`) bind to it. `gkm build` discovers it into the\n * manifest's `topics` field; infra provisions an SNS topic.\n *\n * This replaces hand-writing a publisher `Service`: the publisher is *derived*\n * from the declared event contract, the same way `Queue` derives its publisher.\n */\nexport class Topic<\n\tTName extends string = string,\n\tTEvents extends TopicEvents = TopicEvents,\n> extends Construct {\n\t__IS_TOPIC__ = true;\n\n\tstatic isTopic(obj: unknown): obj is Topic<string, TopicEvents> {\n\t\treturn Boolean(\n\t\t\tobj &&\n\t\t\t\t(obj as { __IS_TOPIC__?: boolean }).__IS_TOPIC__ === true &&\n\t\t\t\t(obj as Construct).type === ConstructType.Topic,\n\t\t);\n\t}\n\n\tconstructor(\n\t\tpublic readonly name: TName,\n\t\t/**\n\t\t * The event contract — a map of event type → payload schema. Named\n\t\t * `eventSchemas` (not `events`) to avoid clashing with `Construct.events`,\n\t\t * which is the array of `MappedEvent`s a construct *publishes*.\n\t\t */\n\t\tpublic readonly eventSchemas: TEvents,\n\t\tlogger: Logger = DEFAULT_LOGGER,\n\t) {\n\t\tsuper(ConstructType.Topic, logger, [], []);\n\t}\n\n\t/** The event type names this topic carries. */\n\tget eventTypes(): (keyof TEvents & string)[] {\n\t\treturn Object.keys(this.eventSchemas) as (keyof TEvents & string)[];\n\t}\n\n\t/**\n\t * The producer side — a `Service` exposing an `EventPublisher` typed to the\n\t * union of this topic's events. Inject via `.publisher(topic.publisher)` (for\n\t * declarative `.event(...)`) or `.services([topic.publisher])` (to publish\n\t * imperatively). Reads `<NAME>_PUBLISHER_CONNECTION_STRING` and selects the\n\t * transport from the URL protocol — `pgboss://` locally, `sns://` deployed.\n\t *\n\t * Because it's a `Service`, the connection-string requirement is sniffed into\n\t * the manifest of whatever construct injects it (least-privilege linking).\n\t */\n\tget publisher(): Service<\n\t\t`${TName}Publisher`,\n\t\tEventPublisher<TopicMessage<TEvents>>\n\t> {\n\t\tconst envVar = `${environmentCase(this.name)}_PUBLISHER_CONNECTION_STRING`;\n\t\treturn {\n\t\t\tserviceName: `${this.name}Publisher`,\n\t\t\tasync register({ envParser }) {\n\t\t\t\tconst { connectionString } = envParser\n\t\t\t\t\t.create((get) => ({\n\t\t\t\t\t\tconnectionString: get(envVar).string(),\n\t\t\t\t\t}))\n\t\t\t\t\t.parse();\n\n\t\t\t\treturn Publisher.fromConnectionString<TopicMessage<TEvents>>(\n\t\t\t\t\tconnectionString as EventPublisherConnectionString,\n\t\t\t\t);\n\t\t\t},\n\t\t};\n\t}\n}\n","import type { Logger } from '@geekmidas/logger';\nimport { DEFAULT_LOGGER } from '@geekmidas/logger/console';\nimport { Topic, type TopicEvents } from './Topic';\n\n/**\n * Builds a {@link Topic} — `t.topic('users').events({ 'user.created': schema, … })`.\n * The event map is the topic's contract: it types the derived `topic.publisher`\n * and the subscribers that bind via `s.topic(topic)`.\n */\nexport class TopicBuilder<\n\tTName extends string = string,\n\tTEvents extends TopicEvents = TopicEvents,\n> {\n\tprivate _name?: string;\n\tprivate _logger: Logger = DEFAULT_LOGGER;\n\n\t/** The topic name — drives the infra topic and its `<NAME>_*` env vars. */\n\ttopic<T extends string>(name: T): TopicBuilder<T, TEvents> {\n\t\tthis._name = name;\n\t\treturn this as unknown as TopicBuilder<T, TEvents>;\n\t}\n\n\tlogger(logger: Logger): this {\n\t\tthis._logger = logger;\n\t\treturn this;\n\t}\n\n\t/**\n\t * The event contract — a map of event type → payload schema. Building the\n\t * topic requires this; it's what types the publisher and subscribers.\n\t */\n\tevents<T extends TopicEvents>(events: T): Topic<TName, T> {\n\t\tif (!this._name) {\n\t\t\tthrow new Error(\n\t\t\t\t'Topic requires a name — call .topic(name) before .events().',\n\t\t\t);\n\t\t}\n\n\t\tconst topic = new Topic<TName, T>(\n\t\t\tthis._name as TName,\n\t\t\tevents,\n\t\t\tthis._logger,\n\t\t);\n\n\t\t// Reset builder state to prevent pollution across reuse.\n\t\tthis._name = undefined;\n\t\tthis._logger = DEFAULT_LOGGER;\n\n\t\treturn topic;\n\t}\n}\n","export {\n\tTopic,\n\ttype TopicEvents,\n\ttype TopicMessage,\n} from './Topic';\n\nimport { TopicBuilder } from './TopicBuilder';\n\nexport { TopicBuilder } from './TopicBuilder';\n\nexport const t = new TopicBuilder();\n"],"mappings":";;;;;;AAcA,MAAMA,mBAAiB,IAAI;;;;;;;;;;;AA0B3B,IAAa,QAAb,cAGU,UAAU;CACnB,eAAe;CAEf,OAAO,QAAQC,KAAiD;AAC/D,SAAO,QACN,OACE,IAAmC,iBAAiB,QACpD,IAAkB,SAAS,cAAc,MAC3C;CACD;CAED,YACiBC,MAMAC,cAChBC,SAAiBJ,kBAChB;AACD,QAAM,cAAc,OAAO,QAAQ,CAAE,GAAE,CAAE,EAAC;EAT1B;EAMA;CAIhB;;CAGD,IAAI,aAAyC;AAC5C,SAAO,OAAO,KAAK,KAAK,aAAa;CACrC;;;;;;;;;;;CAYD,IAAI,YAGF;EACD,MAAM,UAAU,EAAE,gBAAgB,KAAK,KAAK,CAAC;AAC7C,SAAO;GACN,cAAc,EAAE,KAAK,KAAK;GAC1B,MAAM,SAAS,EAAE,WAAW,EAAE;IAC7B,MAAM,EAAE,kBAAkB,GAAG,UAC3B,OAAO,CAAC,SAAS,EACjB,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CACtC,GAAE,CACF,OAAO;AAET,WAAO,UAAU,qBAChB,iBACA;GACD;EACD;CACD;AACD;;;;;;;;;AC7FD,IAAa,eAAb,MAGE;CACD,AAAQ;CACR,AAAQ,UAAkB;;CAG1B,MAAwBK,MAAmC;AAC1D,OAAK,QAAQ;AACb,SAAO;CACP;CAED,OAAOC,QAAsB;AAC5B,OAAK,UAAU;AACf,SAAO;CACP;;;;;CAMD,OAA8BC,QAA4B;AACzD,OAAK,KAAK,MACT,OAAM,IAAI,MACT;EAIF,MAAM,QAAQ,IAAI,MACjB,KAAK,OACL,QACA,KAAK;AAIN,OAAK;AACL,OAAK,UAAU;AAEf,SAAO;CACP;AACD;;;;ACxCD,MAAa,IAAI,IAAI"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -34,6 +34,26 @@
         "default": "./dist/functions/index.cjs"
       }
     },
+    "./queue": {
+      "import": {
+        "types": "./dist/queue/index.d.mts",
+        "default": "./dist/queue/index.mjs"
+      },
+      "require": {
+        "types": "./dist/queue/index.d.cts",
+        "default": "./dist/queue/index.cjs"
+      }
+    },
+    "./topic": {
+      "import": {
+        "types": "./dist/topic/index.d.mts",
+        "default": "./dist/topic/index.mjs"
+      },
+      "require": {
+        "types": "./dist/topic/index.d.cts",
+        "default": "./dist/topic/index.cjs"
+      }
+    },
     "./crons": {
       "import": {
         "types": "./dist/crons/index.d.mts",
@@ -127,16 +147,16 @@
     "msw": "~2.10.3",
     "zod": "~4.1.13",
     "@geekmidas/audit": "^2.0.1",
-    "@geekmidas/db": "^1.0.2",
     "@geekmidas/cache": "^1.1.1",
-    "@geekmidas/envkit": "^1.0.7",
+    "@geekmidas/db": "^1.0.2",
+    "@geekmidas/envkit": "^1.1.0",
     "@geekmidas/errors": "^1.0.1",
-    "@geekmidas/events": "^1.1.4",
+    "@geekmidas/events": "^1.1.5",
     "@geekmidas/logger": "^1.0.2",
-    "@geekmidas/rate-limit": "^3.0.0",
-    "@geekmidas/schema": "^1.0.2",
-    "@geekmidas/services": "^1.1.0",
-    "@geekmidas/testkit": "^2.0.0"
+    "@geekmidas/rate-limit": "^4.0.0",
+    "@geekmidas/schema": "^1.0.3",
+    "@geekmidas/services": "^2.0.0",
+    "@geekmidas/testkit": "^3.0.0"
   },
   "peerDependencies": {
     "@middy/core": ">=6.3.1",
@@ -146,13 +166,13 @@
     "@geekmidas/audit": "^2.0.1",
     "@geekmidas/cache": "^1.1.1",
     "@geekmidas/db": "^1.0.2",
-    "@geekmidas/envkit": "^1.0.7",
+    "@geekmidas/envkit": "^1.1.0",
     "@geekmidas/errors": "^1.0.1",
-    "@geekmidas/events": "^1.1.4",
+    "@geekmidas/events": "^1.1.5",
     "@geekmidas/logger": "^1.0.2",
-    "@geekmidas/rate-limit": "^3.0.0",
-    "@geekmidas/schema": "^1.0.2",
-    "@geekmidas/services": "^1.1.0"
+    "@geekmidas/rate-limit": "^4.0.0",
+    "@geekmidas/schema": "^1.0.3",
+    "@geekmidas/services": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@geekmidas/audit": {

package/src/Construct.ts

@@ -171,6 +171,8 @@ export enum ConstructType {
 	Endpoint = 'dev.geekmidas.function.endpoint',
 	Function = 'dev.geekmidas.function.function',
 	Subscriber = 'dev.geekmidas.function.subscriber',
+	Queue = 'dev.geekmidas.function.queue',
+	Topic = 'dev.geekmidas.resource.topic',
 }
 
 /**

package/src/adaptors/aws.ts

@@ -2,4 +2,5 @@ export { AWSScheduledFunction } from '../crons/AWSScheduledFunction';
 export { AmazonApiGatewayV1Endpoint } from '../endpoints/AmazonApiGatewayV1EndpointAdaptor';
 export { AmazonApiGatewayV2Endpoint } from '../endpoints/AmazonApiGatewayV2EndpointAdaptor';
 export { AWSLambdaFunction } from '../functions/AWSLambdaFunction';
+export { AWSLambdaQueue } from '../queue/AWSLambdaQueueAdaptor';
 export { AWSLambdaSubscriber } from '../subscribers/AWSLambdaSubscriberAdaptor';

package/src/adaptors/testing.ts

@@ -7,4 +7,5 @@ export {
 } from '../endpoints/MswEndpointAdaptor';
 export { TestEndpointAdaptor } from '../endpoints/TestEndpointAdaptor';
 export { TestFunctionAdaptor } from '../functions/TestFunctionAdaptor';
+export { TestQueueAdaptor } from '../queue/TestQueueAdaptor';
 export { TestSubscriberAdaptor } from '../subscribers/TestSubscriberAdaptor';

package/src/endpoints/Endpoint.ts

@@ -9,6 +9,7 @@ import type { RateLimitConfig } from '@geekmidas/rate-limit';
 import type {
 	InferComposableStandardSchema,
 	InferStandardSchema,
+	InferStandardSchemaInput,
 } from '@geekmidas/schema';
 import {
 	convertSchemaWithComponents,
@@ -367,11 +368,12 @@ export class Endpoint<
 		>,
 		response: ResponseBuilder,
 	): OutSchema extends StandardSchemaV1
-		?
-				| InferStandardSchema<OutSchema>
-				| ResponseWithMetadata<InferStandardSchema<OutSchema>>
-				| Promise<InferStandardSchema<OutSchema>>
-				| Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>>
+		? // Handler produces the output schema's INPUT type (the schema
+			// may coerce it on the way out — see EndpointHandler).
+				| InferStandardSchemaInput<OutSchema>
+				| ResponseWithMetadata<InferStandardSchemaInput<OutSchema>>
+				| Promise<InferStandardSchemaInput<OutSchema>>
+				| Promise<ResponseWithMetadata<InferStandardSchemaInput<OutSchema>>>
 		:
 				| any
 				| ResponseWithMetadata<any>
@@ -1241,11 +1243,15 @@ export type EndpointHandler<
 	>,
 	response: ResponseBuilder,
 ) => OutSchema extends StandardSchemaV1
-	?
-			| InferStandardSchema<OutSchema>
-			| ResponseWithMetadata<InferStandardSchema<OutSchema>>
-			| Promise<InferStandardSchema<OutSchema>>
-			| Promise<ResponseWithMetadata<InferStandardSchema<OutSchema>>>
+	? // The handler must produce the schema's INPUT type — the output
+		// schema is allowed to coerce it (e.g. a `Date` → ISO `string`),
+		// so the handler may return the looser input while consumers
+		// (EndpointOutput / the generated client) still see the parsed
+		// output type.
+			| InferStandardSchemaInput<OutSchema>
+			| ResponseWithMetadata<InferStandardSchemaInput<OutSchema>>
+			| Promise<InferStandardSchemaInput<OutSchema>>
+			| Promise<ResponseWithMetadata<InferStandardSchemaInput<OutSchema>>>
 	:
 			| unknown
 			| ResponseWithMetadata<unknown>

package/src/queue/AWSLambdaQueueAdaptor.ts

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

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