@geekmidas/cloud 10.0.0-alpha.50 → 10.0.0-alpha.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/cloud",
-  "version": "10.0.0-alpha.50",
+  "version": "10.0.0-alpha.51",
   "type": "module",
   "files": [
     "dist",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "lodash.snakecase": "~4.1.1",
-    "@geekmidas/envkit": "10.0.0-alpha.50",
-    "@geekmidas/manifest": "10.0.0-alpha.50"
+    "@geekmidas/envkit": "10.0.0-alpha.51",
+    "@geekmidas/manifest": "10.0.0-alpha.51"
   },
   "devDependencies": {
     "@types/lodash.get": "~4.4.9",
@@ -58,10 +58,10 @@
     "@pulumi/aws": ">=7.47.0",
     "@pulumi/random": ">=4.21.2",
     "@pulumi/pulumi": ">=3.263.0",
-    "@geekmidas/manifest": "^10.0.0-alpha.50",
-    "@geekmidas/storage": "^10.0.0-alpha.50",
-    "@geekmidas/events": "^10.0.0-alpha.50",
-    "@geekmidas/db": "^10.0.0-alpha.50"
+    "@geekmidas/manifest": "^10.0.0-alpha.51",
+    "@geekmidas/storage": "^10.0.0-alpha.51",
+    "@geekmidas/events": "^10.0.0-alpha.51",
+    "@geekmidas/db": "^10.0.0-alpha.51"
   },
   "peerDependenciesMeta": {
     "@geekmidas/manifest": {

package/src/sst/__type-tests__/overrides.type-test.ts

@@ -0,0 +1,152 @@
+// Type-level tests for `fromManifest`'s overrides, inferred from the manifest.
+// Checked by `ts:check:sst`; each `@ts-expect-error` self-validates: if the
+// inference regresses, the now-unused directive becomes a TS error the gate
+// catches.
+
+import type { ConstructManifest } from '@geekmidas/manifest';
+import { App } from '../App';
+import { fromManifest } from '../fromManifest';
+
+const stack = new App({
+	name: 'a',
+	stage: 'dev',
+	domain: 'example.com',
+	hostedZoneId: 'Z',
+	region: 'us-east-1',
+}).stack('shop');
+
+declare const vpc: sst.aws.Vpc;
+
+// The shape `gkm build` emits: `as const satisfies ConstructManifest`.
+const constructs = {
+	Orders: {
+		kind: 'database',
+		id: 'Orders',
+		engine: 'postgres',
+		provides: ['ORDERS_URL'],
+	},
+	Billing: {
+		kind: 'database-schema',
+		id: 'Billing',
+		of: 'Orders',
+		schema: 'billing',
+		provides: ['BILLING_URL'],
+	},
+	Sessions: { kind: 'cache', id: 'Sessions', provides: ['SESSIONS_URL'] },
+	Rates: {
+		kind: 'cache',
+		id: 'Rates',
+		of: 'Orders',
+		provides: ['RATES_URL'],
+	},
+	Mail: { kind: 'email', id: 'Mail', provides: ['MAIL_URL'] },
+	Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+	Api: {
+		kind: 'rest-api',
+		id: 'Api',
+		path: 'apps/api',
+		endpoints: [],
+		provides: ['API_URL'],
+	},
+} as const satisfies ConstructManifest;
+
+// Valid: the two the synth cannot guess, plus an optional bucket prop.
+export const ok = fromManifest(stack, constructs, {
+	Orders: { vpc },
+	Mail: { from: 'no-reply@example.com' },
+	Uploads: { cors: false },
+});
+
+// A database without its VPC.
+// @ts-expect-error — `Orders` is a database: `vpc` is required.
+fromManifest(stack, constructs, { Mail: { from: 'a@example.com' } });
+
+// Mail without a sender.
+fromManifest(stack, constructs, {
+	Orders: { vpc },
+	// @ts-expect-error — every provider rejects an unverified sender.
+	Mail: {},
+});
+
+// A misspelt id.
+fromManifest(stack, constructs, {
+	Orders: { vpc },
+	Mail: { from: 'a@example.com' },
+	// @ts-expect-error — not a construct in this manifest.
+	Ordrs: { vpc },
+});
+
+// A prop the kind's component never reads.
+fromManifest(stack, constructs, {
+	Orders: { vpc },
+	Mail: { from: 'a@example.com' },
+	// @ts-expect-error — a surface takes API Gateway args, not bucket ones.
+	Api: { versioning: true },
+});
+
+// What the declaration already decides is not overridable.
+fromManifest(stack, constructs, {
+	// @ts-expect-error — the schema is the declaration's, not the deploy's.
+	Orders: { vpc, schema: 'other' },
+	Mail: { from: 'a@example.com' },
+});
+
+// A kind with nothing to override takes no key.
+fromManifest(stack, constructs, {
+	Orders: { vpc },
+	Mail: { from: 'a@example.com' },
+	// @ts-expect-error — a schema derives from its database.
+	Billing: {},
+});
+
+// Nor does a cache in a database: same address, one more table.
+fromManifest(stack, constructs, {
+	Orders: { vpc },
+	Mail: { from: 'a@example.com' },
+	// @ts-expect-error — `Rates` lives in `Orders`.
+	Rates: { region: 'eu-west-1' },
+});
+
+// The backend decides too: ElastiCache needs a VPC to live in…
+fromManifest(
+	stack,
+	constructs,
+	// @ts-expect-error — `Sessions` on ElastiCache needs `vpc`.
+	{ Orders: { vpc }, Mail: { from: 'a@example.com' } },
+	{ cache: 'elasticache' },
+);
+export const elasticache = fromManifest(
+	stack,
+	constructs,
+	{
+		Orders: { vpc },
+		Sessions: { vpc: { subnets: [], securityGroups: [] } },
+		Mail: { from: 'a@example.com' },
+	},
+	{ cache: 'elasticache' },
+);
+
+// …and mail that is not SES is an account somebody created, with its URL.
+fromManifest(
+	stack,
+	constructs,
+	{
+		Orders: { vpc },
+		// @ts-expect-error — Resend's URL is not something a deploy can mint.
+		Mail: { from: 'a@example.com' },
+	},
+	{ email: 'resend' },
+);
+export const resend = fromManifest(
+	stack,
+	constructs,
+	{
+		Orders: { vpc },
+		Mail: { from: 'a@example.com', url: 'smtp://resend' },
+	},
+	{ email: 'resend' },
+);
+
+// A manifest whose ids are not known statically keeps the untyped record.
+declare const untyped: ConstructManifest;
+export const loose = fromManifest(stack, untyped, { Anything: { at: 'all' } });

package/src/sst/fromManifest.ts

@@ -62,6 +62,7 @@ import {
 	UnresolvedDependency,
 } from './errors';
 import type { GkmLinkable } from './Linkable';
+import type { ManifestBackends, ManifestOverrides } from './overrides';
 import type { StackType } from './Stack';
 
 /**
@@ -139,21 +140,6 @@ type Provisioner = (
 	context: ProvisionContext,
 ) => Provisioned;
 
-/**
- * Provider-specific props, per construct id.
- *
- * Neutral options — `versioned`, and later `cdn` — travel in the declaration,
- * because the app legitimately has an opinion about them. Anything with S3 in
- * its name does not belong in application code, so lifecycle rules, CORS, and
- * canned ACLs are supplied here, in the deploy layer, keyed by the id they
- * apply to and typed against the component that receives them.
- *
- * A third escape hatch needs no API at all: `fromManifest` returns the
- * components, so `provisioned.Uploads.nodes.bucket` is reachable for anything
- * neither route covers.
- */
-export type ComponentOverrides = Record<string, Record<string, unknown>>;
-
 /**
  * Which component provisions which kind.
  *
@@ -951,20 +937,34 @@ export function assertProvides(
  * tenant, a read replica, and the surface over a bucket all resolve an address
  * off something else, and a pass in map order would find it half the time.
  */
-export function fromManifest(
+export function fromManifest<
+	const M extends ConstructManifest,
+	const B extends ManifestBackends = {},
+>(
 	stack: StackType,
-	manifest: ConstructManifest,
-	overrides: ComponentOverrides = {},
+	manifest: M,
+	/**
+	 * Provider-specific props, per construct id — typed from the manifest, so
+	 * only its ids are keys, each takes what its kind's component reads, and
+	 * what the synth cannot guess (a database's `vpc`, mail's `from`) is
+	 * required. See {@link ManifestOverrides}.
+	 *
+	 * Neutral options — `versioned`, `fifo` — travel in the declaration,
+	 * because the app legitimately has an opinion about them. Anything with S3
+	 * in its name does not belong in application code, so it is supplied here.
+	 * A third escape hatch needs no API: the components are returned, so
+	 * `provisioned.Uploads.nodes.bucket` is reachable for anything else.
+	 */
+	overrides: ManifestOverrides<M, B>,
 	/**
 	 * The backend choices that are config rather than declaration.
 	 *
 	 * Defaulted the same way the local target defaults them, so a stage deployed
-	 * without saying gets the same backend a developer ran against.
+	 * without saying gets the same backend a developer ran against. Typed
+	 * literally, because the backend decides what is required above: an
+	 * ElastiCache cache needs a `vpc`, Resend or SMTP mail a `url`.
 	 */
-	backends: {
-		cache?: 'upstash' | 'elasticache' | 'db';
-		email?: 'resend' | 'ses' | 'smtp';
-	} = {},
+	backends: B = {} as B,
 ): ProvisionedManifest {
 	const provisioned: ProvisionedManifest = {};
 
@@ -1006,7 +1006,7 @@ export function fromManifest(
 		const component = provisionerFor(declaration.kind)(
 			stack,
 			declaration,
-			overrides[id] ?? {},
+			(overrides as Record<string, Record<string, unknown>>)[id] ?? {},
 			context,
 		);
 

package/src/sst/index.ts

@@ -62,7 +62,6 @@ export {
 } from './errors';
 export {
 	assertProvides,
-	type ComponentOverrides,
 	describeRoutes,
 	fromManifest,
 	isServed,
@@ -76,4 +75,9 @@ export {
 } from './fromManifest';
 export { type GkmLinkable, ResourceType } from './Linkable';
 export { kebab, prefixedName, regionOfArn } from './naming';
+export type {
+	ManifestBackends,
+	ManifestOverrides,
+	OverrideFor,
+} from './overrides';
 export { Stack, type StackType } from './Stack';

package/src/sst/overrides.ts

@@ -0,0 +1,133 @@
+/**
+ * What a deploy can say about each construct, inferred from the manifest.
+ *
+ * `fromManifest` used to take `Record<string, Record<string, unknown>>`, so a
+ * misspelt id, a prop the component never reads, and a missing VPC all passed
+ * the type checker — the first two silently, the last at synth, mid-deploy.
+ * The manifest is emitted `as const`, so every id's kind is known statically,
+ * and the kind decides what can be overridden:
+ *
+ * - only the manifest's own ids are keys;
+ * - each takes the props its kind's provisioner reads, minus those the
+ *   declaration already decides (a site's `path`, a file server's `origin`);
+ * - what the synth refuses to guess is required — a database's `vpc`, mail's
+ *   `from`, and, by backend, an ElastiCache `vpc` or a non-SES mail `url`;
+ * - a kind with nothing to override takes no key at all.
+ */
+
+import type { ConstructManifest, DeclarationKind } from '@geekmidas/manifest';
+import type { CacheProps } from './aws/Cache';
+import type { CredentialProps } from './aws/Credential';
+import type { DatabaseProps } from './aws/Database';
+import type { EncryptionProps } from './aws/Encryption';
+import type { ExternalApiProps } from './aws/ExternalApi';
+import type { FileServerProps } from './aws/FileServer';
+import type { ObjectStorageProps } from './aws/ObjectStorage';
+import type { QueueProps } from './aws/Queue';
+import type { SecretProps } from './aws/Secret';
+import type { StaticSiteProps } from './aws/StaticSite';
+import type { TopicProps } from './aws/Topic';
+
+/** The backend choices that are config rather than declaration. */
+export interface ManifestBackends {
+	cache?: 'upstash' | 'elasticache' | 'db';
+	email?: 'resend' | 'ses' | 'smtp';
+}
+
+/** The backend a choice resolves to — the provisioner's default when unset. */
+type CacheBackendOf<B extends ManifestBackends> =
+	B['cache'] extends NonNullable<ManifestBackends['cache']>
+		? B['cache']
+		: 'upstash';
+type EmailBackendOf<B extends ManifestBackends> =
+	B['email'] extends NonNullable<ManifestBackends['email']>
+		? B['email']
+		: 'ses';
+
+type CacheOverride<Backend> = Backend extends 'elasticache'
+	? { vpc: NonNullable<CacheProps['vpc']> }
+	: Backend extends 'upstash'
+		? { url?: CacheProps['url']; region?: string }
+		: never;
+
+type EmailOverride<Backend> = {
+	/** Every provider rejects an unverified sender, so there is no default. */
+	from: $util.Input<string>;
+	region?: $util.Input<string>;
+} & (Backend extends 'ses'
+	? { url?: $util.Input<string> }
+	: // Resend and a relay are accounts somebody created: their URL is theirs.
+		{ url: $util.Input<string> });
+
+/**
+ * What one declaration takes, by its kind and the backends; `never` for a kind
+ * with nothing to override, which drops its id from the keys.
+ */
+export type OverrideFor<D, B extends ManifestBackends = {}> = D extends {
+	kind: infer K extends DeclarationKind;
+}
+	? K extends 'objects'
+		? Partial<ObjectStorageProps>
+		: K extends 'file-server'
+			? Partial<Omit<FileServerProps, 'origin'>>
+			: K extends 'site'
+				? Partial<Omit<StaticSiteProps, 'path' | 'variant' | 'environment'>>
+				: K extends 'queue'
+					? Partial<Omit<QueueProps, 'fifo'>>
+					: K extends 'topic'
+						? Partial<TopicProps>
+						: K extends 'database'
+							? Omit<DatabaseProps, 'schema' | 'version'>
+							: K extends 'cache'
+								? // In a database: same address, one more table, nothing to say.
+									D extends { of: string }
+									? never
+									: CacheOverride<CacheBackendOf<B>>
+								: K extends 'email'
+									? EmailOverride<EmailBackendOf<B>>
+									: K extends 'rest-api'
+										? Partial<sst.aws.ApiGatewayV2Args>
+										: K extends 'secret'
+											? SecretProps
+											: K extends 'credential'
+												? CredentialProps
+												: K extends 'encryption'
+													? Partial<EncryptionProps>
+													: K extends 'external-api'
+														? Omit<ExternalApiProps, 'url'>
+														: // Derived databases, compute, mobile apps, OIDC.
+															never
+	: never;
+
+/** Whether `{}` satisfies an override — whether the id can be left out. */
+type IsOptional<T> = {} extends T ? true : false;
+
+type Overridable<M, B extends ManifestBackends> = {
+	[Id in keyof M]: [OverrideFor<M[Id], B>] extends [never] ? never : Id;
+}[keyof M];
+
+type RequiredIds<M, B extends ManifestBackends> = {
+	[Id in Overridable<M, B>]: IsOptional<OverrideFor<M[Id], B>> extends true
+		? never
+		: Id;
+}[Overridable<M, B>];
+
+/**
+ * The overrides a manifest accepts, keyed by its own construct ids.
+ *
+ * A manifest typed only as `ConstructManifest` — ids unknown — falls back to
+ * the untyped record, and the provisioners' synth-time checks still apply.
+ */
+export type ManifestOverrides<
+	M extends ConstructManifest,
+	B extends ManifestBackends = {},
+> = string extends keyof M
+	? Record<string, Record<string, unknown>>
+	: {
+			[Id in RequiredIds<M, B>]: OverrideFor<M[Id], B>;
+		} & {
+			[Id in Exclude<Overridable<M, B>, RequiredIds<M, B>>]?: OverrideFor<
+				M[Id],
+				B
+			>;
+		};