post

Import

Import

import * as api from "@fungi.computer/carrier/post";

Exports

Kind	Export	Description
Cclass	PostError	Post rejected an unknown route, conflicting key, or unsupported policy.
Ttype alias	PostDeliveryResult	Receiver’s idempotent admission decision.
Ttype alias	PostOutboxStore	Durable, string-backed rows. A delivered receipt must outlive source replay.
Ttype alias	PostOutbox	Bounded generic delivery owned by Post.
Ttype alias	PostEnvelope	One addressed event identified by the producer’s stable key.
Ttype alias	PostRow	Pending row, terminal receipt, or dead letter.
Ttype alias	PostRoute	Schema-correlated ordinary events or prepared delivery facts.
Ttype alias	PostRegistryRoute	Runtime operations that preserve the route’s schema evidence.
Ttype alias	PostRuntime	One producer’s Post operations.
constconstant	PostDeliveryResultSchema	Accepted receipt, revision cursor, or permanent refusal returned by a receiver.
constconstant	PostEnvelopeSchema	Wire envelope parsed at the durable row and receiver boundaries.
constconstant	PostRowSchema	Persisted Post row parser.
fnfunction	makePostOutbox()	The same bounded delivery and receipt machinery serves Post and BirdDog.
fnfunction	postOutboxPending()	Whether any message in an outbox still awaits a delivery attempt. Delivered receipts and exhausted dead letters are retained but owe nothing more, so a host may let their owner rest.
fnfunction	definePostRoute()
fnfunction	createPost()	Decode at both persisted and DO boundaries with the route’s Effect Schema.
fnfunction	admitPost()	Consumer admission runs inside the receiver’s own SQLite transaction.

PostErrorCclass

Post rejected an unknown route, conflicting key, or unsupported policy.

Extends

• YieldableError<this> & object & Readonly<{ message: string; reason?: "relational-deadline-unsupported"; }>

Constructors

Constructor

Signature

new PostError(message, reason?): PostError;

Parameters

Parameter	Type
message	string
reason?	"relational-deadline-unsupported"

Returns

PostError

Overrides

Signature

Data.TaggedError("PostError")<{
  readonly message: string;
  readonly reason?: "relational-deadline-unsupported";
}>.constructor

Properties

reason?

Signature

readonly optional reason?: "relational-deadline-unsupported";

Inherited from

Signature

Data.TaggedError("PostError").reason;

message

Signature

message: string;

Inherited from

Signature

Data.TaggedError("PostError").message;

PostDeliveryResultTtype alias

Signature

type PostDeliveryResult =
  | "accepted"
  | "duplicate"
  | "refused"
  | Readonly<{
      status: "accepted" | "duplicate";
      cursor: number;
    }>
  | Readonly<{
      status: "accepted" | "duplicate" | "refused";
      receipt: Schema.Json;
    }>;

Receiver’s idempotent admission decision.

---

PostOutboxStoreTtype alias

Signature

type PostOutboxStore<E> = Readonly<{
  put: (key, value) => Effect.Effect<void, E>;
  read: (key) => Effect.Effect<string | undefined, E>;
  list: (
    limit,
    afterKey?,
  ) => Effect.Effect<
    readonly Readonly<{
      key: string;
      value: string;
    }>[],
    E
  >;
  delete: (key) => Effect.Effect<void, E>;
}>;

Durable, string-backed rows. A delivered receipt must outlive source replay.

Type Parameters

Type Parameter
E

---

PostOutboxTtype alias

Signature

type PostOutbox<M, E> = Readonly<{
  enqueue: (message, at?) => Effect.Effect<number | undefined, E>;
  drain: () => Effect.Effect<void, E>;
  nextWakeAt: () => Effect.Effect<number | undefined, E>;
  deadLetters: (limit, afterKey?) => Effect.Effect<M[], E>;
}>;

Bounded generic delivery owned by Post.

Type Parameters

Type Parameter
M
E

---

PostEnvelopeTtype alias

Signature

type PostEnvelope = Schema.Schema.Type<typeof PostEnvelopeSchema>;

One addressed event identified by the producer’s stable key.

---

PostRowTtype alias

Signature

type PostRow = Schema.Schema.Type<typeof PostRowSchema>;

