@satorio/machinery 0.2.1

package/dist/identifiers/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public entry to the identifiers mechanism: the id a machine mints, and the
+ * numbers a person reads off a document. It gives you the identifier a machine
+ * mints for a record, and the numbers a person reads off a document, quotes
+ * back over the phone, and types into a bank.
+ */
+export { type ClientCode, clientCodeFrom, clientCodeInGroupedForm, digitsOfClientCode, newClientCode, } from './client-code.js';
+export { type CreditorReference, creditorReferenceFrom, creditorReferenceInGroupedForm, creditorReferenceOf, digitsOfCreditorReference, } from './creditor-reference.js';
+export { dammCheckDigit, dammHolds, withDammCheckDigit } from './damm.js';
+export { clientCodeOfDocumentNumber, type DocumentNumber, type DocumentNumberParts, digitsOfDocumentNumber, reportingMonthOf, } from './document-number.js';
+export { type DocumentNumbers, makeDocumentNumbers, } from './document-numbers.js';
+export { type IdentifierFailure, NotAClientCodeError, NotACreditorReferenceError, NotADocumentNumberError, } from './failures.js';
+export type { NextDocumentNumberInput } from './next-document-number.js';
+export { newUlid, ulidOfSeed, ulidsInOrder } from './ulid.js';

package/dist/identifiers/index.js

@@ -0,0 +1,13 @@
+/**
+ * Public entry to the identifiers mechanism: the id a machine mints, and the
+ * numbers a person reads off a document. It gives you the identifier a machine
+ * mints for a record, and the numbers a person reads off a document, quotes
+ * back over the phone, and types into a bank.
+ */
+export { clientCodeFrom, clientCodeInGroupedForm, digitsOfClientCode, newClientCode, } from './client-code.js';
+export { creditorReferenceFrom, creditorReferenceInGroupedForm, creditorReferenceOf, digitsOfCreditorReference, } from './creditor-reference.js';
+export { dammCheckDigit, dammHolds, withDammCheckDigit } from './damm.js';
+export { clientCodeOfDocumentNumber, digitsOfDocumentNumber, reportingMonthOf, } from './document-number.js';
+export { makeDocumentNumbers, } from './document-numbers.js';
+export { NotAClientCodeError, NotACreditorReferenceError, NotADocumentNumberError, } from './failures.js';
+export { newUlid, ulidOfSeed, ulidsInOrder } from './ulid.js';

package/dist/identifiers/next-document-number.d.ts

@@ -0,0 +1,26 @@
+import { DocumentNumberCounter, DocumentNumberCounterUnavailableError } from '@satorio/machinery/ports';
+import type { CalendarDay } from '@satorio/machinery/time';
+import { Effect } from 'effect';
+import { type ClientCode } from './client-code.js';
+import { type DocumentNumber } from './document-number.js';
+/**
+ * Which document to number: its series, who it goes to, and the month it
+ * reports on.
+ */
+export interface NextDocumentNumberInput<Series extends string = string> {
+    readonly series: Series;
+    readonly clientCode: ClientCode;
+    readonly reportingMonth: CalendarDay;
+}
+/**
+ * The number for the next document a client is sent this month. The
+ * count comes from the counter port, which is the only thing here that
+ * remembers anything: every series shares one count per client and
+ * month, so two documents never carry the same digits. A counter that
+ * answers with something no document can be numbered by is a broken
+ * counter, and it comes back as that port's own refusal rather than as
+ * a number nobody can pay against.
+ *
+ * @internal
+ */
+export declare const nextDocumentNumber: (input: NextDocumentNumberInput) => Effect.Effect<DocumentNumber, DocumentNumberCounterUnavailableError, DocumentNumberCounter>;

package/dist/identifiers/next-document-number.js

