declapract-typescript-ehmpathy 0.49.13 → 0.49.14

package/dist/practices/persist-with-rds/best-practice/src/.test/assets/database/getTestdbIdentity.ts

@@ -0,0 +1,52 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+/**
+ * .what = read one value from git, in a dir
+ */
+const getGitValue = (input: { cwd: string; args: string[] }): string =>
+  execFileSync('git', input.args, { cwd: input.cwd, encoding: 'utf8' }).trim();
+
+/**
+ * .what = this checkout's testdb identity: the suffix of its compose project and container, and
+ *         the host port it binds
+ * .why = two worktrees of one repo must never share one testdb, or an integration run in one
+ *        reads or clobbers the rows of another, and a `start:testdb` in one stops the other's db
+ * .note = ci and a main checkout keep the declared port and no suffix, so both behave as before.
+ *         only a linked worktree derives its own, from a hash of its toplevel path, so the same
+ *         worktree always lands on the same port
+ * .note = the port offset spans 999 slots, so two linked worktrees can draw one port (~1 in 999
+ *         per pair). that collision is loud, never shared: the suffix differs, so each worktree
+ *         names its own compose project and volume, and docker refuses the second bind with
+ *         `port is already allocated`. stop one worktree's testdb to start the other's
+ */
+export const getTestdbIdentity = (
+  input: { portDeclared: number },
+  context: { cwd: string; env: NodeJS.ProcessEnv } = {
+    cwd: process.cwd(),
+    env: process.env,
+  },
+): { suffix: string; port: number } => {
+  // ci runs one checkout per job, so it keeps the declared port
+  if (context.env.CI) return { suffix: '', port: input.portDeclared };
+
+  // a main checkout keeps the declared port; only a linked worktree has a git dir of its own
+  const gitDir = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--absolute-git-dir'],
+  });
+  const gitDirCommon = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+  });
+  if (gitDir === gitDirCommon) return { suffix: '', port: input.portDeclared };
+
+  // derive the suffix and the port from the worktree's toplevel path
+  const toplevel = getGitValue({
+    cwd: context.cwd,
+    args: ['rev-parse', '--show-toplevel'],
+  });
+  const hash = createHash('sha256').update(toplevel).digest('hex');
+  const offset = 1 + (Number.parseInt(hash.slice(0, 8), 16) % 999);
+  return { suffix: `-${hash.slice(0, 6)}`, port: input.portDeclared + offset };
+};

package/dist/practices/persist-with-rds/best-practice/src/.test/assets/database/getTestdbPort.ts