Pending row, terminal receipt, or dead letter.

---

PostRouteTtype alias

Signature

type PostRoute<A, E, D, AI, EI, DI> = Readonly<{
  addressKind: string;
  deadlineMs?: number;
  address: Schema.Codec<A, AI>;
  event: Schema.Codec<E, EI>;
  name: (address) => string;
  namespace: Readonly<{
     getByName: (name) => Readonly<{
        deliver: (envelope) => Promise<PostDeliveryResult>;
     }>;
  }>;
}> &
  | Readonly<{
  prepare: Readonly<{
     event: Schema.Codec<D, DI>;
     run: (address, intent, signal) => Promise<D>;
  }>;
  onDelivered?: (address, event) => void;
  onCursor?: (address, event, cursor) => void;
  onRefused?: (address, event) => void;
}>
  | Readonly<{
  prepare?: undefined;
  onDelivered?: (address, event) => void;
  onCursor?: (address, event, cursor) => void;
  onRefused?: (address, event) => void;
}>;

Schema-correlated ordinary events or prepared delivery facts.

Type Parameters

Type Parameter	Default type
A	-
E	-
D	E
AI	A
EI	E
DI	EI

---

PostRegistryRouteTtype alias

Signature

type PostRegistryRoute = Readonly<{
  addressKind: string;
  deadlineMs?: number;
  address: Schema.Codec<unknown, unknown>;
  event: Schema.Codec<unknown, unknown>;
  encodeEnvelope: (envelope) => PostEnvelope;
  parseDelivery: (envelope) => PostEnvelope;
  prepareEnvelope?: (envelope, signal) => Promise<PostEnvelope>;
  recordDelivered?: (envelope) => void;
  nameOf: (envelope) => string;
  namespace: PostRoute<never, never>["namespace"];
  recordCursor?: (envelope, cursor) => void;
  recordRefused?: (envelope) => void;
}>;

Runtime operations that preserve the route’s schema evidence.

---

PostRuntimeTtype alias

Signature

type PostRuntime<R> = Readonly<{
  send: <K>(input) => void;
  execute: (job) => Promise<
    Readonly<{
      kind: "completed";
    }>
  >;
  enqueueDue: (limit?, afterKey?) => Promise<string | undefined>;
  releaseNow: (limit?, afterKey?) => Promise<string | undefined>;
  deadLetters: (
    limit?,
    afterKey?,
  ) => Readonly<{
    letters: readonly Readonly<{
      key: string;
      reason: "refused" | "exhausted" | "expired";
      envelope: PostEnvelope;
      attempts: number;
    }>[];
    nextCursor: string | undefined;
  }>;
  latest: <K>(
    kind,
    address,
  ) =>
    | Readonly<{
        key: string;
        row: PostRow;
      }>
    | undefined;
  retry: (key) => Promise<void>;
  read: (key) => PostRow | undefined;
  nextWake: () => number | null;
}>;

One producer’s Post operations.

Type Parameters

Type Parameter
R extends Record<string, PostRegistryRoute>

PostDeliveryResultSchemaconstconstant

Signature

const PostDeliveryResultSchema: Union<
  readonly [
    Literals<readonly ["accepted", "duplicate", "refused"]>,
    Struct<{
      status: Literals<readonly ["accepted", "duplicate"]>;
      cursor: Int;
    }>,
    Struct<{
      status: Literals<readonly ["accepted", "duplicate", "refused"]>;
      receipt: Codec<Json, Json, never, never>;
    }>,
  ]
>;

Accepted receipt, revision cursor, or permanent refusal returned by a receiver.

---

PostEnvelopeSchemaconstconstant

Signature

const PostEnvelopeSchema: Struct<{
  key: String;
  kind: String;
  address: Unknown;
  event: Unknown;
}>;

Wire envelope parsed at the durable row and receiver boundaries.

---

PostRowSchemaconstconstant

Signature