@@ -0,0 +1,31 @@
+import { DocumentNumberCounter, DocumentNumberCounterUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Either } from 'effect';
+import { digitsOfClientCode } from './client-code.js';
+import { documentNumberOf, reportingMonthOf, } from './document-number.js';
+/**
+ * The number for the next document a client is sent this month. The
+ * count comes from the counter port, which is the only thing here that
+ * remembers anything: every series shares one count per client and
+ * month, so two documents never carry the same digits. A counter that
+ * answers with something no document can be numbered by is a broken
+ * counter, and it comes back as that port's own refusal rather than as
+ * a number nobody can pay against.
+ *
+ * @internal
+ */
+export const nextDocumentNumber = (input) => Effect.gen(function* () {
+    const counter = yield* DocumentNumberCounter;
+    const count = yield* counter.nextCount({
+        clientCode: digitsOfClientCode(input.clientCode),
+        reportingMonth: reportingMonthOf(input.reportingMonth),
+    });
+    const numbered = documentNumberOf({ ...input, count });
+    if (Either.isLeft(numbered)) {
+        return yield* new DocumentNumberCounterUnavailableError({
+            operation: 'nextCount',
+            cause: `The counter answered with ${count}, and no document can carry ` +
+                'that as its count.',
+        });
+    }
+    return numbered.right;
+});

package/dist/identifiers/ulid.d.ts

@@ -0,0 +1,28 @@
+import { type Ulid } from '@satorio/machinery/core';
+import { type DateTime, Effect } from 'effect';
+/**
+ * A fresh identifier, minted from the clock and the randomness the
+ * service already shares. Nothing here reads a global clock or a global
+ * random source, so a test that pins the moment and seeds the randomness
+ * gets the same identifier every run, and the effect diagnostics that
+ * refuse a global random source stay quiet in the service that calls it.
+ */
+export declare const newUlid: Effect.Effect<Ulid>;
+/**
+ * A maker of identifiers that keep their order even when two of them
+ * land inside one millisecond. Ask for the maker once, then call it for
+ * every identifier of one run: it remembers the last one it handed out
+ * and steps the next one past it, which is what a journal needs when
+ * several lines are written in the same breath. Two makers do not
+ * coordinate, so one run asks for one maker.
+ */
+export declare const ulidsInOrder: Effect.Effect<Effect.Effect<Ulid>>;
+/**
+ * The identifier a moment and a seed always mint the same way. Use it
+ * where nobody outside may name a record and no random source belongs
+ * either: a message off a queue carries the moment the fact happened and
+ * its own identifier, and those two are enough. The same envelope
+ * arriving twice mints one identifier, so a redelivery cannot enter
+ * under a second name, and the identifiers still sort by the moment.
+ */
+export declare const ulidOfSeed: (moment: DateTime.Utc, seed: string) => Ulid;

