@satorio/machinery 0.2.1

package/dist/testing/queue-message-source.js

@@ -0,0 +1,71 @@
+import { QueueMessageSource, QueueMessageSourceUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+const NOT_MOUNTED = 'queue unavailable (test)';
+/**
+ * One raw message, built the way a queue hands it over: an id, the
+ * receipt an acknowledgement quotes, and the body.
+ */
+export const messageOf = (messageId, body) => ({
+    messageId,
+    receiptHandle: `receipt-${messageId}`,
+    body,
+});
+/**
+ * An in-memory message source over a `Ref` you keep, so a test seeds the
+ * queue before the run and reads what is left after it. `receive` hands
+ * back everything waiting; `acknowledge` takes one message off for good,
+ * as a real queue does when the receipt is deleted.
+ */
+export const makeInMemoryQueueMessageSourceWith = (pending) => ({
+    receive: Ref.get(pending),
+    acknowledge: (receiptHandle) => Ref.update(pending, (current) => current.filter((message) => message.receiptHandle !== receiptHandle)),
+});
+/**
+ * An in-memory message source over a `Ref` of its own, empty at the
+ * start.
+ */
+export const makeInMemoryQueueMessageSource = Effect.gen(function* () {
+    const pending = yield* Ref.make([]);
+    return makeInMemoryQueueMessageSourceWith(pending);
+});
+/**
+ * The in-memory message source, mounted.
+ */
+export const InMemoryQueueMessageSourceLive = Layer.effect(QueueMessageSource, makeInMemoryQueueMessageSource);
+/**
+ * A message source that answers nothing: every operation fails with
+ * `QueueMessageSourceUnavailableError`. Mount it to walk the branch a
+ * working stand-in never reaches.
+ */
+export const QueueMessageSourceUnavailableLive = Layer.succeed(QueueMessageSource, {
+    receive: Effect.fail(new QueueMessageSourceUnavailableError({
+        operation: 'receive',
+        cause: NOT_MOUNTED,
+    })),
+    acknowledge: () => Effect.fail(new QueueMessageSourceUnavailableError({
+        operation: 'acknowledge',
+        cause: NOT_MOUNTED,
+    })),
+});
+/**
+ * Builds the scripted source and the reader for what it acknowledged.
+ */
+export const makeScriptedMessageSource = (script) => Effect.gen(function* () {
+    const remaining = yield* Ref.make(script);
+    const acknowledged = yield* Ref.make([]);
+    const source = {
+        receive: Ref.modify(remaining, (current) => {
+            const [head, ...tail] = current;
+            return head === undefined
+                ? [Effect.never, current]
+                : [Effect.succeed(head), tail];
+        }).pipe(Effect.flatten),
+        acknowledge: (receiptHandle) => Ref.update(acknowledged, (current) => [...current, receiptHandle]),
+    };
+    return { source, acknowledged: Ref.get(acknowledged) };
+});
+/**
+ * The scripted source, mounted: each `receive` answers with the next
+ * batch of the script.
+ */
+export const scriptedQueueMessageSourceLive = (script) => Layer.effect(QueueMessageSource, Effect.map(makeScriptedMessageSource(script), (queue) => queue.source));

package/dist/testing/quiet-reporter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The one test case a summary reads: its full name, and the result the
+ * runner recorded for it. Declared here rather than imported from the
+ * runner, because this file is read while a test-runner configuration is
+ * built and the runner's own runtime does not exist yet.
+ *
+ * @internal
+ */
+export interface ReportedTestCase {
+    readonly fullName: string;
+    readonly result: () => {
+        readonly state: string;
+        readonly errors?: readonly {
+            readonly message?: string;
+        }[];
+    };
+}
+/**
+ * The one test module a summary reads: the file it came from and the
+ * test cases inside it.
+ *
+ * @internal
+ */
+export interface ReportedTestModule {
+    readonly moduleId: string;
+    readonly children: {
+        readonly allTests: () => Iterable<ReportedTestCase>;
+    };
+}
+/**
+ * How the quiet reporter names itself and where it writes. `label` opens
+ * the summary line, so a run of several packages says which one spoke.
+ *
+ * @internal
+ */
+export interface QuietReporterOptions {
+    readonly label?: string;
+    readonly write?: (line: string) => void;
+}
+/**
+ * A test-runner reporter that prints one summary line for a whole run:
+ * how many files, how many tests, how long it took. A run where nothing
+ * failed says nothing else. A run with a failure prints each failed test
+ * by its full name with the message the runner recorded, so the reason
+ * is in the same output as the count.
+ *
+ * It forwards whatever a suite printed on purpose. A guard that prints
+ * the number of files it read is a floor somebody watches move, and a
+ * reporter that swallows it hides the one line that matters. What it
+ * drops is the per-test tick list, which is the part that grows with the
+ * suite and says nothing a green summary does not.
+ */
+export declare class QuietReporter {
+    private readonly label;
+    private readonly write;
+    private startedAt;
+    private root;
+    constructor(options?: QuietReporterOptions);
+    onInit(context: {
+        readonly config?: {
+            readonly root?: string;
+        };
+    }): void;
+    onTestRunStart(): void;
+    onUserConsoleLog(log: {
+        readonly content: string;
+    }): void;
+    onTestRunEnd(testModules: readonly ReportedTestModule[], unhandledErrors?: readonly {
+        readonly message?: string;
+    }[]): void;
+}
+/**
+ * Whether the runner should print everything. A run asks for it with
+ * `VITEST_VERBOSE=1`; unset, empty, `0`, `false` and `no` all mean no.
+ */
+export declare const verboseOutputWanted: (environment?: Readonly<Record<string, string | undefined>>) => boolean;
+/**
+ * The `reporters` a test-runner configuration takes. By default it is
+ * the quiet reporter, so a run says how many files and tests passed and
+ * nothing else; `VITEST_VERBOSE=1` hands the run back to the runner's
+ * own reporter, whole. The array is mutable on purpose: the runner's
+ * own configuration type takes no readonly array.
+ */
+export declare const quietReporters: (options?: QuietReporterOptions & {
+    readonly verbose?: boolean;
+}) => ("default" | QuietReporter)[];

package/dist/testing/quiet-reporter.js

@@ -0,0 +1,81 @@
+const DEFAULT_LABEL = 'tests';
+const secondsOf = (millis) => `${(millis / 1000).toFixed(1)}s`;
+const relativeTo = (root, moduleId) => moduleId.startsWith(root) ? moduleId.slice(root.length + 1) : moduleId;
+/**
+ * A test-runner reporter that prints one summary line for a whole run:
+ * how many files, how many tests, how long it took. A run where nothing
+ * failed says nothing else. A run with a failure prints each failed test
+ * by its full name with the message the runner recorded, so the reason
+ * is in the same output as the count.
+ *
+ * It forwards whatever a suite printed on purpose. A guard that prints
+ * the number of files it read is a floor somebody watches move, and a
+ * reporter that swallows it hides the one line that matters. What it
+ * drops is the per-test tick list, which is the part that grows with the
+ * suite and says nothing a green summary does not.
+ */
+// @effect-diagnostics effect/globalDate:off
+export class QuietReporter {
+    label;
+    write;
+    startedAt = Date.now();
+    root = '';
+    constructor(options = {}) {
+        this.label = options.label ?? DEFAULT_LABEL;
+        this.write = options.write ?? ((line) => process.stdout.write(`${line}\n`));
+    }
+    onInit(context) {
+        this.root = context.config?.root ?? '';
+    }
+    onTestRunStart() {
+        this.startedAt = Date.now();
+    }
+    onUserConsoleLog(log) {
+        this.write(log.content.replace(/\n$/, ''));
+    }
+    onTestRunEnd(testModules, unhandledErrors = []) {
+        const failed = [];
+        let tests = 0;
+        let failures = 0;
+        for (const testModule of testModules) {
+            for (const testCase of testModule.children.allTests()) {
+                tests++;
+                const result = testCase.result();
+                if (result.state !== 'failed')
+                    continue;
+                failures++;
+                failed.push(`${relativeTo(this.root, testModule.moduleId)} > ${testCase.fullName}`);
+                for (const error of result.errors ?? []) {
+                    failed.push(`    ${error.message ?? 'no message'}`);
+                }
+            }
+        }
+        const outcome = failures === 0 && unhandledErrors.length === 0
+            ? 'green'
+            : `${failures} failed`;
+        this.write(`${this.label}: ${testModules.length} files, ${tests} tests, ` +
+            `${secondsOf(Date.now() - this.startedAt)} — ${outcome}`);
+        for (const line of failed)
+            this.write(line);
+        for (const error of unhandledErrors) {
+            this.write(`  unhandled: ${error.message ?? 'no message'}`);
+        }
+    }
+}
+// @effect-diagnostics effect/globalDate:error
+const OFF = new Set(['', '0', 'false', 'no']);
+/**
+ * Whether the runner should print everything. A run asks for it with
+ * `VITEST_VERBOSE=1`; unset, empty, `0`, `false` and `no` all mean no.
+ */
+export const verboseOutputWanted = (environment = process.env) => !OFF.has((environment.VITEST_VERBOSE ?? '').toLowerCase());
+/**
+ * The `reporters` a test-runner configuration takes. By default it is
+ * the quiet reporter, so a run says how many files and tests passed and
+ * nothing else; `VITEST_VERBOSE=1` hands the run back to the runner's
+ * own reporter, whole. The array is mutable on purpose: the runner's
+ * own configuration type takes no readonly array.
+ */
+export const quietReporters = (options = {}) => (options.verbose ?? verboseOutputWanted())
+    ? ['default']
+    : [new QuietReporter(options)];

package/dist/testing/readiness-probe.d.ts

@@ -0,0 +1,27 @@
+import { ReadinessProbe, type ReadinessProbeShape } from '@satorio/machinery/ports';
+import { Layer } from 'effect';
+/**
+ * The reason an unavailable probe reports, so a test asserts on a
+ * sentence rather than on the shape of a failure alone.
+ *
+ * @internal
+ */
+export declare const READINESS_REASON_IN_A_TEST = "database did not answer (test)";
+/**
+ * A probe that always says the database answered. It is the only thing
+ * an in-memory probe can honestly say: there is no database behind it to
+ * fall silent.
+ *
+ * @internal
+ */
+export declare const makeInMemoryReadinessProbe: ReadinessProbeShape;
+/**
+ * The in-memory probe, mounted.
+ */
+export declare const InMemoryReadinessProbeLive: Layer.Layer<ReadinessProbe>;
+/**
+ * A probe whose database never answers. Mount it to walk the branch a
+ * working stand-in never reaches — the one a readiness endpoint turns
+ * into "not ready".
+ */
+export declare const ReadinessProbeUnavailableLive: Layer.Layer<ReadinessProbe>;

package/dist/testing/readiness-probe.js

@@ -0,0 +1,33 @@
+import { DatabaseDidNotAnswerError, ReadinessProbe, } from '@satorio/machinery/ports';
+import { Effect, Layer } from 'effect';
+/**
+ * The reason an unavailable probe reports, so a test asserts on a
+ * sentence rather than on the shape of a failure alone.
+ *
+ * @internal
+ */
+export const READINESS_REASON_IN_A_TEST = 'database did not answer (test)';
+/**
+ * A probe that always says the database answered. It is the only thing
+ * an in-memory probe can honestly say: there is no database behind it to
+ * fall silent.
+ *
+ * @internal
+ */
+export const makeInMemoryReadinessProbe = {
+    verifyDatabaseAnswers: Effect.void,
+};
+/**
+ * The in-memory probe, mounted.
+ */
+export const InMemoryReadinessProbeLive = Layer.succeed(ReadinessProbe, makeInMemoryReadinessProbe);
+/**
+ * A probe whose database never answers. Mount it to walk the branch a
+ * working stand-in never reaches — the one a readiness endpoint turns
+ * into "not ready".
+ */
+export const ReadinessProbeUnavailableLive = Layer.succeed(ReadinessProbe, {
+    verifyDatabaseAnswers: new DatabaseDidNotAnswerError({
+        reason: READINESS_REASON_IN_A_TEST,
+    }),
+});

package/dist/testing/scenario.d.ts

@@ -0,0 +1,94 @@
+import { Cause, Effect } from 'effect';
+/**
+ * One step in a scenario. `at` is the step's technical moment — it becomes
+ * a stored row's `processed_at`, `recorded_at`, or `occurred_at`. The
+ * business date, such as a movement's day or a loan's day, lives in
+ * `command` instead.
+ */
+export interface ScenarioStep<Command> {
+    readonly at: string;
+    readonly what: string;
+    readonly command: Command;
+    readonly firstPass: string;
+    readonly onReplay: string;
+}
+/**
+ * A story told as data: the steps a world walks through, and the numbers
+ * that world ends on. `context` carries what every step of that scenario
+ * shares and no step states — the currency of an account, the account
+ * itself, the tenant. A snapshot then reads those from the scenario
+ * rather than deriving them from whatever the first row happened to
+ * hold. A scenario that shares nothing leaves it out.
+ */
+export interface Scenario<Command, Snapshot, Context = never> {
+    readonly name: string;
+    readonly story: string;
+    readonly steps: readonly ScenarioStep<Command>[];
+    readonly expectedSnapshot: Snapshot;
+    readonly context?: Context;
+}
+/**
+ * Reads the cross-cutting data of a scenario that declares some. A
+ * scenario whose type promises it and whose data leaves it out dies
+ * here, naming itself, rather than handing `undefined` on to a snapshot
+ * that then reports a wrong number.
+ */
+export declare const contextOf: <Command, Snapshot, Context>(scenario: Scenario<Command, Snapshot, Context>) => Context;
+/**
+ * What a service gives the scenario player: how to run a step, and how to
+ * snapshot what followed.
+ *
+ * What a service gives the player: how to run a command and name its result,
+ * and how to take a snapshot of the numbers after the run. The failure channel
+ * is deliberately wide — a label only NAMES a failure, it never parses it.
+ */
+export interface ScenarioService<Command, Snapshot, R, Context = never> {
+    readonly perform: (command: Command) => Effect.Effect<string, unknown, R>;
+    readonly snapshot: (scenario: Scenario<Command, Snapshot, Context>) => Effect.Effect<Snapshot, never, R>;
+}
+/**
+ * What one run of a scenario leaves behind: the label of every step, and the
+ * snapshot the run ended on.
+ */
+export interface ScenarioPlayback<Snapshot> {
+    readonly labels: readonly string[];
+    readonly snapshot: Snapshot;
+}
+/**
+ * The labels a scenario expects the first time it runs, in order.
+ */
+export declare const firstPassLabelsOf: <C, S, X>(scenario: Scenario<C, S, X>) => readonly string[];
+/**
+ * The labels a scenario expects when the same steps run a second time, in
+ * order.
+ */
+export declare const replayLabelsOf: <C, S, X>(scenario: Scenario<C, S, X>) => readonly string[];
+/**
+ * Labels a failure, so a scenario reads the same on every run.
+ *
+ * Labels a failure: a domain failure by its named reason, a storage conflict
+ * by its tag, a defect on its own so it stands out from both.
+ */
+export declare const labelOfFailure: (cause: Cause.Cause<unknown>) => string;
+/**
+ * Runs one step and labels it: what it returned, or the name of the failure it
+ * met.
+ */
+export declare const labelOf: <R>(program: Effect.Effect<string, unknown, R>) => Effect.Effect<string, never, R>;
+/**
+ * Fails loudly when a scenario's steps are not in strictly increasing
+ * time order — that is a broken scenario, not a run outcome.
+ */
+export declare const ensureStepsAreInOrder: <C, S, X>(scenario: Scenario<C, S, X>) => Effect.Effect<void>;
+/**
+ * Plays a scenario: each step runs at its own moment, and the
+ * snapshot is taken at the last step's moment. Replaying the same
+ * scenario against the same world should produce `onReplay` labels
+ * and leave the snapshot unchanged — that is how claim-once holds.
+ */
+export declare const playScenario: <C, S, R, X>(scenario: Scenario<C, S, X>, service: ScenarioService<C, S, R, X>) => Effect.Effect<ScenarioPlayback<S>, never, R>;
+/**
+ * Returns the moments of the chosen steps as ISO strings, in the
+ * format a database round-trip returns them.
+ */
+export declare const momentsOfSteps: <C, S, X>(scenario: Scenario<C, S, X>, chosen: (step: ScenarioStep<C>) => boolean) => readonly string[];

package/dist/testing/scenario.js

@@ -0,0 +1,81 @@
+import { Cause, DateTime, Effect, Exit } from 'effect';
+import { atTheMoment } from './clock.js';
+/**
+ * Reads the cross-cutting data of a scenario that declares some. A
+ * scenario whose type promises it and whose data leaves it out dies
+ * here, naming itself, rather than handing `undefined` on to a snapshot
+ * that then reports a wrong number.
+ */
+export const contextOf = (scenario) => {
+    if (scenario.context === undefined) {
+        throw new Error(`Scenario "${scenario.name}" declares cross-cutting data and ` +
+            `carries none: give it a context, or drop the type it promises.`);
+    }
+    return scenario.context;
+};
+/**
+ * The labels a scenario expects the first time it runs, in order.
+ */
+export const firstPassLabelsOf = (scenario) => scenario.steps.map((step) => step.firstPass);
+/**
+ * The labels a scenario expects when the same steps run a second time, in
+ * order.
+ */
+export const replayLabelsOf = (scenario) => scenario.steps.map((step) => step.onReplay);
+/**
+ * Labels a failure, so a scenario reads the same on every run.
+ *
+ * Labels a failure: a domain failure by its named reason, a storage conflict
+ * by its tag, a defect on its own so it stands out from both.
+ */
+export const labelOfFailure = (cause) => {
+    const failure = Cause.failureOption(cause);
+    if (failure._tag === 'None')
+        return `DEFECT: ${Cause.pretty(cause)}`;
+    const tagged = failure.value;
+    return tagged.reason ?? tagged._tag ?? String(failure.value);
+};
+/**
+ * Runs one step and labels it: what it returned, or the name of the failure it
+ * met.
+ */
+export const labelOf = (program) => Effect.exit(program).pipe(Effect.map((exit) => Exit.isSuccess(exit) ? exit.value : labelOfFailure(exit.cause)));
+const millisOf = (isoTimestamp) => DateTime.toEpochMillis(DateTime.unsafeMake(isoTimestamp));
+/**
+ * Fails loudly when a scenario's steps are not in strictly increasing
+ * time order — that is a broken scenario, not a run outcome.
+ */
+export const ensureStepsAreInOrder = (scenario) => Effect.forEach(scenario.steps, (step, index) => {
+    const previous = scenario.steps[index - 1];
+    return previous !== undefined &&
+        millisOf(step.at) <= millisOf(previous.at)
+        ? Effect.die(new Error(`Scenario "${scenario.name}": step ${index + 1} ` +
+            `(${step.at}) is not later than step ${index} ` +
+            `(${previous.at})`))
+        : Effect.void;
+}, { discard: true });
+const lastMomentOf = (scenario) => {
+    const last = scenario.steps.at(-1);
+    return last === undefined
+        ? DateTime.formatIso(DateTime.unsafeMake(0))
+        : last.at;
+};
+/**
+ * Plays a scenario: each step runs at its own moment, and the
+ * snapshot is taken at the last step's moment. Replaying the same
+ * scenario against the same world should produce `onReplay` labels
+ * and leave the snapshot unchanged — that is how claim-once holds.
+ */
+export const playScenario = (scenario, service) => Effect.gen(function* () {
+    yield* ensureStepsAreInOrder(scenario);
+    const labels = yield* Effect.forEach(scenario.steps, (step) => atTheMoment(step.at)(labelOf(service.perform(step.command))));
+    const snapshot = yield* atTheMoment(lastMomentOf(scenario))(service.snapshot(scenario));
+    return { labels, snapshot };
+});
+/**
+ * Returns the moments of the chosen steps as ISO strings, in the
+ * format a database round-trip returns them.
+ */
+export const momentsOfSteps = (scenario, chosen) => scenario.steps
+    .filter(chosen)
+    .map((step) => DateTime.formatIso(DateTime.unsafeMake(step.at)));

package/dist/testing/transaction-boundary.d.ts

@@ -0,0 +1,30 @@
+import { TransactionBoundary, type TransactionBoundaryShape } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+/**
+ * One participant in an in-memory transaction: it can capture its own
+ * state now and hand back the effect that puts it back.
+ */
+export interface TransactionalState {
+    readonly capture: Effect.Effect<Effect.Effect<void>>;
+}
+/**
+ * Makes a `Ref` a participant, so an in-memory boundary can put it back
+ * where it was when the work fails.
+ */
+export declare const stateOfRef: <A>(ref: Ref.Ref<A>) => TransactionalState;
+/**
+ * Builds an in-memory transaction boundary: it captures each
+ * participant's state on entry and restores it if the work fails.
+ */
+export declare const makeInMemoryTransactionBoundary: (participants: readonly TransactionalState[]) => TransactionBoundaryShape;
+/**
+ * The in-memory transaction boundary, mounted over the participants you
+ * name.
+ */
+export declare const inMemoryTransactionBoundaryLive: (participants: readonly TransactionalState[]) => Layer.Layer<TransactionBoundary>;
+/**
+ * A transaction boundary that opens nothing: the work never runs and the
+ * caller reads the refusal. Mount it to walk the branch a working
+ * stand-in never reaches.
+ */
+export declare const TransactionBoundaryUnavailableLive: Layer.Layer<TransactionBoundary>;

package/dist/testing/transaction-boundary.js

@@ -0,0 +1,36 @@
+import { TransactionBoundary, TransactionBoundaryUnavailableError, } from '@satorio/machinery/ports';
+import { Effect, Layer, Ref } from 'effect';
+const NOT_MOUNTED = 'transaction boundary unavailable (test)';
+/**
+ * Makes a `Ref` a participant, so an in-memory boundary can put it back
+ * where it was when the work fails.
+ */
+export const stateOfRef = (ref) => ({
+    capture: Ref.get(ref).pipe(Effect.map((valueAtEntry) => Ref.set(ref, valueAtEntry))),
+});
+/**
+ * Builds an in-memory transaction boundary: it captures each
+ * participant's state on entry and restores it if the work fails.
+ */
+export const makeInMemoryTransactionBoundary = (participants) => ({
+    inTransaction: (work) => Effect.gen(function* () {
+        const restores = yield* Effect.forEach(participants, (state) => state.capture);
+        return yield* work.pipe(Effect.tapError(() => Effect.forEach(restores, (restore) => restore, { discard: true })));
+    }),
+});
+/**
+ * The in-memory transaction boundary, mounted over the participants you
+ * name.
+ */
+export const inMemoryTransactionBoundaryLive = (participants) => Layer.succeed(TransactionBoundary, makeInMemoryTransactionBoundary(participants));
+/**
+ * A transaction boundary that opens nothing: the work never runs and the
+ * caller reads the refusal. Mount it to walk the branch a working
+ * stand-in never reaches.
+ */
+export const TransactionBoundaryUnavailableLive = Layer.succeed(TransactionBoundary, {
+    inTransaction: () => new TransactionBoundaryUnavailableError({
+        operation: 'inTransaction',
+        cause: NOT_MOUNTED,
+    }),
+});

package/dist/testing/typed-failure.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from 'effect';
+/**
+ * Extracts a use case's typed failure (Fail) through `Effect.exit`
+ * and `Cause`, rather than by matching an error message string.
+ * Fails loudly if the effect succeeded, or if it died or was
+ * interrupted instead of producing a typed Fail.
+ */
+export declare const typedFailureOf: <A, E>(effect: Effect.Effect<A, E>) => Effect.Effect<E>;

package/dist/testing/typed-failure.js

@@ -0,0 +1,15 @@
+import { Cause, Effect, Exit, Option } from 'effect';
+/**
+ * Extracts a use case's typed failure (Fail) through `Effect.exit`
+ * and `Cause`, rather than by matching an error message string.
+ * Fails loudly if the effect succeeded, or if it died or was
+ * interrupted instead of producing a typed Fail.
+ */
+export const typedFailureOf = (effect) => Effect.exit(effect).pipe(Effect.flatMap((exit) => Exit.isSuccess(exit)
+    ? Effect.die(new Error(`expected a typed failure — the use case succeeded ` +
+        `instead: ${JSON.stringify(exit.value)}`))
+    : Cause.failureOption(exit.cause).pipe(Option.match({
+        onNone: () => Effect.die(new Error(`expected a typed failure (Fail) — the Cause ` +
+            `is not a Fail: ${Cause.pretty(exit.cause)}`)),
+        onSome: Effect.succeed,
+    }))));

package/dist/time/calendar-day.d.ts

@@ -0,0 +1,83 @@
+import { Either, Order, Schema } from 'effect';
+import { NotACalendarDayError } from './failures.js';
+declare const calendarDayBrand: unique symbol;
+/**
+ * One day of the calendar, with no time and no zone in it. The value
+ * carries a brand, so a plain string never passes for a day until it has
+ * been read by one of the two readers below.
+ */
+export type CalendarDay = string & {
+    readonly [calendarDayBrand]: 'CalendarDay';
+};
+/**
+ * The day named by parts a real moment already produced. This is the one
+ * place a calendar day is built, so a value of that type never comes
+ * from anywhere else.
+ *
+ * @internal
+ */
+export declare const dayOfDateParts: (year: number, month: number, day: number) => CalendarDay;
+/**
+ * Reads the form a person writes a day in: `19.03.2026`. A text of any
+ * other shape, a month outside the twelve, or a day the month does not
+ * have all come back as a refusal that names which rule was broken.
+ */
+export declare const calendarDayFromHumanForm: (text: string) => Either.Either<CalendarDay, NotACalendarDayError>;
+/**
+ * Reads the form a machine writes a day in: `2026-03-19`. It refuses
+ * exactly what the human reader refuses, for exactly the same reasons.
+ */
+export declare const calendarDayFromIsoForm: (text: string) => Either.Either<CalendarDay, NotACalendarDayError>;
+/**
+ * Writes a day the way a person reads it: `19.03.2026`.
+ */
+export declare const dayInHumanForm: (day: CalendarDay) => string;
+/**
+ * Writes a day the way a machine reads it: `2026-03-19`. This is the
+ * one seam between a day and its text, so a change of how a day is held
+ * inside touches this function and nothing a consumer wrote.
+ */
+export declare const dayInIsoForm: (day: CalendarDay) => string;
+/**
+ * Puts two days in calendar order, earliest first.
+ */
+export declare const CalendarDayOrder: Order.Order<CalendarDay>;
+/**
+ * Counts whole days from the first day to the second. The count runs
+ * negative when the second day stands earlier.
+ */
+export declare const daysBetween: (earlier: CalendarDay, later: CalendarDay) => number;
+/**
+ * Moves a day by whole days. A negative count moves it back.
+ */
+export declare const addDays: (day: CalendarDay, days: number) => CalendarDay;
+/**
+ * Moves a day by whole months, landing on the last day of a month too short to
+ * hold it.
+ *
+ * Moves a day by whole months, and lands on the last day of the month it
+ * arrives in when that month is too short to hold the same number.
+ */
+export declare const addMonths: (day: CalendarDay, months: number) => CalendarDay;
+/**
+ * The last day of the month the given day falls in. Ask the calendar
+ * rather than a table of month lengths: February in a leap year answers
+ * correctly here because the runtime's own calendar answers correctly.
+ */
+export declare const lastDayOfTheMonthOf: (day: CalendarDay) => CalendarDay;
+/**
+ * The first day of the month the given day falls in. Every month starts
+ * on its first, so this one needs no calendar; it stays here beside its
+ * twin, and `monthOf` is the name a consumer reaches for.
+ *
+ * @internal
+ */
+export declare const firstDayOfTheMonthOf: (day: CalendarDay) => CalendarDay;
+/**
+ * Reads a day off the wire from the form a person writes, and writes it
+ * back in that same form. A text this schema refuses carries the whole
+ * three-part refusal into the parse error, so the reader of a failed
+ * command sees what to do next rather than a bare type name.
+ */
+export declare const CalendarDayFromHumanString: Schema.Schema<CalendarDay, string>;
+export {};