const PostRowSchema: fromJsonString<
  Union<
    readonly [
      Struct<{
        state: Literal<"pending">;
        envelope: Struct<{
          key: String;
          kind: String;
          address: Unknown;
          event: Unknown;
        }>;
        attempts: Int;
        nextAttemptAt: Number;
        deadlineAt: optional<Number>;
        jobId: optional<String>;
        delivery: optional<
          Struct<{
            key: String;
            kind: String;
            address: Unknown;
            event: Unknown;
          }>
        >;
        nextKey: optional<String>;
      }>,
      Struct<{
        state: Literal<"delivered">;
        receipt: optional<Codec<Json, Json, never, never>>;
        nextKey: optional<String>;
      }>,
      Struct<{
        state: Literal<"dead">;
        envelope: Struct<{
          key: String;
          kind: String;
          address: Unknown;
          event: Unknown;
        }>;
        attempts: Int;
        reason: Literals<readonly ["refused", "exhausted", "expired"]>;
        deadlineAt: optional<Number>;
        receipt: optional<Codec<Json, Json, never, never>>;
        delivery: optional<
          Struct<{
            key: String;
            kind: String;
            address: Unknown;
            event: Unknown;
          }>
        >;
        nextKey: optional<String>;
      }>,
    ]
  >
>;

Persisted Post row parser.

makePostOutbox()fnfunction

Signature

function makePostOutbox<M, E>(options): PostOutbox<M, E>;

The same bounded delivery and receipt machinery serves Post and BirdDog.

Type Parameters

Type Parameter
M
E

Parameters

Parameter	Type
options	Readonly<{ message: Schema.Codec<M>; key: (message) => string; outbox: PostOutboxStore<E>; deliver: (message) => Effect.Effect<boolean, E>; scheduleWake: (at) => Effect.Effect<void, E>; now: () => number; invalidRow: () => E; encodingFailed: () => E; }>

Returns

PostOutbox<M, E>

---

postOutboxPending()fnfunction

Signature

function postOutboxPending<M, E>(options): Effect<boolean, E>;

Whether any message in an outbox still awaits a delivery attempt. Delivered receipts and exhausted dead letters are retained but owe nothing more, so a host may let their owner rest.

Type Parameters

Type Parameter
M
E

Parameters

Parameter	Type
options	Readonly<{ message: Schema.Codec<M>; outbox: Pick<PostOutboxStore<E>, "list">; }>

Returns

Effect<boolean, E>

---

definePostRoute()fnfunction

Call Signature

Signature

function definePostRoute<A, E, AI, EI>(route): PostRoute<A, E, E, AI, EI, EI> & Omit<Readonly<{
  addressKind: string;
  deadlineMs?: number;
  address: Codec<unknown, unknown>;
  event: Codec<unknown, unknown>;
  encodeEnvelope: (envelope) => object;
  parseDelivery: (envelope) => object;
  prepareEnvelope?: (envelope, signal) => Promise<{
     key: string;
     kind: string;
     address: unknown;
     event: unknown;
  }>;
  recordDelivered?: (envelope) => void;
  nameOf: (envelope) => string;
  namespace: Readonly<{
     getByName: (name) => Readonly<{
        deliver: (envelope) => Promise<...>;
     }>;
  }>;
  recordCursor?: (envelope, cursor) => void;
  recordRefused?: (envelope) => void;
}>, "address" | "event">;

Preserve each route’s inferred address and event types in a registry.

Type Parameters

Type Parameter	Default type
A	-
E	-
AI	A
EI	E

Parameters

Parameter

Type

route

Readonly<{ addressKind: string; deadlineMs?: number; address: Codec<A, AI>; event: Codec<E, EI>; name: (address) => string; namespace: Readonly<{ getByName: (name) => Readonly<{ deliver: (envelope) => Promise<PostDeliveryResult>; }>; }>; }> & Readonly<{ prepare?: undefined; onDelivered?: (address, event) => void; onCursor?: (address, event, cursor) => void; onRefused?: (address, event) => void; }>

Returns

PostRoute<A, E, E, AI, EI, EI> & Omit<Readonly<{ addressKind: string; deadlineMs?: number; address: Codec<unknown, unknown>; event: Codec<unknown, unknown>; encodeEnvelope: (envelope) => object; parseDelivery: (envelope) => object; prepareEnvelope?: (envelope, signal) => Promise<{ key: string; kind: string; address: unknown; event: unknown; }>; recordDelivered?: (envelope) => void; nameOf: (envelope) => string; namespace: Readonly<{ getByName: (name) => Readonly<{ deliver: (envelope) => Promise<…>; }>; }>; recordCursor?: (envelope, cursor) => void; recordRefused?: (envelope) => void; }>, "address" | "event">