package/dist/identifiers/ulid.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { ulid } from '@satorio/machinery/core';
+import { Clock, Effect, Random } from 'effect';
+import { monotonicFactory, ulid as ulidText } from 'ulid';
+const RANDOM_SYMBOLS = 16;
+const BYTE_RANGE = 256;
+const drawingFrom = (draws) => {
+    let at = 0;
+    return () => {
+        const draw = draws[at] ?? 0;
+        at += 1;
+        return draw;
+    };
+};
+const refillableDraws = () => {
+    let draws = [];
+    let at = 0;
+    return {
+        prng: () => {
+            const draw = draws[at] ?? 0;
+            at += 1;
+            return draw;
+        },
+        refill: (fresh) => {
+            draws = fresh;
+            at = 0;
+        },
+    };
+};
+/**
+ * A fresh identifier, minted from the clock and the randomness the
+ * service already shares. Nothing here reads a global clock or a global
+ * random source, so a test that pins the moment and seeds the randomness
+ * gets the same identifier every run, and the effect diagnostics that
+ * refuse a global random source stay quiet in the service that calls it.
+ */
+export const newUlid = Effect.gen(function* () {
+    const millis = yield* Clock.currentTimeMillis;
+    const draws = yield* Effect.replicateEffect(Random.next, RANDOM_SYMBOLS);
+    return ulid(ulidText(millis, drawingFrom(draws)));
+});
+/**
+ * A maker of identifiers that keep their order even when two of them
+ * land inside one millisecond. Ask for the maker once, then call it for
+ * every identifier of one run: it remembers the last one it handed out
+ * and steps the next one past it, which is what a journal needs when
+ * several lines are written in the same breath. Two makers do not
+ * coordinate, so one run asks for one maker.
+ */
+export const ulidsInOrder = Effect.sync(() => {
+    const draws = refillableDraws();
+    const nextText = monotonicFactory(draws.prng);
+    return Effect.gen(function* () {
+        const millis = yield* Clock.currentTimeMillis;
+        draws.refill(yield* Effect.replicateEffect(Random.next, RANDOM_SYMBOLS));
+        return ulid(nextText(millis));
+    });
+});
+/**
+ * The identifier a moment and a seed always mint the same way. Use it
+ * where nobody outside may name a record and no random source belongs
+ * either: a message off a queue carries the moment the fact happened and
+ * its own identifier, and those two are enough. The same envelope
+ * arriving twice mints one identifier, so a redelivery cannot enter
+ * under a second name, and the identifiers still sort by the moment.
+ */
+export const ulidOfSeed = (moment, seed) => {
+    const digest = createHash('sha256').update(seed).digest();
+    const draws = [...digest].map((byte) => byte / BYTE_RANGE);
+    return ulid(ulidText(moment.epochMillis, drawingFrom(draws)));
+};

package/dist/integration/external-http-client.d.ts

@@ -0,0 +1,22 @@
+import { HttpClient } from '@effect/platform';
+import { type Refusal } from '@satorio/machinery/core';
+import { type ExternalHttpClientShape } from '@satorio/machinery/ports';
+import { Effect } from 'effect';
+import type { ExternalServiceSettings } from './settings.js';
+/**
+ * A ready-to-use client, with its transport already captured.
+ *
+ * A ready-to-use client: the transport (`HttpClient.HttpClient`) is captured
+ * into context once, so the piece handed to an adapter needs nothing more from
+ * the Effect context.
+ */
+export declare const makeExternalHttpClient: (service: string, settings: ExternalServiceSettings) => Effect.Effect<ExternalHttpClientShape, never, HttpClient.HttpClient>;
+/**
+ * The client that stands in when nobody set the address, and fails every call
+ * loudly.
+ *
+ * The client that stands in when the address is not set: every call fails with
+ * the same three-part refusal the mount desk logged, so nothing goes missing
+ * in silence and no second wording exists to keep in step.
+ */
+export declare const externalHttpClientUnavailableWithoutConfiguration: (service: string, refusal: Refusal) => ExternalHttpClientShape;

package/dist/integration/external-http-client.js

