pipework 0.202.0 → 0.203.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.203.0
+
+- **Added: `pipe.tryAdvisoryLock`** (#775). The non-blocking form of `pipe.advisoryLock`: `pg_try_advisory_xact_lock` with the same three key forms and the same hashing, returning `true` if the lock was won and `false` at once if another transaction holds it. A lock won is held until commit or rollback, and `advisoryLock` and `tryAdvisoryLock` on the same arguments contend on the same lock.
+
 ## 0.202.0
 
 - **Added: `assign` on `alerts.clientFaults` and `alerts.requestFaults`** (#773). `assign(report)` (or `assign(fault)`) may return `{ owner?, runbook? }` to choose who gets that one alert. A field it leaves undefined keeps the app's (or the hook's) value. A request report whose refusal the server caused can now go to the server's owner, not the page's. For `clientFaults`, an `assign` that throws is handled the way a throwing `key` is: it is logged and recorded as a fault, nothing is raised, and the answer is still 204.

package/REFERENCE.md

@@ -865,6 +865,10 @@ Returns excluded-column references for onConflictDoUpdate set clauses.
 
 Acquires a transaction-scoped advisory lock. Released at commit/rollback.
 
+### `pipe.tryAdvisoryLock`
+
+Non-blocking advisoryLock: true if the transaction-scoped lock was won, false if another transaction holds it.
+
 ### `pipe.serializable`
 
 Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks.

package/dist/REFERENCE.md

@@ -1,7 +1,7 @@
 # Pipework API Reference
 
 > Auto-generated from source JSDoc. Do not edit manually.
-> Generated: 2026-10-22
+> Generated: 2026-10-09
 
 ## Contents
 
@@ -10,7 +10,6 @@
 - [jobs — Background Jobs](#jobs-background-jobs)
 - [pipeline — Multi-Step Pipelines](#pipeline-multi-step-pipelines)
 - [state — State Machines](#state-state-machines)
-- [steps](#steps)
 - [auth — Authentication](#auth-authentication)
 - [rbac — Access Control](#rbac-access-control)
 - [tenant — Multi-Tenancy](#tenant-multi-tenancy)
@@ -31,9 +30,7 @@
 - [cache — Caching](#cache-caching)
 - [credits](#credits)
 - [mail](#mail)
-- [untrustedFetch](#untrustedfetch)
 - [storage](#storage)
-- [support](#support)
 - [webhook — Inbound & Outbound Webhooks](#webhook-inbound-outbound-webhooks)
 - [behavior — Resource Decorators](#behavior-resource-decorators)
 - [fitting — Dependency Injection](#fitting-dependency-injection)
@@ -88,18 +85,6 @@ function createManifold<const TEnv extends EnvDefs = EnvDefs>( raw: Omit<Bluepri
 interface Manifold<TEnv extends EnvDefs = EnvDefs>
 ```
 
-**`ScriptOptions`** — Options for {@link Manifold.script}.
-
-```typescript
-interface ScriptOptions
-```
-
-**`StartOptions`** — Options for {@link Manifold.start}.
-
-```typescript
-interface StartOptions
-```
-
 **`SeedOptions`** — ALS context the {@link Manifold.seed} callback runs under — tenant scope, auth principal, and job type.
 
 ```typescript
@@ -244,14 +229,6 @@ Creates a job queue with claim/complete/fail lifecycle, heartbeat, and dead lett
 
 Executes a fitting handler as a background job with its own Flow context.
 
-### `jobs.later`
-
-The error to throw to end an attempt as "later": pending again after `delayMs`, no attempt counted.
-
-### `jobs.permanent`
-
-The error to throw to dead-letter the job now, whatever attempts remain.
-
 ### `jobs.parseCron`
 
 Parses a 5-field cron expression into a CronSchedule (minute, hour, dom, month, dow).
@@ -292,14 +269,6 @@ Thrown when a transition is not allowed from the current state.
 
 Thrown when the state machine definition is internally inconsistent.
 
-## steps
-
-Step graphs over a job queue: results recorded by their inputs, only missing steps run.
-
-### `steps.define`
-
-Defines a graph of named steps over a jobs Queue. Pass it to `createWorkerSurface({ graphs })` to run its steps.
-
 ## auth — Authentication
 
 Authentication namespace — session management, multi-org support, auth chain resolution.
@@ -320,10 +289,6 @@ Hashes and verifies passwords with scrypt; reports when a stored hash needs reha
 
 Guarded password sign-in that slows, then refuses, repeated failures per account and per client.
 
-### `auth.emailLinks`
-
-Emailed single-use links that prove control of an address: password reset and address verification; the token is never stored.
-
 ### `auth.runChain`
 
 Executes an auth chain (strategy pipeline) to resolve auth + tenant from a request.
@@ -358,7 +323,7 @@ interface AuthContext
 interface AuthStrategy<TAuth>
 ```
 
-**`AuthRequest`** — Normalized request shape passed to auth strategies — headers, the parsed `Cookie` header, and the upper-case HTTP method.
+**`AuthRequest`** — Normalized request shape passed to auth strategies — headers, cookies, method, url.
 
 ```typescript
 interface AuthRequest
@@ -388,18 +353,6 @@ interface TenantResolver<TAuth>
 interface AuthChainConfig<TAuth>
 ```
 
-**`SessionAuth`** — What `sessions.strategy()` authenticates: the token's user and org, its roles, and where the token came from.
-
-```typescript
-type SessionAuth = BaseAuth &
-```
-
-**`SessionStrategyOptions`** — Options for `sessions.strategy()`.
-
-```typescript
-interface SessionStrategyOptions
-```
-
 **`SessionConfig`** — Session configuration — signing keys, issuer, audience, token TTLs, refresh rotation.
 
 ```typescript
@@ -671,10 +624,6 @@ Base error class with code, statusCode, and suggestion fields.
 
 403 — authenticated but insufficient permissions.
 
-### `errors.CrossSiteRequest`
-
-403 `CROSS_SITE_REQUEST` — a cookie-authenticated write that did not come from the app's own site.
-
 ### `errors.Validation`
 
 422 — input validation failed, carries field-level details.
@@ -695,17 +644,13 @@ Base error class with code, statusCode, and suggestion fields.
 
 415 — request body media type not accepted by the route.
 
-### `errors.MalformedMultipart`
-
-400 `MALFORMED_MULTIPART` — a multipart body that cannot be parsed or ends before its closing boundary.
-
 ## lifecycle — Startup & Shutdown
 
 Application lifecycle namespace — startup orchestration with hooks and timeouts.
 
 ### `lifecycle.orchestrate`
 
-Runs pre-start hooks (DB readiness checks, migrations, etc.) with a configurable timeout. The hooks run in one trace that names the process; the trace-partition hook runs first, outside it.
+Runs pre-start hooks (DB readiness checks, migrations, etc.) with a configurable timeout.
 
 ## log — Structured Logging
 
@@ -745,7 +690,7 @@ Creates a worker surface — a long-running process that claims and executes job
 
 ### `surface.script`
 
-Creates a script surface — a one-shot process that runs and exits (migrations, seeds, CLI tools). The run is traced as a job-kind trace that names the surface.
+Creates a script surface — a one-shot process that runs and exits (migrations, seeds, CLI tools).
 
 ## pipe — Database
 
@@ -816,10 +761,6 @@ Acquires a transaction-scoped advisory lock. Released at commit/rollback.
 
 Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks.
 
-### `pipe.withTimeouts`
-
-Sets statement_timeout and/or lock_timeout for the current transaction in one statement, then runs fn; a statement cancelled for them rejects with StatementTimeoutError or LockTimeoutError.
-
 ### `pipe.bulkSet`
 
 Bulk UPDATE ... FROM (VALUES ...) — updates multiple rows with per-row values in a single statement.
@@ -828,10 +769,6 @@ Bulk UPDATE ... FROM (VALUES ...) — updates multiple rows with per-row values
 
 Produces a typed VALUES clause for bulk operations — the base primitive for bulkSet and bulkUpsert.
 
-### `pipe.fn`
-
-A set-returning SQL function as a typed source for `.from()` and joins — `pipe.fn('schema.f', { args: [field.uuid()], columns: { path: field.text() } })`. Arguments are bound and cast to their declared types.
-
 ### `pipe.field`
 
 Field builders for domain definitions — uuid(), text(), integer(), etc.
@@ -844,17 +781,13 @@ Registers a domain definition with table, validators, and factory projections. T
 
 Returns the global registry of all domain definitions.
 
-### `pipe.external`
-
-Declares a table or view another service owns (`pipe.external(name, fields, { schema, table? })`): typed columns and every query operator, read-only, never migrated, not tenant-scoped.
-
 ### `pipe.update`
 
 Pipework-owned UPDATE builder — the only consumer-facing way to update pipework-managed tables (Q8).
 
 ### `pipe.insert`
 
-Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction.
+Pipework-owned INSERT builder — the only consumer-facing way to insert into pipework-managed tables (Q8).
 
 ### `pipe.delete`
 
@@ -862,7 +795,7 @@ Pipework-owned DELETE builder — the only consumer-facing way to delete from pi
 
 ### `pipe.upsert`
 
-Pipework-owned UPSERT builder — insert with conflict resolution (Q8). A list of any size is split into statements under Postgres's parameter limit, in one transaction; rows repeating a conflict key across statements do not fail as one statement would.
+Pipework-owned UPSERT builder — insert with conflict resolution (Q8).
 
 ### Types
 
@@ -878,54 +811,12 @@ interface WindowSpec
 interface ValueColumnDef
 ```
 
-**`JsonbElements`** — A jsonb array read as its elements' text. Produced by {@link jsonbElements}.
-
-```typescript
-interface JsonbElements
-```
-
-**`ArraySource`** — Something whose elements `arrayAny` / `arrayAll` can test.
-
-```typescript
-type ArraySource =
-```
-
-**`ElementOf`** — The element type of an {@link ArraySource}.
-
-```typescript
-type ElementOf<S> =
-```
-
-**`FunctionSpec`** — Declares a SQL function's argument and result-column shapes. See {@link fn}.
-
-```typescript
-interface FunctionSpec<TArgs extends readonly AnyField[], TColumns extends Record<string, AnyField>>
-```
-
-**`FunctionSourceFields`** — The selected fields of a function source: each result column as a typed SQL expression.
-
-```typescript
-type FunctionSourceFields<TColumns extends Record<string, AnyField>> =
-```
-
-**`FunctionSource`** — A function call usable in `.from()` and joins; its result columns are properties of it.
-
-```typescript
-type FunctionSource<TAlias extends string, TColumns extends Record<string, AnyField>> =
-```
-
 **`SerializableOptions`** — Retry policy for {@link serializable}: how many attempts on a serialization failure / deadlock, and the base backoff between them.
 
 ```typescript
 interface SerializableOptions
 ```
 
-**`TimeoutOptions`** — Which timeouts {@link withTimeouts} sets; each a positive integer number of milliseconds.
-
-```typescript
-interface TimeoutOptions
-```
-
 **`ManagedConnection`** — A standalone pooled connection: the raw postgres.js client, its drizzle handle, and a `close()` that ends the pool.
 
 ```typescript
@@ -946,10 +837,6 @@ JSONB query operators — typed helpers for PostgreSQL JSONB containment, key ch
 
 The @> containment operator — tests whether a JSONB column contains the given value.
 
-### `jsonb.merge`
-
-Merges an object into a JSONB column in `.set()`: `coalesce(col, '{}') || value`. Top-level keys overwrite; others are kept.
-
 ### `jsonb.containedBy`
 
 The <@ contained-by operator — tests whether a JSONB column is contained by the given value.
@@ -1016,60 +903,6 @@ type Schema<T = unknown> = z.ZodType<T>
 type Infer<T extends Schema> = z.infer<T>
 ```
 
-**`StringSchema`** — A string validator — what check.string() returns, nameable without importing zod.
-
-```typescript
-interface StringSchema extends z.ZodString
-```
-
-**`NumberSchema`** — A number validator — what check.number() returns.
-
-```typescript
-interface NumberSchema extends z.ZodNumber
-```
-
-**`BooleanSchema`** — A boolean validator — what check.boolean() returns.
-
-```typescript
-interface BooleanSchema extends z.ZodBoolean
-```
-
-**`EnumSchema`** — An enum validator over string literals — what check.enum([...]) returns.
-
-```typescript
-interface EnumSchema<V extends string = string> extends z.ZodEnum<
-```
-
-**`LiteralSchema`** — A literal validator — what check.literal(v) returns.
-
-```typescript
-interface LiteralSchema<V extends string | number | boolean | null = string> extends z.ZodLiteral<V>
-```
-
-**`ArraySchema`** — An array validator — what check.array(item) returns.
-
-```typescript
-interface ArraySchema<Item extends z.core.SomeType = z.core.SomeType> extends z.ZodArray<Item>
-```
-
-**`OptionalSchema`** — An optional validator — what check.optional(inner) returns.
-
-```typescript
-interface OptionalSchema<Inner extends z.core.SomeType = z.core.SomeType> extends z.ZodOptional<Inner>
-```
-
-**`NullableSchema`** — A nullable validator — what check.nullable(inner) returns.
-
-```typescript
-interface NullableSchema<Inner extends z.core.SomeType = z.core.SomeType> extends z.ZodNullable<Inner>
-```
-
-**`ObjectSchema`** — An object validator whose .extend, .pick, .omit and .partial results stay ObjectSchema — what check.object({...}) returns.
-
-```typescript
-type ObjectSchema<S extends Shape = Shape> =
-```
-
 ## temporal — Bitemporal Data
 
 Temporal (bitemporal) data namespace — version history with effective date ranges.
@@ -1114,14 +947,6 @@ Query all versions of temporal records (no date filter).
 
 Close the current version and create a new one with updated data.
 
-### `temporal.setVersion`
-
-Append the next version of an append-only-versions definition: serialised per scope, numbered, never back-dated, audited.
-
-### `temporal.versionAt`
-
-The version in force at a moment: the row with the greatest effectiveFrom at or before it.
-
 ## valve
 
 Valve namespace — typed, directional, gated boundaries between code silos.
@@ -1304,18 +1129,6 @@ Alerts namespace — raise and resolve keyed conditions, grouped, delivered to s
 
 Creates an alerts handle.
 
-### `alerts.http`
-
-Routes for an operations agent: list, get, totals, delivery health, acknowledge, resolve, link; bearer credentials.
-
-### `alerts.clientFaults`
-
-One POST route that records failures reported by browser code as a trace step and an alert; answers 204, no session needed. Send with `reportClientFault` from `pipework/client`.
-
-### `alerts.requestFaults`
-
-An `onInternalError` hook for the HTTP server: raises `request-fault:<METHOD> <route>` for each internal 500.
-
 ### `alerts.webhook`
 
 A sink that POSTs the alert as signed JSON to a URL.
@@ -1348,10 +1161,6 @@ The newest record's `{ seq, hash }` in the tenant's audit hash chain (blueprint
 
 Walks the tenant's audit hash chain and reports the first break (hash-mismatch, prev-mismatch, missing, head-mismatch, anchor-mismatch), or `{ ok: true }`.
 
-### `audit.removeTenant`
-
-Deletes every audit record of one tenant and its hash chain, for the closure of that tenant's account. Irreversible; returns the number of records removed. Other tenants' records and chains are untouched.
-
 ## cache — Caching
 
 In-memory caching namespace — TTL-based with stats, preload, and tenant-aware variants.
@@ -1404,36 +1213,6 @@ Inbound source: SES receipt rule storing raw messages in S3 and notifying a sign
 
 Inbound development source: `.eml` files dropped in a folder, received by `scan()`; refused in production.
 
-## untrustedFetch
-
-Untrusted fetch — fetch one URL a stranger gave without letting them reach the app's private network.
-
-### `untrustedFetch.get`
-
-Fetches `url` with GET and returns `{ ok: true, url, status, contentType, body, bytes }`, or `{ ok: false, reason, message }`
-naming the rule that refused: `scheme`, `address`, `redirects`, `too_large`, `timeout`, `status`, `rejected` or `network`.
-It does not throw for these.
-
-Rules, none of which can be switched off: only `http:` and `https:`; the name is resolved and every address is checked
-(loopback, private, link-local including cloud metadata, CGNAT, unique-local and site-local IPv6, multicast, reserved,
-unspecified, and IPv4-mapped or NAT64 forms of these; literal IP URLs likewise) and the connection goes to a checked
-address; redirects are followed up to `maxRedirects` and each hop is checked as the first, and the app's `headers` go only to the first origin;
-the body is stopped the moment it passes `maxBytes`, whatever Content-Length says; `timeoutMs` covers the whole fetch.
-`accept({ status, contentType, firstBytes })` sees the first 1024 bytes before the body is kept: return false, or a string
-(your own message), to refuse with `rejected`. Messages never contain an address or anything a server sent.
-
-`resolve` and `connect` are for tests: `resolve(hostname)` replaces DNS and `connect(target)` replaces the socket after the
-address check passed, so a test sends a fake public address to a local server. The address check always runs on what `resolve` returns.
-
-The call is the trace step `pipework/fetch:get`; its child `pipework/fetch:outcome` carries host, status, bytes and reason.
-The full URL is recorded only when `urlIsSafeToTrace` is true; otherwise only the host.
-
-```ts
-const got = await untrustedFetch.get(pasted, { maxBytes: 5_000_000, timeoutMs: 10_000, maxRedirects: 3,
-  accept: h => h.firstBytes[0] === 0x25 || 'That does not look like a PDF.' })
-if (!got.ok) return tell(got.message)
-```
-
 ## storage
 
 Storage namespace — tenant-scoped, content-addressed file storage with signed URLs and retention.
@@ -1450,18 +1229,6 @@ S3-compatible backend (AWS S3, MinIO, R2): SigV4 over `fetch`, multipart streami
 
 Local-disk backend for development and tests; refused in production.
 
-## support
-
-Support namespace — tickets from email (and later chat), with replies sent only after an approval.
-
-### `support.create`
-
-Creates the support handle: tickets, messages, notes, links, drafts, `approve`, `receiveEmail`, and the events job.
-
-### `support.templates`
-
-The reply template to spread into `mail.create({ templates })`; it renders the approved draft verbatim.
-
 ## webhook — Inbound & Outbound Webhooks
 
 Webhook namespace — inbound verification, outbound delivery with retries, HMAC signing.
@@ -1552,10 +1319,6 @@ Returns the current Flow or undefined — use for optional context detection.
 
 Creates a Flow for test isolation with optional auth and tenant overrides.
 
-### `flow.actAs`
-
-Runs `fn` as a tenant and user chosen inside a tenantless Flow (sign-up, a public sign-in): RLS, audit and trace under that tenant, on the request's transaction.
-
 ## http — Server
 
 HTTP namespace: `http.file()` builds a file response; the server itself is managed by manifold.start().
@@ -1580,40 +1343,6 @@ interface SecurityConfig
 interface RateLimitConfig
 ```
 
-**`RateLimitWindow`** — One fixed window: at most `max` requests per `windowSeconds`.
-
-```typescript
-interface RateLimitWindow
-```
-
-**`RateLimitClass`**
-
-A named limit class: any of a per-user, per-tenant, per-address and total window, each counted on its own.
-Each key takes one window or an array of windows (distinct `windowSeconds`); a request is counted against
-all of a key's windows and refused if any is over.
-
-```typescript
-interface RateLimitClass
-```
-
-**`RateLimitRefusal`** — What `onRefused` is told about one refused window of one request.
-
-```typescript
-interface RateLimitRefusal
-```
-
-**`RateLimitClassesConfig`**
-
-Named limit classes, checked after auth and counted in Postgres (`pipework_rate_limit_counts`, opted in
-with the blueprint's `rateLimits: {}`), so every server process on the same database shares one count.
-Keys are counted perUser, perTenant, perAddress, total in turn, up to the first key with a window over its max, so one user's
-refused requests don't spend the tenant's budget. The 429's Retry-After is the longest wait of the windows that refused. A route is in `signedIn` (auth required, or optional with
-a user), `public` (no auth, or optional without a user) or the class its fitting names with `.rateLimit(name)`.
-
-```typescript
-interface RateLimitClassesConfig
-```
-
 **`InjectOptions`** — Options for server.inject() — method, url, headers, payload for testing without HTTP.
 
 ```typescript
@@ -1632,12 +1361,6 @@ interface InjectResponse
 interface ServerConfig
 ```
 
-**`InternalErrorFault`** — What `onInternalError` is told about one request that ended in an internal error.
-
-```typescript
-interface InternalErrorFault
-```
-
 **`HandlerResponse`** — Standard handler response shape — statusCode, headers, body.
 
 ```typescript
@@ -1696,7 +1419,7 @@ Generates an OpenAPI 3.1 document from route registrations — schemas derived f
 
 ## trace
 
-Trace namespace — hand the current trace to a process outside Node, record the steps it reports back, mark point events, and read a trace tree.
+Trace namespace — hand the current trace to a process outside Node and record the steps it reports back.
 
 ### `trace.traceparent`
 
@@ -1710,15 +1433,6 @@ W3C `traceparent` for the current trace and open step; `null` outside a traced f
 
 Records steps reported as JSON lines (or objects) by an outside process under the step open now. Synchronous; never throws.
 
-### `trace.event`
-
-Records one zero-length step `external:<name>` under the step open now, with an optional `capture` and `error`. A no-op outside a traced flow; never throws.
-
-### `trace.tree`
-
-Reads every hot trace sharing `rootId` (a request's trace and the jobs it queued) with their steps. Runs on the
-given `db`, so tenant policies apply: only an unrestricted connection (table owner, tests) sees every tenant's rows.
-
 ### Types
 
 **`FlowStepMeta`** — Trace metadata for one documented flow-step: its `path:symbol` graph node id and the per-argument capture projections.
@@ -1739,40 +1453,17 @@ type ExternalStepReport = z.infer<typeof externalStepReportSchema>
 interface ExternalRecordResult
 ```
 
-**`TraceStepNode`** — One step of a trace. `ref` is the flow step's `path:symbol`, or `external:<name>` for a recorded or point-event step.
-
-```typescript
-interface TraceStepNode
-```
-
-**`TraceNode`** — One trace of the tree, with its steps ordered by `seq`.
-
-```typescript
-interface TraceNode
-```
-
-**`TraceTree`** — The traces that share a root id, ordered by when they opened.
-
-```typescript
-interface TraceTree
-```
-
 ## data
 
-### `StatementTimeoutError`
-
-A statement was cancelled by Postgres for running past the statement timeout a {@link withTimeouts} call set. `cause` is the driver error.
-
-```typescript
-class StatementTimeoutError extends Error constructor(readonly statementTimeoutMs: number, cause: unknown)
-```
-
-### `LockTimeoutError`
+### `tap`
 
-A statement gave up waiting for a lock past the lock timeout a {@link withTimeouts} call set. `cause` is the driver error.
+Opens a standalone managed connection outside the manifold's pools — the
+sanctioned door for contexts where `pipe()` structurally cannot resolve:
+`worker_threads`, detached monitors, one-off scripts. Callers own the
+lifecycle: always `await conn.close()`.
 
 ```typescript
-class LockTimeoutError extends Error constructor(readonly lockTimeoutMs: number, cause: unknown)
+function tap(url: string, options?: ConnectOptions): ManagedConnection
 ```
 
 ## request

package/dist/data/db/advisory-lock.d.ts

@@ -6,4 +6,10 @@ import type { DB } from './types.js';
  */
 export declare function advisoryLock(db: DB, namespace: number, key: string): Promise<void>;
 export declare function advisoryLock(db: DB, ...keys: string[]): Promise<void>;
+/** Non-blocking advisoryLock: takes the same lock (same key forms, same hashing) if it is free
+ * and returns true, or returns false at once when another transaction holds it.
+ * A lock won is held until commit/rollback.
+ */
+export declare function tryAdvisoryLock(db: DB, namespace: number, key: string): Promise<boolean>;
+export declare function tryAdvisoryLock(db: DB, ...keys: string[]): Promise<boolean>;
 //# sourceMappingURL=advisory-lock.d.ts.map

package/dist/data/db/advisory-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"advisory-lock.d.ts","sourceRoot":"","sources":["../../../src/data/db/advisory-lock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,YAAY,CAAA;AAEpC;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AACzF,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}
+{"version":3,"file":"advisory-lock.d.ts","sourceRoot":"","sources":["../../../src/data/db/advisory-lock.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAO,MAAM,YAAY,CAAA;AA8BzC;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AACzF,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAM5E;;;GAGG;AACH,wBAAsB,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAC/F,wBAAsB,eAAe,CAAC,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA"}

package/dist/data/db/advisory-lock.js

@@ -1,26 +1,33 @@
 import { sql } from './sql.js';
-export async function advisoryLock(db, first, ...rest) {
+/** Validates the key arguments and builds the lock-argument fragment shared by
+ * advisoryLock and tryAdvisoryLock, so the two can never disagree about a key. */
+function lockArguments(fn, first, rest) {
     if (typeof first === 'number') {
         const key = rest[0];
         if (key === undefined) {
-            throw new Error('[pipework] advisoryLock(db, namespace, key) requires a key string.\n\n' +
-                '  advisoryLock(db, 1001, \'my-entity\')  — numeric namespace + string key\n' +
-                '  advisoryLock(db, \'key1\', \'key2\')      — two hashed string keys\n');
+            throw new Error(`[pipework] ${fn}(db, namespace, key) requires a key string.\n\n` +
+                `  ${fn}(db, 1001, 'my-entity')  — numeric namespace + string key\n` +
+                `  ${fn}(db, 'key1', 'key2')      — two hashed string keys\n`);
         }
-        await db.execute(sql `SELECT pg_advisory_xact_lock(${first}, hashtext(${key}))`);
-        return;
+        return sql `${first}, hashtext(${key})`;
     }
     if (first === undefined) {
-        throw new Error('[pipework] advisoryLock requires at least one key.\n\n' +
-            '  advisoryLock(db, \'my-lock\')             — single hashed key\n' +
-            '  advisoryLock(db, \'key1\', \'key2\')        — two hashed keys\n' +
-            '  advisoryLock(db, 1001, \'my-entity\')    — numeric namespace + hashed key\n');
-    }
-    if (rest.length === 0) {
-        await db.execute(sql `SELECT pg_advisory_xact_lock(hashtext(${first}))`);
-    }
-    else {
-        await db.execute(sql `SELECT pg_advisory_xact_lock(hashtext(${first}), hashtext(${rest[0]}))`);
+        throw new Error(`[pipework] ${fn} requires at least one key.\n\n` +
+            `  ${fn}(db, 'my-lock')             — single hashed key\n` +
+            `  ${fn}(db, 'key1', 'key2')        — two hashed keys\n` +
+            `  ${fn}(db, 1001, 'my-entity')    — numeric namespace + hashed key\n`);
     }
+    if (rest.length === 0)
+        return sql `hashtext(${first})`;
+    return sql `hashtext(${first}), hashtext(${rest[0]})`;
+}
+export async function advisoryLock(db, first, ...rest) {
+    const args = lockArguments('advisoryLock', first, rest);
+    await db.execute(sql `SELECT pg_advisory_xact_lock(${args})`);
+}
+export async function tryAdvisoryLock(db, first, ...rest) {
+    const args = lockArguments('tryAdvisoryLock', first, rest);
+    const rows = await db.execute(sql `SELECT pg_try_advisory_xact_lock(${args}) AS locked`);
+    return rows[0]?.['locked'] === true;
 }
 //# sourceMappingURL=advisory-lock.js.map

package/dist/data/db/advisory-lock.js.map

@@ -1 +1 @@
-{"version":3,"file":"advisory-lock.js","sourceRoot":"","sources":["../../../src/data/db/advisory-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAU9B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAM,EAAE,KAAuB,EAAE,GAAG,IAAc;IACnF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,wEAAwE;gBACxE,6EAA6E;gBAC7E,wEAAwE,CACzE,CAAA;QACH,CAAC;QACD,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,gCAAgC,KAAK,cAAc,GAAG,IAAI,CAAC,CAAA;QAC/E,OAAM;IACR,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,wDAAwD;YACxD,mEAAmE;YACnE,mEAAmE;YACnE,+EAA+E,CAChF,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,yCAAyC,KAAK,IAAI,CAAC,CAAA;IACzE,CAAC;SAAM,CAAC;QACN,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,yCAAyC,KAAK,eAAe,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,CAAA;IAChG,CAAC;AACH,CAAC"}
+{"version":3,"file":"advisory-lock.js","sourceRoot":"","sources":["../../../src/data/db/advisory-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAG9B;kFACkF;AAClF,SAAS,aAAa,CAAC,EAAU,EAAE,KAAkC,EAAE,IAAc;IACnF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,cAAc,EAAE,iDAAiD;gBACjE,KAAK,EAAE,6DAA6D;gBACpE,KAAK,EAAE,sDAAsD,CAC9D,CAAA;QACH,CAAC;QACD,OAAO,GAAG,CAAA,GAAG,KAAK,cAAc,GAAG,GAAG,CAAA;IACxC,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,cAAc,EAAE,iCAAiC;YACjD,KAAK,EAAE,mDAAmD;YAC1D,KAAK,EAAE,iDAAiD;YACxD,KAAK,EAAE,+DAA+D,CACvE,CAAA;IACH,CAAC;IAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAA,YAAY,KAAK,GAAG,CAAA;IACrD,OAAO,GAAG,CAAA,YAAY,KAAK,eAAe,IAAI,CAAC,CAAC,CAAE,GAAG,CAAA;AACvD,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAM,EAAE,KAAuB,EAAE,GAAG,IAAc;IACnF,MAAM,IAAI,GAAG,aAAa,CAAC,cAAc,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;IACvD,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,gCAAgC,IAAI,GAAG,CAAC,CAAA;AAC9D,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EAAM,EAAE,KAAuB,EAAE,GAAG,IAAc;IACtF,MAAM,IAAI,GAAG,aAAa,CAAC,iBAAiB,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA;IAC1D,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,oCAAoC,IAAI,aAAa,CAAC,CAAA;IACvF,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;AACrC,CAAC"}

package/dist/data/db/namespace.d.ts

@@ -2,7 +2,7 @@ import { pipe as getDb, pipeSystem, pipeDoor } from './db.js';
 import { sql } from './sql.js';
 import { migrateAll, migrateOne } from '../migrate/index.js';
 import { excluded } from './excluded.js';
-import { advisoryLock } from './advisory-lock.js';
+import { advisoryLock, tryAdvisoryLock } from './advisory-lock.js';
 import { serializable } from './serializable.js';
 import { withTimeouts } from './timeouts.js';
 import { bulkSet } from './bulk-set.js';
@@ -161,6 +161,8 @@ export declare const pipe: typeof getDb & {
     excluded: typeof excluded;
     /** Acquires a transaction-scoped advisory lock. Released at commit/rollback. */
     advisoryLock: typeof advisoryLock;
+    /** Non-blocking advisoryLock: true if the transaction-scoped lock was won, false if another transaction holds it. */
+    tryAdvisoryLock: typeof tryAdvisoryLock;
     /** Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks. */
     serializable: typeof serializable;
     /** Sets statement_timeout and/or lock_timeout for the current transaction in one statement, then runs fn; a statement cancelled for them rejects with StatementTimeoutError or LockTimeoutError. */

package/dist/data/db/namespace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../../src/data/db/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGnM,OAAO,EAAS,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAGzE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE3E,6EAA6E;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,6EAA6E;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,mJAAmJ;AACnJ,eAAO,MAAM,IAAI;IACf,iQAAiQ;;IAGjQ,6QAA6Q;;IAG7Q,6EAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAG7E,+RAA+R;;;;;;;;;;;;;IAkB/R,oDAAoD;;IAEpD,mDAAmD;;IAGnD,6EAA6E;;IAG7E,gFAAgF;;IAGhF,kHAAkH;;IAGlH,oMAAoM;;IAGpM,2GAA2G;;IAG3G,0GAA0G;;IAG1G,uNAAuN;;IAGvN,8EAA8E;;;;;;;;;;;;;;;;;;;;;;;IAE9E,qMAAqM;;IAErM,6DAA6D;;IAE7D,+LAA+L;;IAG/L,2GAA2G;;IAE3G,kNAAkN;;IAElN,gHAAgH;;IAEhH,kQAAkQ;;CAElQ,CAAA"}
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../../src/data/db/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGnM,OAAO,EAAS,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAGzE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE3E,6EAA6E;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,6EAA6E;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,mJAAmJ;AACnJ,eAAO,MAAM,IAAI;IACf,iQAAiQ;;IAGjQ,6QAA6Q;;IAG7Q,6EAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAG7E,+RAA+R;;;;;;;;;;;;;IAkB/R,oDAAoD;;IAEpD,mDAAmD;;IAGnD,6EAA6E;;IAG7E,gFAAgF;;IAGhF,qHAAqH;;IAGrH,kHAAkH;;IAGlH,oMAAoM;;IAGpM,2GAA2G;;IAG3G,0GAA0G;;IAG1G,uNAAuN;;IAGvN,8EAA8E;;;;;;;;;;;;;;;;;;;;;;;IAE9E,qMAAqM;;IAErM,6DAA6D;;IAE7D,+LAA+L;;IAG/L,2GAA2G;;IAE3G,kNAAkN;;IAElN,gHAAgH;;IAEhH,kQAAkQ;;CAElQ,CAAA"}

package/dist/data/db/namespace.js

@@ -3,7 +3,7 @@ import { sql } from './sql.js';
 import { migrateAll, migrateOne } from '../migrate/index.js';
 import { filter } from './filter.js';
 import { excluded } from './excluded.js';
-import { advisoryLock } from './advisory-lock.js';
+import { advisoryLock, tryAdvisoryLock } from './advisory-lock.js';
 import { serializable } from './serializable.js';
 import { withTimeouts } from './timeouts.js';
 import { bulkSet } from './bulk-set.js';
@@ -48,6 +48,8 @@ export const pipe = Object.assign(getDb, {
     excluded,
     /** Acquires a transaction-scoped advisory lock. Released at commit/rollback. */
     advisoryLock,
+    /** Non-blocking advisoryLock: true if the transaction-scoped lock was won, false if another transaction holds it. */
+    tryAdvisoryLock,
     /** Runs a function in a SERIALIZABLE transaction with automatic retry on serialization failures and deadlocks. */
     serializable,
     /** Sets statement_timeout and/or lock_timeout for the current transaction in one statement, then runs fn; a statement cancelled for them rejects with StatementTimeoutError or LockTimeoutError. */

package/dist/data/db/namespace.js.map

@@ -1 +1 @@
-{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../../src/data/db/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAEnM,qBAAqB;AACrB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAKzE,6EAA6E;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,6EAA6E;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,mJAAmJ;AACnJ,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE;IACvC,iQAAiQ;IACjQ,MAAM,EAAE,UAAU;IAElB,6QAA6Q;IAC7Q,IAAI,EAAE,QAAQ;IAEd,6EAA6E;IAC7E,MAAM;IAEN,+RAA+R;IAC/R,GAAG;IAEH,kGAAkG;IAClG,eAAe;IACf,YAAY;IACZ,kBAAkB;IAClB,eAAe;IACf,YAAY;IACZ,WAAW;IACX,qBAAqB;IACrB,OAAO;IAEP,qDAAqD;IACrD,UAAU;IACV,SAAS;IACT,SAAS;IAET,oDAAoD;IACpD,OAAO,EAAE,UAAU;IACnB,mDAAmD;IACnD,UAAU;IAEV,6EAA6E;IAC7E,QAAQ;IAER,gFAAgF;IAChF,YAAY;IAEZ,kHAAkH;IAClH,YAAY;IAEZ,oMAAoM;IACpM,YAAY;IAEZ,2GAA2G;IAC3G,OAAO;IAEP,0GAA0G;IAC1G,MAAM;IAEN,uNAAuN;IACvN,EAAE;IAEF,8EAA8E;IAC9E,KAAK;IACL,qMAAqM;IACrM,MAAM;IACN,6DAA6D;IAC7D,WAAW;IACX,+LAA+L;IAC/L,QAAQ;IAER,2GAA2G;IAC3G,MAAM;IACN,kNAAkN;IAClN,MAAM;IACN,gHAAgH;IAChH,MAAM,EAAE,MAAM;IACd,kQAAkQ;IAClQ,MAAM;CACP,CAAC,CAAA"}
+{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../../src/data/db/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC7D,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAA;AAC9B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAA;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAEnM,qBAAqB;AACrB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAKzE,6EAA6E;AAC7E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC,6EAA6E;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC,mJAAmJ;AACnJ,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE;IACvC,iQAAiQ;IACjQ,MAAM,EAAE,UAAU;IAElB,6QAA6Q;IAC7Q,IAAI,EAAE,QAAQ;IAEd,6EAA6E;IAC7E,MAAM;IAEN,+RAA+R;IAC/R,GAAG;IAEH,kGAAkG;IAClG,eAAe;IACf,YAAY;IACZ,kBAAkB;IAClB,eAAe;IACf,YAAY;IACZ,WAAW;IACX,qBAAqB;IACrB,OAAO;IAEP,qDAAqD;IACrD,UAAU;IACV,SAAS;IACT,SAAS;IAET,oDAAoD;IACpD,OAAO,EAAE,UAAU;IACnB,mDAAmD;IACnD,UAAU;IAEV,6EAA6E;IAC7E,QAAQ;IAER,gFAAgF;IAChF,YAAY;IAEZ,qHAAqH;IACrH,eAAe;IAEf,kHAAkH;IAClH,YAAY;IAEZ,oMAAoM;IACpM,YAAY;IAEZ,2GAA2G;IAC3G,OAAO;IAEP,0GAA0G;IAC1G,MAAM;IAEN,uNAAuN;IACvN,EAAE;IAEF,8EAA8E;IAC9E,KAAK;IACL,qMAAqM;IACrM,MAAM;IACN,6DAA6D;IAC7D,WAAW;IACX,+LAA+L;IAC/L,QAAQ;IAER,2GAA2G;IAC3G,MAAM;IACN,kNAAkN;IAClN,MAAM;IACN,gHAAgH;IAChH,MAAM,EAAE,MAAM;IACd,kQAAkQ;IAClQ,MAAM;CACP,CAAC,CAAA"}

package/dist/infra/email/sigv4.d.ts

@@ -0,0 +1,24 @@
+export interface AwsCredentials {
+    readonly accessKeyId: string;
+    readonly secretAccessKey: string;
+    readonly sessionToken?: string;
+}
+export interface SigV4Request {
+    readonly method: string;
+    readonly url: string;
+    /** Headers to sign and send, other than host and x-amz-date, which are added. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string | Buffer;
+    readonly region: string;
+    readonly service: string;
+    readonly credentials: AwsCredentials;
+    readonly now?: Date;
+}
+/**
+ * Signs a request with AWS Signature Version 4 and returns the headers to send:
+ * the given ones, `x-amz-date`, `x-amz-security-token` when the credentials carry
+ * a session token, and `authorization`. `host` is signed but not returned; the
+ * HTTP client sets it from the URL.
+ */
+export declare function signV4(req: SigV4Request): Record<string, string>;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/infra/email/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../../src/infra/email/sigv4.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAA;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CACpB;AAkBD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwChE"}

package/dist/infra/email/sigv4.js

@@ -0,0 +1,55 @@
+import { createHash, createHmac } from 'node:crypto';
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function hmac(key, data) {
+    return createHmac('sha256', key).update(data).digest();
+}
+function uriEncode(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function amzDate(d) {
+    return d.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}/, '');
+}
+/**
+ * Signs a request with AWS Signature Version 4 and returns the headers to send:
+ * the given ones, `x-amz-date`, `x-amz-security-token` when the credentials carry
+ * a session token, and `authorization`. `host` is signed but not returned; the
+ * HTTP client sets it from the URL.
+ */
+export function signV4(req) {
+    const url = new URL(req.url);
+    const stamp = amzDate(req.now ?? new Date());
+    const day = stamp.slice(0, 8);
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers))
+        headers[name.toLowerCase()] = value.trim().replace(/\s+/g, ' ');
+    headers['x-amz-date'] = stamp;
+    if (req.credentials.sessionToken !== undefined)
+        headers['x-amz-security-token'] = req.credentials.sessionToken;
+    const signed = { ...headers, host: url.host };
+    const names = Object.keys(signed).sort();
+    const canonicalHeaders = names.map(n => `${n}:${signed[n]}\n`).join('');
+    const signedHeaders = names.join(';');
+    const canonicalPath = url.pathname.split('/').map(uriEncode).join('/');
+    const canonicalQuery = [...url.searchParams.entries()]
+        .map(([k, v]) => [uriEncode(k), uriEncode(v)])
+        .sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : (a[0] < b[0] ? -1 : 1)))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const canonicalRequest = [
+        req.method.toUpperCase(), canonicalPath, canonicalQuery, canonicalHeaders, signedHeaders, sha256Hex(req.body),
+    ].join('\n');
+    const scope = `${day}/${req.region}/${req.service}/aws4_request`;
+    const stringToSign = ['AWS4-HMAC-SHA256', stamp, scope, sha256Hex(canonicalRequest)].join('\n');
+    const kDate = hmac(`AWS4${req.credentials.secretAccessKey}`, day);
+    const kRegion = hmac(kDate, req.region);
+    const kService = hmac(kRegion, req.service);
+    const kSigning = hmac(kService, 'aws4_request');
+    const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex');
+    return {
+        ...headers,
+        authorization: `AWS4-HMAC-SHA256 Credential=${req.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+    };
+}
+//# sourceMappingURL=sigv4.js.map

package/dist/infra/email/sigv4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.js","sourceRoot":"","sources":["../../../src/infra/email/sigv4.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.202.0",
+  "version": "0.203.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",