Call Signature

Signature

function definePostRoute<A, E, D, AI, EI, DI>(route): PostRoute<A, E, D, AI, EI, DI> & Omit<Readonly<{
  addressKind: string;
  deadlineMs?: number;
  address: Codec<unknown, unknown>;
  event: Codec<unknown, unknown>;
  encodeEnvelope: (envelope) => object;
  parseDelivery: (envelope) => object;
  prepareEnvelope?: (envelope, signal) => Promise<{
     key: string;
     kind: string;
     address: unknown;
     event: unknown;
  }>;
  recordDelivered?: (envelope) => void;
  nameOf: (envelope) => string;
  namespace: Readonly<{
     getByName: (name) => Readonly<{
        deliver: (envelope) => Promise<...>;
     }>;
  }>;
  recordCursor?: (envelope, cursor) => void;
  recordRefused?: (envelope) => void;
}>, "address" | "event">;

Preserve each route’s inferred address and event types in a registry.

Type Parameters

Type Parameter	Default type
A	-
E	-
D	-
AI	A
EI	E
DI	EI

Parameters

Parameter

Type

route

Readonly<{ addressKind: string; deadlineMs?: number; address: Codec<A, AI>; event: Codec<E, EI>; name: (address) => string; namespace: Readonly<{ getByName: (name) => Readonly<{ deliver: (envelope) => Promise<PostDeliveryResult>; }>; }>; }> & Readonly<{ prepare: Readonly<{ event: Schema.Codec<D, DI>; run: (address, intent, signal) => Promise<D>; }>; onDelivered?: (address, event) => void; onCursor?: (address, event, cursor) => void; onRefused?: (address, event) => void; }>

Returns

PostRoute<A, E, D, AI, EI, DI> & Omit<Readonly<{ addressKind: string; deadlineMs?: number; address: Codec<unknown, unknown>; event: Codec<unknown, unknown>; encodeEnvelope: (envelope) => object; parseDelivery: (envelope) => object; prepareEnvelope?: (envelope, signal) => Promise<{ key: string; kind: string; address: unknown; event: unknown; }>; recordDelivered?: (envelope) => void; nameOf: (envelope) => string; namespace: Readonly<{ getByName: (name) => Readonly<{ deliver: (envelope) => Promise<…>; }>; }>; recordCursor?: (envelope, cursor) => void; recordRefused?: (envelope) => void; }>, "address" | "event">

---

createPost()fnfunction

Signature

function createPost<R>(options): PostRuntime<R>;

Decode at both persisted and DO boundaries with the route’s Effect Schema.

Type Parameters

Type Parameter

R extends Record<string, Readonly<{ addressKind: string; deadlineMs?: number; address: Codec<unknown, unknown>; event: Codec<unknown, unknown>; encodeEnvelope: (envelope) => object; parseDelivery: (envelope) => object; prepareEnvelope?: (envelope, signal) => Promise<{ key: string; kind: string; address: unknown; event: unknown; }>; recordDelivered?: (envelope) => void; nameOf: (envelope) => string; namespace: Readonly<{ getByName: (name) => Readonly<{ deliver: (envelope) => Promise<PostDeliveryResult>; }>; }>; recordCursor?: (envelope, cursor) => void; recordRefused?: (envelope) => void; }>>

Parameters

Parameter	Type
options	Readonly<{ routes: R; owner: WatchdogSqliteOwner; transactional: WatchdogTransactionalProjection; readJob: WatchdogRuntime["read"]; now: () => number; scheduleWake: (at) => Promise<void>; }>

Returns

PostRuntime<R>

---

admitPost()fnfunction

Signature

function admitPost<E, I>(options): PostDeliveryResult;

Consumer admission runs inside the receiver’s own SQLite transaction.

Type Parameters

Type Parameter
E
I

Parameters

Parameter	Type
options	Readonly<{ key: string; event: unknown; schema: Schema.Codec<E, I>; hasReceipt: (key) => boolean; apply: (event) => PostDeliveryResult; putReceipt: (key) => void; }>

Returns

PostDeliveryResult