@@ -0,0 +1,74 @@
+import { HttpClient, HttpClientRequest, HttpClientResponse, } from '@effect/platform';
+import { refusalText } from '@satorio/machinery/core';
+import { ExternalServiceRefusedError, ExternalServiceResponseMalformedError, ExternalServiceUnavailableError, } from '@satorio/machinery/ports';
+import { Clock, Duration, Effect, Either, Option } from 'effect';
+import { callFailureOfStatus, retryWhileTransient, transientCallFailure, } from './retry.js';
+const GET_JSON = 'getJson';
+const outcomeOfResponse = (response) => Option.match(callFailureOfStatus(response.status), {
+    onNone: () => Effect.succeed(response),
+    onSome: (failure) => Effect.fail(failure),
+});
+const logCall = (service, operation, path, status, durationMillis) => Effect.logInfo(JSON.stringify({
+    event: 'external-service-call',
+    service,
+    operation,
+    method: 'GET',
+    path,
+    status,
+    durationMillis,
+}));
+const attemptOnce = (service, operation, settings, path) => Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.get(path).pipe(HttpClientRequest.prependUrl(settings.baseUrl));
+    const startedAt = yield* Clock.currentTimeMillis;
+    const outcome = yield* client.execute(request).pipe(Effect.timeoutFail({
+        duration: Duration.millis(settings.timeoutMillis),
+        onTimeout: () => 'timeout',
+    }), Effect.either);
+    const durationMillis = (yield* Clock.currentTimeMillis) - startedAt;
+    return yield* Either.match(outcome, {
+        onLeft: (error) => logCall(service, operation, path, error === 'timeout' ? 'timeout' : 'network-error', durationMillis).pipe(Effect.zipRight(Effect.fail(transientCallFailure(error)))),
+        onRight: (response) => logCall(service, operation, path, response.status, durationMillis).pipe(Effect.zipRight(outcomeOfResponse(response))),
+    });
+});
+const getJsonWith = (service, settings, path, schema) => attemptOnce(service, GET_JSON, settings, path).pipe(Effect.retry(retryWhileTransient), Effect.catchTag('TransientCallFailure', (failure) => new ExternalServiceUnavailableError({
+    service,
+    operation: GET_JSON,
+    cause: failure.cause,
+})), Effect.catchTag('RefusedCallFailure', (failure) => new ExternalServiceRefusedError({
+    service,
+    operation: GET_JSON,
+    status: failure.status,
+})), Effect.flatMap((response) => HttpClientResponse.schemaBodyJson(schema)(response).pipe(Effect.mapError((cause) => new ExternalServiceResponseMalformedError({
+    service,
+    operation: GET_JSON,
+    cause,
+})))));
+/**
+ * A ready-to-use client, with its transport already captured.
+ *
+ * A ready-to-use client: the transport (`HttpClient.HttpClient`) is captured
+ * into context once, so the piece handed to an adapter needs nothing more from
+ * the Effect context.
+ */
+export const makeExternalHttpClient = (service, settings) => Effect.gen(function* () {
+    const context = yield* Effect.context();
+    return {
+        getJson: (path, schema) => getJsonWith(service, settings, path, schema).pipe(Effect.provide(context)),
+    };
+});
+/**
+ * The client that stands in when nobody set the address, and fails every call
+ * loudly.
+ *
+ * The client that stands in when the address is not set: every call fails with
+ * the same three-part refusal the mount desk logged, so nothing goes missing
+ * in silence and no second wording exists to keep in step.
+ */
+export const externalHttpClientUnavailableWithoutConfiguration = (service, refusal) => ({
+    getJson: () => Effect.fail(new ExternalServiceUnavailableError({
+        service,
+        operation: GET_JSON,
+        cause: refusalText(refusal),
+    })),
+});

package/dist/integration/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public entry to the integration mechanism: one HTTP client for reference
+ * data outside this service. It gives you the `ExternalHttpClient` port bound
+ * to real HTTP — a base URL and a timeout read from two prefixed variables,
+ * bounded retry for network failures and 5xx, no retry for 4xx, response
+ * decoding through `Schema`, a log line for every call, and a loud stub in the
+ * client's place when nobody set the address.
+ */
+export { externalHttpClientUnavailableWithoutConfiguration, makeExternalHttpClient, } from './external-http-client.js';
+export { externalHttpClientFromEnvironmentLive, externalHttpClientLive, } from './layer.js';
+export { defaultExternalRetrySchedule } from './retry.js';
+export { baseUrlVariable, DEFAULT_TIMEOUT_MILLIS, ENVIRONMENT, type ExternalServiceSettings, externalServiceSettings, timeoutVariable, } from './settings.js';