@@ -0,0 +1,17 @@
+import { getTestdbIdentity } from './getTestdbIdentity';
+
+/**
+ * .what = the host port this checkout's testdb binds, for an access
+ * .why = the test harness and the schema provisioner ask here, so the compose file, the jest env
+ *        (which hands the port to the app via TESTDB_PORT), and the provisioner of one worktree
+ *        all agree on one port
+ * .note = only `test` access reaches the local testdb; any other access keeps its declared port
+ * .note = a test asset: the app never imports it. the app reads TESTDB_PORT via getOneDatabasePort
+ */
+export const getTestdbPort = (input: {
+  access: string;
+  portDeclared: number;
+}): number => {
+  if (input.access !== 'test') return input.portDeclared;
+  return getTestdbIdentity({ portDeclared: input.portDeclared }).port;
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/config/config.schema.ts

@@ -4,34 +4,16 @@ import { z } from 'zod';
 export type Grant = 'plan' | 'apply';
 
 /**
- * .what = get the config schema for a given oidc grant.
- * .why = the prod plan job's oidc role is DENIED every ssm secret except the
- *        for-plan db credential. under grant=plan the
- *        eagerly-read getConfig() cannot read for-apply's password (or any other
- *        secret); sdk-config substitutes undefined for each denied param, so those
- *        must be .optional() to tolerate the miss. grant=apply (the default — apply
- *        job, cloud runtime, local dev, tests) keeps every secret REQUIRED, so its
- *        inferred type carries no `| undefined` and needs no guards at consumers.
- * .note = grant is a per-schema arg, NOT read from env here; getConfig picks which
- *         schema to parse with at call time (see getConfig.ts).
+ * .what = the config schema for one grant: `plan` marks the secrets its role may not read optional
+ * .why = see "config grants" in the persist-with-rds practice readme
  */
 const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
-  // required by default; optional only under grant=plan. generic on the LITERAL
-  // TGrant so each schema infers monomorphically (all-required for apply,
-  // reader-denied-optional for plan) instead of the widened union.
+  // required under apply; optional under plan
   const secret = <T extends z.ZodTypeAny>(
     schema: T,
   ): TGrant extends 'plan' ? z.ZodOptional<T> : T =>
-    // as-cast — why types miss: TS cannot relate a conditional return type
-    //   (`TGrant extends 'plan' ? … : …`) to a runtime `grant === 'plan'`
-    //   ternary; the two are unrelated to the checker, so the ternary widens to
-    //   `ZodOptional<T> | T` and does not fit the declared conditional return.
-    // correct type: the value IS `ZodOptional<T>` when TGrant='plan' and `T`
-    //   otherwise — exactly the declared return; the runtime branch matches the
-    //   type branch one-to-one, so the assertion is sound.
-    // removal path: TS learns to relate a conditional return type to a runtime
-    //   discriminant check (microsoft/TypeScript#33912), or the caller splits
-    //   into two monomorphic overloads that never share this body.
+    // as-cast: the runtime branch matches the conditional type one-to-one.
+    // removal path: microsoft/TypeScript#33912, or two monomorphic overloads
     (grant === 'plan' ? schema.optional() : schema) as TGrant extends 'plan'
       ? z.ZodOptional<T>
       : T;
@@ -53,13 +35,7 @@ const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
       }),
       role: z.object({
         cicd: z.object({
-          // for-plan and for-apply may map to DIFFERENT db users (e.g. a readonly
-          // user for-plan), so each carries its own username. names mirror the prod
-          // oidc roles (for-plan / for-apply) that read them.
-          // .note: only for-apply's PASSWORD is reader-denied under grant=plan; the
-          // username is a readable static, so the object is always present. mark the
-          // password itself as the secret (a secret() on the whole object would never
-          // tolerate the miss — the present object still validates its required password).
+          // each grant role may map to its own db user; only for-apply's password is a secret
           'for-plan': z.object({ username: z.string(), password: z.string() }),
           'for-apply': z.object({
             username: z.string(),
@@ -89,22 +65,13 @@ const getOneSchema = <TGrant extends Grant>(grant: TGrant) => {
   });
 };
 
-/**
- * .what = one schema per grant. apply = every secret required (the default);
- *         plan = the reader-denied secrets optional.
- * .why = getConfig picks which to parse with by grant (see getConfig.ts).
- */
+/** .what = one schema per grant; getConfig picks one at call time */
 export const schema = {
   apply: getOneSchema('apply'),
   plan: getOneSchema('plan'),
 } as const;
 
-/**
- * .what = the config type for a grant, default apply.
- * .why = Config (= Config<'apply'>) is the fully-required shape ordinary consumers
- *        get, so no `| undefined` leaks into the app's config type; Config<'plan'>
- *        is the opt-in narrowed shape whose reader-denied secrets may be absent.
- */
+/** .what = the config type for a grant; the default `apply` carries no `| undefined` */
 export type Config<TGrant extends Grant = 'apply'> = z.infer<
   (typeof schema)[TGrant]
 >;

package/dist/practices/persist-with-rds/best-practice/src/utils/database/asDatabaseClientSsl.test.ts

@@ -0,0 +1,82 @@
+import { ConstraintError, UnexpectedCodePathError } from 'helpful-errors';
+import { getError, given, then, when } from 'test-fns';
+
+import type { PeerCertificate } from 'node:tls';
+import { asDatabaseClientSsl } from './asDatabaseClientSsl';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+const CLUSTER_ENDPOINT = 'surfdb.cluster-abc123.us-east-1.rds.amazonaws.com';
+
+/**
+ * .what = a peer certificate shaped as the one an aurora cluster presents
+ * .why = checkServerIdentity reads only the subject and the subject alt names
+ */
+const certOfCluster = {
+  subject: { CN: CLUSTER_ENDPOINT },
+  subjectaltname: `DNS:${CLUSTER_ENDPOINT}`,
+} as PeerCertificate; // note: a partial cert; checkServerIdentity reads only these two fields
+
+describe('asDatabaseClientSsl', () => {
+  given('[case1] no cluster endpoint declared (the local testdb)', () => {
+    when('[t0] the ssl options are derived', () => {
+      then('the client connects plain', () => {
+        expect(asDatabaseClientSsl({ clusterEndpoint: null })).toEqual(false);
+      });
+    });
+  });
+
+  given('[case2] a us-east-1 cluster endpoint declared', () => {
+    const ssl =
+      asDatabaseClientSsl({ clusterEndpoint: CLUSTER_ENDPOINT }) ||
+      UnexpectedCodePathError.throw(
+        'a declared cluster endpoint must yield ssl options, never a plain connect',
+        { clusterEndpoint: CLUSTER_ENDPOINT },
+      );
+
+    when('[t0] the ssl options are derived', () => {
+      then('the chain is verified against the rds roots', () => {
+        expect(ssl.rejectUnauthorized).toEqual(true);
+        expect(ssl.ca).toEqual(RDS_CA_BUNDLE_US_EAST_1);
+      });
+    });
+
+    when('[t1] the dialed host is a local tunnel alias', () => {
+      then('the name check passes against the cluster endpoint', () => {
+        expect(
+          ssl.checkServerIdentity!('aws.ssmproxy.surfdb.prep', certOfCluster),
+        ).toEqual(undefined);
+      });
+    });
+
+    when('[t2] the certificate names a different host', () => {
+      then('the name check rejects it', () => {
+        const certOfImpostor = {
+          subject: { CN: 'impostor.example.com' },
+          subjectaltname: 'DNS:impostor.example.com',
+        } as PeerCertificate; // note: a partial cert; checkServerIdentity reads only these two fields
+        // node's Error lives in another realm than jest's, so assert on the message
+        expect(
+          ssl.checkServerIdentity!(CLUSTER_ENDPOINT, certOfImpostor)?.message,
+        ).toContain(`Host: ${CLUSTER_ENDPOINT}. is not in the cert's altnames`);
+      });
+    });
+  });
+
+  given('[case3] a cluster endpoint outside us-east-1', () => {
+    when('[t0] the ssl options are derived', () => {
+      then('it fails loud, with a hint to add that region bundle', async () => {
+        const error = await getError(async () =>
+          asDatabaseClientSsl({
+            clusterEndpoint:
+              'surfdb.cluster-abc123.eu-west-2.rds.amazonaws.com',
+          }),
+        );
+        expect(error).toBeInstanceOf(ConstraintError);
+        expect(error.message).toContain('not in us-east-1');
+        expect(JSON.stringify(error)).toContain(
+          'truststore.pki.rds.amazonaws.com',
+        );
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/best-practice/src/utils/database/asDatabaseClientSsl.ts

@@ -0,0 +1,52 @@
+import { ConstraintError } from 'helpful-errors';
+
+import { type ConnectionOptions, checkServerIdentity } from 'node:tls';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+/**
+ * .what = the aws region an rds endpoint lives in, read from its dns name
+ * .why = the ca bundle is per region, so the region decides which roots verify the cluster
+ */
+const asRdsEndpointRegion = (input: { endpoint: string }): string | null =>
+  /\.(?<region>[a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(
+    input.endpoint,
+  )?.groups?.region ?? null;
+
+/**
+ * .what = the tls options a pg client connects with, derived from the cluster endpoint
+ * .why = a cloud cluster is reached encrypted and verified (verify-full), so the connection
+ *        works whether or not the cluster forces ssl, and never trusts an impostor.
+ *        the local testdb declares no cluster endpoint and speaks no tls, so it connects plain
+ * .note = the name check pins to the cluster endpoint, never the dialed host: a local tunnel
+ *         dials an ssm proxy alias the certificate does not carry, and pg@8 overwrites any
+ *         servername option with the dialed host (lib/connection.js)
+ * .note = only the us-east-1 roots ship here. an endpoint in any other region fails loud, so a
+ *         cluster is never dialed with roots that cannot verify it
+ */
+export const asDatabaseClientSsl = (input: {
+  clusterEndpoint: string | null;
+}): ConnectionOptions | false => {
+  // no cluster endpoint declared, so this is the local testdb, which speaks no tls
+  if (!input.clusterEndpoint) return false;
+  const clusterEndpoint = input.clusterEndpoint;
+
+  // only the us-east-1 roots ship, so any other region must add its own bundle first
+  const region = asRdsEndpointRegion({ endpoint: clusterEndpoint });
+  if (region !== 'us-east-1')
+    throw new ConstraintError(
+      'the cluster endpoint is not in us-east-1, so no ca bundle here can verify it',
+      {
+        clusterEndpoint,
+        region,
+        hint: `add the rds ca bundle for that region (https://truststore.pki.rds.amazonaws.com/<region>/<region>-bundle.pem) beside rdsCaBundleUsEast1.ts, and pick it by region here`,
+      },
+    );
+
+  // verify the chain against the rds roots, and the name against the cluster endpoint
+  return {
+    ca: RDS_CA_BUNDLE_US_EAST_1,
+    rejectUnauthorized: true,
+    checkServerIdentity: (_hostDialed, cert) =>
+      checkServerIdentity(clusterEndpoint, cert),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/databaseClientTimeouts.ts

@@ -0,0 +1,14 @@
+import { toMilliseconds } from 'iso-time';
+
+/**
+ * .what = the connect and query bounds every pg client in this service carries
+ * .why = pg's defaults wait forever. a cluster that accepts the socket and never
+ *        answers — the shape of a major-version flip — would otherwise hold each
+ *        lambda for its full timeout, at full concurrency
+ * .note = connect outlasts an aurora serverless v2 resume from zero acu (~15s);
+ *         query sits under the lambda timeout so the error surfaces, never a kill
+ */
+export const databaseClientTimeouts = {
+  connectionTimeoutMillis: toMilliseconds({ seconds: 20 }),
+  query_timeout: toMilliseconds({ seconds: 30 }),
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabaseConnection.ts

@@ -1,8 +1,12 @@
 import { HelpfulError, UnexpectedCodePathError } from 'helpful-errors';
 import pg, { Client, type QueryResult, type QueryResultRow } from 'pg';
 
-import { getConfig } from '../config/getConfig';
-import { getEnvironment } from '../environment';
+import { getConfig } from '@src/utils/config/getConfig';
+import { getEnvironment } from '@src/utils/environment';
+
+import { asDatabaseClientSsl } from './asDatabaseClientSsl';
+import { databaseClientTimeouts } from './databaseClientTimeouts';
+import { getOneDatabasePort } from './getOneDatabasePort';
 
 // https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
 pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
@@ -39,11 +43,30 @@ values:
   }
 }
 
-export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> => {
+/**
+ * .what = opens one pg client on the tunnel for this environment, encrypted and bounded
+ * .why = the one place the app builds a pg client, so every connection carries the same tls,
+ *        the same timeouts, and the same DatabaseQueryError
+ * .note = mode 'readonly' reads config under the plan grant and connects as the cicd for-plan
+ *         role, then marks the session read only. the session mode is a guard against a slip,
+ *         not a security boundary: a query can still flip it back. the boundary is the for-plan
+ *         role's own grants
+ */
+export const getOneDatabaseConnection = async (
+  input: { mode: 'readwrite' | 'readonly' } = { mode: 'readwrite' },
+): Promise<DatabaseConnection> => {
   const environment = await getEnvironment();
-  const config = await getConfig();
+
+  // read the config under the grant the mode needs; readonly never reads a write credential
+  const config =
+    input.mode === 'readonly'
+      ? await getConfig({ grant: 'plan' })
+      : await getConfig();
   const target = config.database.target;
-  const role = config.database.role.crud;
+  const role =
+    input.mode === 'readonly'
+      ? config.database.role.cicd['for-plan']
+      : config.database.role.crud;
 
   // determine which tunnel to use based on environment.server
   const tunnel =
@@ -59,32 +82,38 @@ export const getOneDatabaseConnection = async (): Promise<DatabaseConnection> =>
     );
   }
 
-  // instantiate the client
+  // instantiate the client, encrypted and verified wherever a cluster endpoint is declared
   const client = new Client({
     host: tunnel.host,
-    port: tunnel.port,
+    port: getOneDatabasePort({
+      access: environment.access,
+      portDeclared: tunnel.port,
+    }), // a worktree's testdb binds a port of its own; the test harness declares it via TESTDB_PORT
     user: role.username,
     password: role.password,
     database: target.database,
+    ssl: asDatabaseClientSsl({
+      clusterEndpoint: config.database.tunnel.lambda?.host ?? null,
+    }),
+    ...databaseClientTimeouts,
   });
   await client.connect();
   await client.query(`SET search_path TO ${target.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
-  const dbConnection = {
-    query: ({ sql, values }: { sql: string; values?: unknown[] }) =>
-      client.query(sql, values),
-    end: () => client.end(),
-  };
+
+  // mark a readonly session read only, so a write from it fails loud
+  if (input.mode === 'readonly')
+    await client.query('SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;');
 
   // declare our interface
   return {
     query: (args: { sql: string; values?: unknown[] }) =>
-      dbConnection.query(args).catch((error) => {
+      client.query(args.sql, args.values).catch((error) => {
         throw new DatabaseQueryError({
           sql: args.sql,
           values: args.values,
           caught: error,
         });
       }),
-    end: () => dbConnection.end(),
+    end: () => client.end(),
   };
 };

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getOneDatabasePort.ts

@@ -0,0 +1,30 @@
+import { ConstraintError } from 'helpful-errors';
+
+/**
+ * .what = the host port a connection to the database should dial, for an access
+ * .why = a worktree's local testdb binds a port of its own, so the test harness declares that
+ *        port via TESTDB_PORT and the app dials it. the override is honored ONLY with test access,
+ *        so a stray TESTDB_PORT can never redirect a prep or prod connection
+ * .note = absent TESTDB_PORT, or any access other than test, keeps the declared port
+ */
+export const getOneDatabasePort = (
+  input: { access: string; portDeclared: number },
+  context: { env: NodeJS.ProcessEnv } = { env: process.env },
+): number => {
+  // only test access reaches the local testdb; every other access keeps its declared port
+  if (input.access !== 'test') return input.portDeclared;
+
+  // no override declared; the testdb binds the declared port
+  const portOverride = context.env.TESTDB_PORT;
+  if (portOverride === undefined || portOverride === '')
+    return input.portDeclared;
+
+  // a malformed override fails loud, so a typo never dials a port no db binds
+  const port = Number(portOverride);
+  if (!/^[0-9]+$/.test(portOverride) || port <= 0 || port > 65535)
+    throw new ConstraintError('TESTDB_PORT is not a valid port', {
+      portOverride,
+      hint: 'set TESTDB_PORT to a positive integer port, or unset it to dial the declared port',
+    });
+  return port;
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/rdsCaBundleUsEast1.test.ts

@@ -0,0 +1,51 @@
+import { given, then, useBeforeAll, when } from 'test-fns';
+
+import { X509Certificate } from 'node:crypto';
+import { RDS_CA_BUNDLE_US_EAST_1 } from './rdsCaBundleUsEast1';
+
+/**
+ * .what = split a pem bundle into one pem per certificate
+ * .why = node parses exactly one certificate per X509Certificate
+ */
+const asPemCertificates = (input: { bundle: string }): string[] =>
+  input.bundle.match(
+    /-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/g,
+  ) ?? [];
+
+/**
+ * .what = the common name a certificate's subject declares
+ * .why = the subject is one multi-line string; the CN line names the root
+ */
+const asCommonName = (input: { cert: X509Certificate }): string | null =>
+  input.cert.subject
+    .split('\n')
+    .find((line) => line.startsWith('CN='))
+    ?.slice('CN='.length) ?? null;
+
+describe('RDS_CA_BUNDLE_US_EAST_1', () => {
+  given('[case1] the embedded bundle', () => {
+    when('[t0] each certificate in it is parsed', () => {
+      const scene = useBeforeAll(async () => ({
+        certs: asPemCertificates({ bundle: RDS_CA_BUNDLE_US_EAST_1 }).map(
+          (pem) => new X509Certificate(pem),
+        ),
+      }));
+
+      then('it holds the three us-east-1 roots', () => {
+        expect(scene.certs.map((cert) => asCommonName({ cert }))).toEqual([
+          'Amazon RDS us-east-1 Root CA RSA2048 G1',
+          'Amazon RDS us-east-1 Root CA RSA4096 G1',
+          'Amazon RDS us-east-1 Root CA ECC384 G1',
+        ]);
+      });
+
+      then('each is a certificate authority that signed itself', () => {
+        for (const cert of scene.certs) {
+          expect(cert.ca).toEqual(true);
+          expect(cert.checkIssued(cert)).toEqual(true);
+          expect(cert.verify(cert.publicKey)).toEqual(true);
+        }
+      });
+    });
+  });
+});

package/dist/practices/persist-with-rds/best-practice/src/utils/database/rdsCaBundleUsEast1.ts

@@ -0,0 +1,86 @@
+/**
+ * .what = the aws rds root certificate authorities for us-east-1, as pem
+ * .why = verify-full checks the cluster's certificate against these roots, so a client
+ *        encrypts and knows it reached the real cluster rather than an impostor.
+ *        embedded as a constant, never a .pem file, so the lambda bundle always carries it
+ * .note = source: https://truststore.pki.rds.amazonaws.com/us-east-1/us-east-1-bundle.pem
+ *         roots: RSA2048 G1 (until 2061), RSA4096 G1 (until 2121), ECC384 G1 (until 2121)
+ */
+export const RDS_CA_BUNDLE_US_EAST_1 = `
+-----BEGIN CERTIFICATE-----
+MIID/zCCAuegAwIBAgIRAPVSMfFitmM5PhmbaOFoGfUwDQYJKoZIhvcNAQELBQAw
+gZcxCzAJBgNVBAYTAlVTMSIwIAYDVQQKDBlBbWF6b24gV2ViIFNlcnZpY2VzLCBJ
+bmMuMRMwEQYDVQQLDApBbWF6b24gUkRTMQswCQYDVQQIDAJXQTEwMC4GA1UEAwwn
+QW1hem9uIFJEUyB1cy1lYXN0LTEgUm9vdCBDQSBSU0EyMDQ4IEcxMRAwDgYDVQQH
+DAdTZWF0dGxlMCAXDTIxMDUyNTIyMzQ1N1oYDzIwNjEwNTI1MjMzNDU3WjCBlzEL
+MAkGA1UEBhMCVVMxIjAgBgNVBAoMGUFtYXpvbiBXZWIgU2VydmljZXMsIEluYy4x
+EzARBgNVBAsMCkFtYXpvbiBSRFMxCzAJBgNVBAgMAldBMTAwLgYDVQQDDCdBbWF6
+b24gUkRTIHVzLWVhc3QtMSBSb290IENBIFJTQTIwNDggRzExEDAOBgNVBAcMB1Nl
+YXR0bGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDu9H7TBeGoDzMr
+dxN6H8COntJX4IR6dbyhnj5qMD4xl/IWvp50lt0VpmMd+z2PNZzx8RazeGC5IniV
+5nrLg0AKWRQ2A/lGGXbUrGXCSe09brMQCxWBSIYe1WZZ1iU1IJ/6Bp4D2YEHpXrW
+bPkOq5x3YPcsoitgm1Xh8ygz6vb7PsvJvPbvRMnkDg5IqEThapPjmKb8ZJWyEFEE
+QRrkCIRueB1EqQtJw0fvP4PKDlCJAKBEs/y049FoOqYpT3pRy0WKqPhWve+hScMd
+6obq8kxTFy1IHACjHc51nrGII5Bt76/MpTWhnJIJrCnq1/Uc3Qs8IVeb+sLaFC8K
+DI69Sw6bAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFE7PCopt
+lyOgtXX0Y1lObBUxuKaCMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0BAQsFAAOC
+AQEAFj+bX8gLmMNefr5jRJfHjrL3iuZCjf7YEZgn89pS4z8408mjj9z6Q5D1H7yS
+jNETVV8QaJip1qyhh5gRzRaArgGAYvi2/r0zPsy+Tgf7v1KGL5Lh8NT8iCEGGXwF
+g3Ir+Nl3e+9XUp0eyyzBIjHtjLBm6yy8rGk9p6OtFDQnKF5OxwbAgip42CD75r/q
+p421maEDDvvRFR4D+99JZxgAYDBGqRRceUoe16qDzbMvlz0A9paCZFclxeftAxv6
+QlR5rItMz/XdzpBJUpYhdzM0gCzAzdQuVO5tjJxmXhkSMcDP+8Q+Uv6FA9k2VpUV
+E/O5jgpqUJJ2Hc/5rs9VkAPXeA==
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+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
+0Ws=
+-----END CERTIFICATE-----
+-----BEGIN CERTIFICATE-----
+MIICrjCCAjSgAwIBAgIRAPAlEk8VJPmEzVRRaWvTh2AwCgYIKoZIzj0EAwMwgZYx
+CzAJBgNVBAYTAlVTMSIwIAYDVQQKDBlBbWF6b24gV2ViIFNlcnZpY2VzLCBJbmMu
+MRMwEQYDVQQLDApBbWF6b24gUkRTMQswCQYDVQQIDAJXQTEvMC0GA1UEAwwmQW1h
+em9uIFJEUyB1cy1lYXN0LTEgUm9vdCBDQSBFQ0MzODQgRzExEDAOBgNVBAcMB1Nl
+YXR0bGUwIBcNMjEwNTI1MjI0MTU1WhgPMjEyMTA1MjUyMzQxNTVaMIGWMQswCQYD
+VQQGEwJVUzEiMCAGA1UECgwZQW1hem9uIFdlYiBTZXJ2aWNlcywgSW5jLjETMBEG
+A1UECwwKQW1hem9uIFJEUzELMAkGA1UECAwCV0ExLzAtBgNVBAMMJkFtYXpvbiBS
+RFMgdXMtZWFzdC0xIFJvb3QgQ0EgRUNDMzg0IEcxMRAwDgYDVQQHDAdTZWF0dGxl
+MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEx5xjrup8II4HOJw15NTnS3H5yMrQGlbj
+EDA5MMGnE9DmHp5dACIxmPXPMe/99nO7wNdl7G71OYPCgEvWm0FhdvVUeTb3LVnV
+BnaXt32Ek7/oxGk1T+Df03C+W0vmuJ+wo0IwQDAPBgNVHRMBAf8EBTADAQH/MB0G
+A1UdDgQWBBTGXmqBWN/1tkSea4pNw0oHrjk2UDAOBgNVHQ8BAf8EBAMCAYYwCgYI
+KoZIzj0EAwMDaAAwZQIxAIqqZWCSrIkZ7zsv/FygtAusW6yvlL935YAWYPVXU30m
+jkMFLM+/RJ9GMvnO8jHfCgIwB+whlkcItzE9CRQ6CsMo/d5cEHDUu/QW6jSIh9BR
+OGh9pTYPVkUbBiKPA7lVVhre
+-----END CERTIFICATE-----
+`.trim();

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseContext.ts

@@ -20,7 +20,8 @@ export interface DatabaseContext {
  *     // do logic with dbConnection
  *   });
  *   // ...
- *   await findById({ id: 821 }); // note how we don't have to pass in the dbConnection
+ *   await findById({ id: '821' }, {}); // the context is required, but the dbConnection within it is not
+ *   await findById({ id: '821' }, { dbConnection }); // pass one in to reuse it, e.g. inside a transaction
  * ```
  */
 export const withDatabaseContext = <P1, P2 extends DatabaseContext, R>(

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -7,10 +7,12 @@ import type { DatabaseConnection } from './getOneDatabaseConnection';
  * .why = gives any logic atomic semantics — every write commits together, or none
  *        does — without each op repeating the begin/commit/rollback dance. a partial
  *        write cannot survive a throw.
- * .note = the wrapper is ALWAYS async — it awaits the transaction — so its honest
- *         return type is `Promise<Awaited<R>>`, NOT `logic`'s `R | Promise<R>`. the
- *         return type is declared explicitly so no `as` cast is needed and no type
- *         lie is told: a caller of a sync `logic` correctly sees a Promise back.
+ * .note = the wrapper is ALWAYS async — it awaits the transaction — so its return
+ *         type is `Promise<R>`, NOT `logic`'s `R | Promise<R>`: a caller of a sync
+ *         `logic` sees a Promise back. `R` is already the resolved value, since ts
+ *         infers it from the `Promise<R>` arm of the union. `Promise<Awaited<R>>` is
+ *         wrong here: `await` of an unconstrained `R` types as `R`, which is not
+ *         assignable to `Awaited<R>`, so tsc fails inside this file.
  */
 export const withDatabaseTransaction = <
   P,
@@ -18,7 +20,7 @@ export const withDatabaseTransaction = <
   R,
 >(
   logic: (input: P, context: C) => R | Promise<R>,
-): ((input: P, context: C) => Promise<Awaited<R>>) => {
+): ((input: P, context: C) => Promise<R>) => {
   return async (input: P, context: C) => {
     await context.dbConnection.query({ sql: 'START TRANSACTION' }); // begin transaction
     try {