package/dist/integration/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public entry to the integration mechanism: one HTTP client for reference
+ * data outside this service. It gives you the `ExternalHttpClient` port bound
+ * to real HTTP — a base URL and a timeout read from two prefixed variables,
+ * bounded retry for network failures and 5xx, no retry for 4xx, response
+ * decoding through `Schema`, a log line for every call, and a loud stub in the
+ * client's place when nobody set the address.
+ */
+export { externalHttpClientUnavailableWithoutConfiguration, makeExternalHttpClient, } from './external-http-client.js';
+export { externalHttpClientFromEnvironmentLive, externalHttpClientLive, } from './layer.js';
+export { defaultExternalRetrySchedule } from './retry.js';
+export { baseUrlVariable, DEFAULT_TIMEOUT_MILLIS, ENVIRONMENT, externalServiceSettings, timeoutVariable, } from './settings.js';

package/dist/integration/layer.d.ts

@@ -0,0 +1,19 @@
+import { type HttpClient } from '@effect/platform';
+import { ExternalHttpClient } from '@satorio/machinery/ports';
+import { type ConfigError, Layer } from 'effect';
+/**
+ * A client built from the environment variables under one prefix. With
+ * no address set it mounts the loud stub and logs the one refusal every
+ * later call repeats, so startup carries on and nothing goes missing in
+ * silence. The transport is a parameter, so a test substitutes its own
+ * without touching the wiring and without a live network.
+ */
+export declare const externalHttpClientFromEnvironmentLive: (service: string, variablePrefix: string, transport?: Layer.Layer<HttpClient.HttpClient>) => Layer.Layer<ExternalHttpClient, ConfigError.ConfigError>;
+/**
+ * One external service on the real fetch transport, reading the
+ * variables its prefix names. Mount one per service:
+ * `externalHttpClientLive('book-catalog', 'BOOK_CATALOG')` and
+ * `externalHttpClientLive('exchange-rates', 'EXCHANGE_RATES')` live side
+ * by side in one process.
+ */
+export declare const externalHttpClientLive: (service: string, variablePrefix: string) => Layer.Layer<ExternalHttpClient, ConfigError.ConfigError>;

package/dist/integration/layer.js

@@ -0,0 +1,30 @@
+import { FetchHttpClient } from '@effect/platform';
+import { refusalText } from '@satorio/machinery/core';
+import { ExternalHttpClient } from '@satorio/machinery/ports';
+import { Effect, Layer, Option } from 'effect';
+import { externalHttpClientUnavailableWithoutConfiguration, makeExternalHttpClient, } from './external-http-client.js';
+import { baseUrlRefusal, configuredBaseUrl, externalServiceSettings, } from './settings.js';
+/**
+ * A client built from the environment variables under one prefix. With
+ * no address set it mounts the loud stub and logs the one refusal every
+ * later call repeats, so startup carries on and nothing goes missing in
+ * silence. The transport is a parameter, so a test substitutes its own
+ * without touching the wiring and without a live network.
+ */
+export const externalHttpClientFromEnvironmentLive = (service, variablePrefix, transport = FetchHttpClient.layer) => Layer.unwrapEffect(Effect.gen(function* () {
+    const configured = yield* configuredBaseUrl(variablePrefix);
+    if (Option.isNone(configured)) {
+        const refusal = baseUrlRefusal(variablePrefix);
+        yield* Effect.logError(refusalText(refusal));
+        return Layer.succeed(ExternalHttpClient, externalHttpClientUnavailableWithoutConfiguration(service, refusal));
+    }
+    return Layer.effect(ExternalHttpClient, Effect.flatMap(externalServiceSettings(variablePrefix), (settings) => makeExternalHttpClient(service, settings))).pipe(Layer.provide(transport));
+}));
+/**
+ * One external service on the real fetch transport, reading the
+ * variables its prefix names. Mount one per service:
+ * `externalHttpClientLive('book-catalog', 'BOOK_CATALOG')` and
+ * `externalHttpClientLive('exchange-rates', 'EXCHANGE_RATES')` live side
+ * by side in one process.
+ */
+export const externalHttpClientLive = (service, variablePrefix) => externalHttpClientFromEnvironmentLive(service, variablePrefix);

package/dist/integration/retry.d.ts

@@ -0,0 +1,65 @@
+import { Option, Schedule } from 'effect';
+/**
+ * How a call waits and tries again: growing pauses, jittered, on a short
+ * budget.
+ *
+ * Exponential growth with jitter and a hard cap on attempts — the same recipe
+ * as the queue consumer's `defaultQueueRetrySchedule`, on a shorter budget: an
+ * external reference call must not hold for minutes.
+ */
+export declare const defaultExternalRetrySchedule: Schedule.Schedule<unknown, unknown>;
+/**
+ * The service did not answer, or answered that it could not: a network
+ * failure, a timeout, or a 5xx. Trying again is worth it.
+ *
+ * @internal
+ */
+export interface TransientCallFailure {
+    readonly _tag: 'TransientCallFailure';
+    readonly cause: unknown;
+}
+/**
+ * The service answered with a specific no — a 4xx. Trying again asks the
+ * same question and gets the same answer, so the client stops at once.
+ *
+ * @internal
+ */
+export interface RefusedCallFailure {
+    readonly _tag: 'RefusedCallFailure';
+    readonly status: number;
+}
+/**
+ * The two ways one attempt can end badly, before the client turns either
+ * of them into the failure a caller reads.
+ *
+ * @internal
+ */
+export type CallFailure = TransientCallFailure | RefusedCallFailure;
+/**
+ * @internal
+ */
+export declare const transientCallFailure: (cause: unknown) => TransientCallFailure;
+/**
+ * @internal
+ */
+export declare const refusedCallFailure: (status: number) => RefusedCallFailure;
+/**
+ * Reads one response status as the kind of failure it is, or
+ * `Option.none` when the service answered. A 5xx is transient because
+ * the service is having a bad moment; a 4xx is a refusal because it
+ * answered the question and the answer was no.
+ *
+ * @internal
+ */
+export declare const callFailureOfStatus: (status: number) => Option.Option<CallFailure>;
+/**
+ * @internal
+ */
+export declare const isTransientCallFailure: (failure: CallFailure) => failure is TransientCallFailure;
+/**
+ * Retries while the attempt failed transiently, on the schedule above,
+ * and stops the moment the service gives a specific no.
+ *
+ * @internal
+ */
+export declare const retryWhileTransient: Schedule.Schedule<readonly [CallFailure, unknown], CallFailure>;

package/dist/integration/retry.js

@@ -0,0 +1,54 @@
+import { Duration, Option, Schedule } from 'effect';
+const LOWEST_SERVER_FAILURE_STATUS = 500;
+const LOWEST_REFUSAL_STATUS = 400;
+/**
+ * How a call waits and tries again: growing pauses, jittered, on a short
+ * budget.
+ *
+ * Exponential growth with jitter and a hard cap on attempts — the same recipe
+ * as the queue consumer's `defaultQueueRetrySchedule`, on a shorter budget: an
+ * external reference call must not hold for minutes.
+ */
+export const defaultExternalRetrySchedule = Schedule.exponential(Duration.millis(100), 2).pipe(Schedule.union(Schedule.spaced(Duration.seconds(2))), Schedule.jittered, Schedule.intersect(Schedule.recurs(4)));
+/**
+ * @internal
+ */
+export const transientCallFailure = (cause) => ({
+    _tag: 'TransientCallFailure',
+    cause,
+});
+/**
+ * @internal
+ */
+export const refusedCallFailure = (status) => ({
+    _tag: 'RefusedCallFailure',
+    status,
+});
+/**
+ * Reads one response status as the kind of failure it is, or
+ * `Option.none` when the service answered. A 5xx is transient because
+ * the service is having a bad moment; a 4xx is a refusal because it
+ * answered the question and the answer was no.
+ *
+ * @internal
+ */
+export const callFailureOfStatus = (status) => {
+    if (status >= LOWEST_SERVER_FAILURE_STATUS) {
+        return Option.some(transientCallFailure(status));
+    }
+    if (status >= LOWEST_REFUSAL_STATUS) {
+        return Option.some(refusedCallFailure(status));
+    }
+    return Option.none();
+};
+/**
+ * @internal
+ */
+export const isTransientCallFailure = (failure) => failure._tag === 'TransientCallFailure';
+/**
+ * Retries while the attempt failed transiently, on the schedule above,
+ * and stops the moment the service gives a specific no.
+ *
+ * @internal
+ */
+export const retryWhileTransient = Schedule.recurWhile(isTransientCallFailure).pipe(Schedule.intersect(defaultExternalRetrySchedule));

package/dist/integration/settings.d.ts

@@ -0,0 +1,73 @@
+import { type EnvironmentEntry, type Refusal } from '@satorio/machinery/core';
+import { Config, type Option } from 'effect';
+/**
+ * The longest one external call may take: ten minutes. A number above it
+ * is a timeout nobody is waiting on any more, so the client refuses it
+ * rather than holding a request open past every deadline around it.
+ *
+ * @internal
+ */
+export declare const LONGEST_TIMEOUT_MILLIS = 600000;
+/**
+ * How long one call may take when nobody names a number. Three seconds
+ * is long enough for a reference service on a good day and short enough
+ * that a bad one does not hold a use case open.
+ */
+export declare const DEFAULT_TIMEOUT_MILLIS = 3000;
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One process calls any number of external services
+ * this way, with readable names: `BOOK_CATALOG_BASE_URL`,
+ * `EXCHANGE_RATES_BASE_URL`, and so on.
+ */
+export declare const baseUrlVariable: (variablePrefix: string) => string;
+/**
+ * Builds the timeout variable's name from the same prefix, so each
+ * external service in one process keeps its own patience.
+ */
+export declare const timeoutVariable: (variablePrefix: string) => string;
+/**
+ * What a client needs before it can call: the address every request goes
+ * under, and how long one call may take.
+ */
+export interface ExternalServiceSettings {
+    readonly baseUrl: string;
+    readonly timeoutMillis: number;
+}
+/**
+ * The three parts a reader meets when the address is not set. The mount
+ * desk logs this text and every call to the loud stub fails with it, so
+ * an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export declare const baseUrlRefusal: (variablePrefix: string) => Refusal;
+/**
+ * The three parts a reader meets when the timeout is set to something
+ * the client cannot wait on. A timeout left unset takes the default and
+ * refuses nothing.
+ *
+ * @internal
+ */
+export declare const timeoutRefusal: (variablePrefix: string) => Refusal;
+/**
+ * Reads the address without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export declare const configuredBaseUrl: (variablePrefix: string) => Config.Config<Option.Option<string>>;
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time, so a second external service in the same process reads a second
+ * pair of names.
+ */
+export declare const ENVIRONMENT: readonly EnvironmentEntry[];
+/**
+ * Reads every variable of `ENVIRONMENT` under one prefix. A missing or
+ * blank address refuses in three parts; a timeout left alone takes the
+ * default, and one set outside the range refuses in three parts of its
+ * own.
+ */
+export declare const externalServiceSettings: (variablePrefix: string) => Config.Config<ExternalServiceSettings>;

package/dist/integration/settings.js

@@ -0,0 +1,92 @@
+import { fallsBackTo, optionalText, refuses, requiredText, wholeNumberFallingBackTo, } from '@satorio/machinery/core';
+import { Config } from 'effect';
+const BASE_URL_SUFFIX = '_BASE_URL';
+const TIMEOUT_SUFFIX = '_TIMEOUT_MILLIS';
+const SHORTEST_TIMEOUT_MILLIS = 1;
+/**
+ * The longest one external call may take: ten minutes. A number above it
+ * is a timeout nobody is waiting on any more, so the client refuses it
+ * rather than holding a request open past every deadline around it.
+ *
+ * @internal
+ */
+export const LONGEST_TIMEOUT_MILLIS = 600_000;
+/**
+ * How long one call may take when nobody names a number. Three seconds
+ * is long enough for a reference service on a good day and short enough
+ * that a bad one does not hold a use case open.
+ */
+export const DEFAULT_TIMEOUT_MILLIS = 3_000;
+/**
+ * Builds the environment variable name from the prefix the application
+ * gives at mount time. One process calls any number of external services
+ * this way, with readable names: `BOOK_CATALOG_BASE_URL`,
+ * `EXCHANGE_RATES_BASE_URL`, and so on.
+ */
+export const baseUrlVariable = (variablePrefix) => `${variablePrefix}${BASE_URL_SUFFIX}`;
+/**
+ * Builds the timeout variable's name from the same prefix, so each
+ * external service in one process keeps its own patience.
+ */
+export const timeoutVariable = (variablePrefix) => `${variablePrefix}${TIMEOUT_SUFFIX}`;
+/**
+ * The three parts a reader meets when the address is not set. The mount
+ * desk logs this text and every call to the loud stub fails with it, so
+ * an operator reads one sentence rather than two.
+ *
+ * @internal
+ */
+export const baseUrlRefusal = (variablePrefix) => ({
+    what: `${baseUrlVariable(variablePrefix)} is not set, so this external service has no address.`,
+    why: 'One process calls several external services, each under its own prefix, so the client cannot guess which address you meant.',
+    whatToDo: `Set ${baseUrlVariable(variablePrefix)} to the service's own base URL, such as https://openlibrary.org, then start the service again.`,
+});
+/**
+ * The three parts a reader meets when the timeout is set to something
+ * the client cannot wait on. A timeout left unset takes the default and
+ * refuses nothing.
+ *
+ * @internal
+ */
+export const timeoutRefusal = (variablePrefix) => ({
+    what: `${timeoutVariable(variablePrefix)} is set to something this client cannot wait on.`,
+    why: `It says how many milliseconds one call may take, so it has to be a whole number from ${SHORTEST_TIMEOUT_MILLIS} to ${LONGEST_TIMEOUT_MILLIS}.`,
+    whatToDo: `Set ${timeoutVariable(variablePrefix)} to a whole number of milliseconds in that range, or leave it unset and take the ${DEFAULT_TIMEOUT_MILLIS} millisecond default.`,
+});
+/**
+ * Reads the address without refusing, so the mount desk can put up the
+ * loud stub instead of failing service startup.
+ *
+ * @internal
+ */
+export const configuredBaseUrl = (variablePrefix) => optionalText(baseUrlVariable(variablePrefix));
+/**
+ * Every variable this adapter reads, and the one state each of them
+ * stands in. `<PREFIX>` is the prefix the application passes at mount
+ * time, so a second external service in the same process reads a second
+ * pair of names.
+ */
+export const ENVIRONMENT = [
+    {
+        name: BASE_URL_SUFFIX,
+        prefixed: true,
+        what: 'The address every call to this external service goes under.',
+        state: refuses(baseUrlRefusal('<PREFIX>')),
+    },
+    {
+        name: TIMEOUT_SUFFIX,
+        prefixed: true,
+        what: 'How many milliseconds one call may take before it counts as a network failure.',
+        state: fallsBackTo(String(DEFAULT_TIMEOUT_MILLIS)),
+    },
+];
+/**
+ * Reads every variable of `ENVIRONMENT` under one prefix. A missing or
+ * blank address refuses in three parts; a timeout left alone takes the
+ * default, and one set outside the range refuses in three parts of its
+ * own.
+ */
+export const externalServiceSettings = (variablePrefix) => Config.all({
+    baseUrl: requiredText(baseUrlVariable(variablePrefix), baseUrlRefusal(variablePrefix)),
+    timeoutMillis: wholeNumberFallingBackTo(timeoutVariable(variablePrefix), SHORTEST_TIMEOUT_MILLIS, LONGEST_TIMEOUT_MILLIS, DEFAULT_TIMEOUT_MILLIS, timeoutRefusal(variablePrefix)),
+});