@akterjs/effect 0.0.0-stage → 0.1.0

package/dist/contract/file/rpc/file-rpc.contract.d.mts

@@ -0,0 +1,88 @@
+import { ActorErasedError } from "../../actor/actor-erased.errors.mjs";
+import { ActorNotCreatedError } from "../../actor/actor-not-created.errors.mjs";
+import { ActorUnavailableError } from "../../client/actor-unavailable.errors.mjs";
+import { BillingUnavailableError } from "../../spend/billing-unavailable.errors.mjs";
+import { CallerNotAllowedError } from "../../caller/caller-not-allowed.errors.mjs";
+import { CommandIdExpiredError } from "../../command/command-id-expired.errors.mjs";
+import { HandlerFailedError } from "../../hosted/handler-failed.errors.mjs";
+import { InvalidRequestError } from "../../client/invalid-request.errors.mjs";
+import { SpendCapReachedError } from "../../spend/spend-cap-reached.errors.mjs";
+import { StorageLimitError } from "../../client/storage-limit.errors.mjs";
+import { BlobTransferError } from "../blob-transfer.errors.mjs";
+import { FileAccessDeniedError } from "../access/file-access-denied.errors.mjs";
+import { FileNotFoundError } from "../file-not-found.errors.mjs";
+import { FilesUnavailableError } from "../files-unavailable.errors.mjs";
+import { FileTooLargeError } from "./file-too-large.errors.mjs";
+import { InvalidFileRequestError } from "../invalid-file-request.errors.mjs";
+import { Schema } from "effect";
+import { Rpc, RpcSchema } from "effect/rpc";
+/** The largest chunk a download stream sends, and the largest one an upload may append. */
+declare const fileChunkBytes = 262144;
+declare const uploadChunkBytes = 1048576;
+declare const FileRpcFailure: Schema.Union<readonly [Schema.Union<readonly [typeof ActorErasedError, typeof ActorNotCreatedError, typeof ActorUnavailableError, typeof BillingUnavailableError, typeof CallerNotAllowedError, typeof CommandIdExpiredError, typeof HandlerFailedError, typeof InvalidRequestError, typeof SpendCapReachedError, typeof StorageLimitError]>, typeof BlobTransferError, typeof FileAccessDeniedError, typeof FileNotFoundError, typeof FilesUnavailableError, typeof FileTooLargeError, typeof InvalidFileRequestError]>;
+declare const WireFilePage: Schema.Struct<{
+  readonly cursor: Schema.OptionFromNullOr<Schema.String>;
+  readonly entries: Schema.$Array<Schema.Struct<{
+    readonly bytes: Schema.Int;
+    readonly path: Schema.String;
+    readonly sha256: Schema.String;
+    readonly writtenAt: Schema.Int;
+  }>>;
+}>;
+declare const WireFileUsagePage: Schema.Struct<{
+  readonly cursor: Schema.OptionFromNullOr<Schema.String>;
+  readonly entries: Schema.$Array<Schema.Struct<{
+    readonly bytes: Schema.Int;
+    readonly path: Schema.String;
+    readonly sha256: Schema.String;
+    readonly writtenAt: Schema.Int;
+  }>>;
+  readonly bytes: Schema.BigIntFromString;
+}>;
+declare const Listing: {
+  cursor: Schema.optionalKey<Schema.String>;
+  key: Schema.String;
+  limit: Schema.optionalKey<Schema.Int>;
+  prefix: Schema.optionalKey<Schema.String>;
+};
+declare const Chunk: Schema.Uint8ArrayFromBase64;
+type FileRpcOperation = "download" | "list" | "upload/append" | "upload/close" | "upload/open" | "usage";
+type FileTag<Operation extends FileRpcOperation = FileRpcOperation> = `${string}/files/${Operation}`;
+declare const fileTag: <Operation extends FileRpcOperation>({ actor, operation }: {
+  readonly actor: string;
+  readonly operation: Operation;
+}) => FileTag<Operation>;
+type FileRpcFailureSchema = typeof FileRpcFailure;
+type FileRpcFailureType = FileRpcFailureSchema["Type"];
+type FileRpc = Rpc.Rpc<FileTag<"list">, Schema.Struct<typeof Listing>, typeof WireFilePage, FileRpcFailureSchema> | Rpc.Rpc<FileTag<"usage">, Schema.Struct<typeof Listing>, typeof WireFileUsagePage, FileRpcFailureSchema> | Rpc.Rpc<FileTag<"download">, Schema.Struct<{
+  readonly key: Schema.String;
+  readonly length: Schema.optionalKey<Schema.Int>;
+  readonly offset: Schema.optionalKey<Schema.Int>;
+  readonly path: Schema.String;
+}>, RpcSchema.Stream<typeof Chunk, FileRpcFailureSchema>> | Rpc.Rpc<FileTag<"upload/open">, Schema.Struct<{
+  readonly key: Schema.String;
+}>, Schema.Struct<{
+  readonly upload: Schema.String;
+}>, FileRpcFailureSchema> | Rpc.Rpc<FileTag<"upload/append">, Schema.Struct<{
+  readonly bytes: typeof Chunk;
+  readonly key: Schema.String;
+  readonly offset: Schema.Int;
+  readonly upload: Schema.String;
+}>, Schema.Struct<{
+  readonly received: Schema.Int;
+}>, FileRpcFailureSchema> | Rpc.Rpc<FileTag<"upload/close">, Schema.Struct<{
+  readonly bytes: Schema.Int;
+  readonly key: Schema.String;
+  readonly upload: Schema.String;
+}>, Schema.Struct<{
+  readonly receipt: Schema.String;
+}>, FileRpcFailureSchema>;
+/**
+ * The file streams of one actor, under the tags docs/adr/0016 reserves: `<Actor>/files/<operation>`. Every payload
+ * carries the actor's encoded key as a string, as the actor's other RPCs do on the wire. Effect RPC has no client
+ * streams, so an upload is a short session: `upload/open` returns an id, `upload/append` sends chunks of at most
+ * 1 MiB in order and is idempotent by offset, and `upload/close` checks the length and returns the receipt a command
+ * attaches. A download streams chunks of at most 256 KiB.
+ */
+declare const fileRpcsOf: (actor: string) => readonly FileRpc[];
+export { type FileRpc, type FileRpcFailureType, type FileRpcOperation, type FileTag, fileChunkBytes, fileRpcsOf, fileTag, uploadChunkBytes };

package/dist/contract/file/rpc/file-rpc.contract.mjs

@@ -0,0 +1,117 @@
+import { HostedFailure } from "../../hosted/hosted-failure.schema.mjs";
+import { BlobTransferError } from "../blob-transfer.errors.mjs";
+import { FileAccessDeniedError } from "../access/file-access-denied.errors.mjs";
+import { FileNotFoundError } from "../file-not-found.errors.mjs";
+import { FilesUnavailableError } from "../files-unavailable.errors.mjs";
+import { FileTooLargeError } from "./file-too-large.errors.mjs";
+import { InvalidFileRequestError } from "../invalid-file-request.errors.mjs";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+// src/contract/file/rpc/file-rpc.contract.ts
+/** The largest chunk a download stream sends, and the largest one an upload may append. */
+const fileChunkBytes = 262144;
+const uploadChunkBytes = 1048576;
+const FileRpcFailure = Schema.Union([
+	HostedFailure,
+	BlobTransferError,
+	FileAccessDeniedError,
+	FileNotFoundError,
+	FilesUnavailableError,
+	FileTooLargeError,
+	InvalidFileRequestError
+]);
+const WireFileRef = Schema.Struct({
+	bytes: Schema.Int,
+	path: Schema.String,
+	sha256: Schema.String,
+	writtenAt: Schema.Int
+});
+const WireFilePage = Schema.Struct({
+	cursor: Schema.OptionFromNullOr(Schema.String),
+	entries: Schema.Array(WireFileRef)
+});
+const WireFileUsagePage = Schema.Struct({
+	...WireFilePage.fields,
+	bytes: Schema.BigIntFromString
+});
+const Listing = {
+	cursor: Schema.optionalKey(Schema.String),
+	key: Schema.String,
+	limit: Schema.optionalKey(Schema.Int),
+	prefix: Schema.optionalKey(Schema.String)
+};
+const Chunk = Schema.Uint8ArrayFromBase64;
+const fileTag = ({ actor, operation }) => `${actor}/files/${operation}`;
+/**
+* The file streams of one actor, under the tags docs/adr/0016 reserves: `<Actor>/files/<operation>`. Every payload
+* carries the actor's encoded key as a string, as the actor's other RPCs do on the wire. Effect RPC has no client
+* streams, so an upload is a short session: `upload/open` returns an id, `upload/append` sends chunks of at most
+* 1 MiB in order and is idempotent by offset, and `upload/close` checks the length and returns the receipt a command
+* attaches. A download streams chunks of at most 256 KiB.
+*/
+const fileRpcsOf = (actor) => [
+	Rpc.make(fileTag({
+		actor,
+		operation: "list"
+	}), {
+		error: FileRpcFailure,
+		payload: Listing,
+		success: WireFilePage
+	}),
+	Rpc.make(fileTag({
+		actor,
+		operation: "usage"
+	}), {
+		error: FileRpcFailure,
+		payload: Listing,
+		success: WireFileUsagePage
+	}),
+	Rpc.make(fileTag({
+		actor,
+		operation: "download"
+	}), {
+		error: FileRpcFailure,
+		payload: {
+			key: Schema.String,
+			length: Schema.optionalKey(Schema.Int),
+			offset: Schema.optionalKey(Schema.Int),
+			path: Schema.String
+		},
+		stream: true,
+		success: Chunk
+	}),
+	Rpc.make(fileTag({
+		actor,
+		operation: "upload/open"
+	}), {
+		error: FileRpcFailure,
+		payload: { key: Schema.String },
+		success: Schema.Struct({ upload: Schema.String })
+	}),
+	Rpc.make(fileTag({
+		actor,
+		operation: "upload/append"
+	}), {
+		error: FileRpcFailure,
+		payload: {
+			bytes: Chunk,
+			key: Schema.String,
+			offset: Schema.Int,
+			upload: Schema.String
+		},
+		success: Schema.Struct({ received: Schema.Int })
+	}),
+	Rpc.make(fileTag({
+		actor,
+		operation: "upload/close"
+	}), {
+		error: FileRpcFailure,
+		payload: {
+			bytes: Schema.Int,
+			key: Schema.String,
+			upload: Schema.String
+		},
+		success: Schema.Struct({ receipt: Schema.String })
+	})
+];
+export { fileChunkBytes, fileRpcsOf, fileTag, uploadChunkBytes };

package/dist/contract/file/rpc/file-too-large.errors.d.mts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+declare const FileTooLargeError_base: Schema.Class<FileTooLargeError, Schema.TaggedStruct<"FileTooLargeError", {
+  readonly actor: Schema.String;
+  readonly maximumBytes: Schema.Int;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * An upload would pass the largest file the server accepts, `maximumBytes`, so the chunk was refused and the upload
+ * dropped. Nothing was attached. Split the content into smaller files.
+ */
+export declare class FileTooLargeError extends FileTooLargeError_base {}
+export {};

package/dist/contract/file/rpc/file-too-large.errors.mjs

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+// src/contract/file/rpc/file-too-large.errors.ts
+/**
+* An upload would pass the largest file the server accepts, `maximumBytes`, so the chunk was refused and the upload
+* dropped. Nothing was attached. Split the content into smaller files.
+*/
+var FileTooLargeError = class extends Schema.TaggedError()("FileTooLargeError", {
+	actor: Schema.String,
+	maximumBytes: Schema.Int
+}) {};
+export { FileTooLargeError };

package/dist/contract/file/rpc/rpc-file-clients.layer.d.mts

@@ -0,0 +1,10 @@
+import { ActorFileClients } from "../file-client.adapter.mjs";
+import { Layer } from "effect";
+import { RpcClient } from "effect/rpc";
+/**
+ * File clients that reach an actor's files over its `<Actor>/files/<operation>` RPCs, for `@akterjs/client` and the
+ * in-process client. They give the same `FileClient` an actor's own host gives, so customer code is the same either
+ * way.
+ */
+declare const rpcFileClients: Layer.Layer<ActorFileClients, never, RpcClient.Protocol>;
+export { type ActorFileClients, rpcFileClients };

package/dist/contract/file/rpc/rpc-file-clients.layer.mjs

@@ -0,0 +1,95 @@
+import { Authentication } from "../../caller/authentication.api.mjs";
+import { ActorUnavailableError } from "../../client/actor-unavailable.errors.mjs";
+import { ActorFileClients } from "../file-client.adapter.mjs";
+import { fileRpcsOf, fileTag, uploadChunkBytes } from "./file-rpc.contract.mjs";
+import { Array, Duration, Effect, Layer, Match, Option, Predicate, Record, Schedule, Stream } from "effect";
+import { RpcClient, RpcGroup } from "effect/rpc";
+// src/contract/file/rpc/rpc-file-clients.layer.ts
+const retryMillis = 50;
+const retryLimit = 5;
+const firstByte = 0;
+const one = 1;
+function wireOf(actor) {
+	const group = RpcGroup.make(...fileRpcsOf(actor)).middleware(Authentication);
+	return Effect.map(RpcClient.make(group, { flatten: true }), (client) => ({
+		send: client,
+		watch: client
+	}));
+}
+const unavailable = (actor, message) => ActorUnavailableError.make({
+	actor,
+	message
+});
+/**
+* What a network file client answers for a failure: a lost reply, after its retries, means the actor is unavailable,
+* and the actor RPC failures a file request can't cause fold into the same retryable answer.
+*/
+const clientFailure = (actor) => (failure) => Match.value(failure).pipe(Match.tags({
+	ActorNotCreatedError: () => unavailable(actor, "the actor's files are unavailable"),
+	CommandIdExpiredError: () => unavailable(actor, "the actor's files are unavailable"),
+	HandlerFailedError: () => unavailable(actor, "the actor's files are unavailable"),
+	RpcClientError: () => unavailable(actor, "the server didn't answer. Retry shortly.")
+}), Match.orElse((other) => other));
+const tagOf = (address, operation) => fileTag({
+	actor: address.actor,
+	operation
+});
+/** One unary file RPC. A lost reply is retried, which every file RPC allows: reads, and appends by their offset. */
+const call = ({ address, protocol }, operation, payload) => {
+	const sent = Effect.flatMap(wireOf(address.actor), (wire) => wire.send(tagOf(address, operation), {
+		...payload,
+		key: address.key
+	}));
+	const retried = Effect.retry(Effect.scoped(sent), {
+		schedule: Schedule.exponential(Duration.millis(retryMillis)),
+		times: retryLimit,
+		while: (failure) => Predicate.isTagged(failure, "RpcClientError")
+	});
+	return Effect.provideContext(Effect.mapError(retried, clientFailure(address.actor)), protocol);
+};
+const listingOf = ({ cursor, limit, prefix }) => ({
+	...Record.getSomes({
+		cursor: Option.fromNullishOr(cursor),
+		prefix: Option.fromNullishOr(prefix)
+	}),
+	...Record.getSomes({ limit: Option.fromNullishOr(limit) })
+});
+const slices = (bytes) => Array.makeBy(Math.max(one, Math.ceil(bytes.length / uploadChunkBytes)), (index) => bytes.subarray(index * uploadChunkBytes, (index + one) * uploadChunkBytes));
+const appendAll = (bound, upload, source) => source.pipe(Stream.flatMap((chunk) => Stream.fromIterable(slices(chunk))), Stream.filter((chunk) => chunk.length > firstByte), Stream.runFoldEffect(() => firstByte, (offset, bytes) => Effect.as(call(bound, "upload/append", {
+	bytes,
+	offset,
+	upload
+}), offset + bytes.length)));
+/** An upload is a session: `upload/open`, the source's bytes as ordered `upload/append` chunks, then `upload/close`. */
+const uploadWith = (bound) => (source) => Effect.gen(function* upload() {
+	const opened = yield* call(bound, "upload/open", {});
+	const bytes = yield* appendAll(bound, opened.upload, source);
+	return (yield* call(bound, "upload/close", {
+		bytes,
+		upload: opened.upload
+	})).receipt;
+});
+const downloadWith = ({ address, protocol }) => (path, range) => {
+	const bytes = Stream.unwrap(Effect.map(wireOf(address.actor), (wire) => wire.watch(tagOf(address, "download"), {
+		key: address.key,
+		path,
+		...range
+	})));
+	return Stream.provideContext(Stream.mapError(bytes, clientFailure(address.actor)), protocol);
+};
+const clientWith = (bound) => ({
+	download: downloadWith(bound),
+	fileUsage: (listing = {}) => call(bound, "usage", listingOf(listing)),
+	list: (listing = {}) => call(bound, "list", listingOf(listing)),
+	upload: uploadWith(bound)
+});
+/**
+* File clients that reach an actor's files over its `<Actor>/files/<operation>` RPCs, for `@akterjs/client` and the
+* in-process client. They give the same `FileClient` an actor's own host gives, so customer code is the same either
+* way.
+*/
+const rpcFileClients = Layer.effect(ActorFileClients, Effect.map(Effect.context(), (protocol) => ({ connect: (address) => clientWith({
+	address,
+	protocol
+}) })));
+export { rpcFileClients };

package/dist/contract/fork/fork-rpc.contract.d.mts

@@ -0,0 +1,40 @@
+import { ActorErasedError } from "../actor/actor-erased.errors.mjs";
+import { ActorNotCreatedError } from "../actor/actor-not-created.errors.mjs";
+import { ActorUnavailableError } from "../client/actor-unavailable.errors.mjs";
+import { BillingUnavailableError } from "../spend/billing-unavailable.errors.mjs";
+import { CallerNotAllowedError } from "../caller/caller-not-allowed.errors.mjs";
+import { CommandIdExpiredError } from "../command/command-id-expired.errors.mjs";
+import { HandlerFailedError } from "../hosted/handler-failed.errors.mjs";
+import { InvalidRequestError } from "../client/invalid-request.errors.mjs";
+import { SpendCapReachedError } from "../spend/spend-cap-reached.errors.mjs";
+import { StorageLimitError } from "../client/storage-limit.errors.mjs";
+import { ActorAlreadyExistsError } from "../actor/actor-already-exists.errors.mjs";
+import { KeySchema } from "../actor/actor.contract.mjs";
+import { CommandId } from "../command/command-id.schema.mjs";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+/** What a fork answers: the parent's commit version at the cut the child was copied from. */
+declare const Forked: Schema.Struct<{
+  readonly version: Schema.Int;
+}>;
+type Forked = typeof Forked.Type;
+declare const ForkFailure: Schema.Union<readonly [Schema.Union<readonly [typeof ActorErasedError, typeof ActorNotCreatedError, typeof ActorUnavailableError, typeof BillingUnavailableError, typeof CallerNotAllowedError, typeof CommandIdExpiredError, typeof HandlerFailedError, typeof InvalidRequestError, typeof SpendCapReachedError, typeof StorageLimitError]>, typeof ActorAlreadyExistsError]>;
+type ForkFailure = typeof ForkFailure.Type;
+type ForkTag = `${string}/fork`;
+type ForkRpc = Rpc.Rpc<ForkTag, Schema.Struct<{
+  readonly commandId: typeof CommandId;
+  readonly into: KeySchema;
+  readonly key: KeySchema;
+}>, typeof Forked, typeof ForkFailure>;
+declare const forkTag: (actor: string) => ForkTag;
+/**
+ * Forks one actor under the tag docs/adr/0016 reserves: `<Actor>/fork` copies the actor at `key`, at one cut between
+ * two of its commands, into a new actor of the same kind at `into` (ADR 0017, ADR 0018). The copy starts quiet, with
+ * its own key, and nothing reads it before it is whole. `commandId` names the fork, so a retry with it answers the
+ * same fork instead of making a second copy.
+ */
+declare const forkRpcOf: ({ actor, key }: {
+  readonly actor: string;
+  readonly key: KeySchema;
+}) => ForkRpc;
+export { ForkFailure, type ForkRpc, type ForkTag, Forked, forkRpcOf, forkTag };

package/dist/contract/fork/fork-rpc.contract.mjs

@@ -0,0 +1,26 @@
+import { ActorAlreadyExistsError } from "../actor/actor-already-exists.errors.mjs";
+import { CommandId } from "../command/command-id.schema.mjs";
+import { HostedFailure } from "../hosted/hosted-failure.schema.mjs";
+import { Schema } from "effect";
+import { Rpc } from "effect/rpc";
+// src/contract/fork/fork-rpc.contract.ts
+/** What a fork answers: the parent's commit version at the cut the child was copied from. */
+const Forked = Schema.Struct({ version: Schema.Int });
+const ForkFailure = Schema.Union([HostedFailure, ActorAlreadyExistsError]);
+const forkTag = (actor) => `${actor}/fork`;
+/**
+* Forks one actor under the tag docs/adr/0016 reserves: `<Actor>/fork` copies the actor at `key`, at one cut between
+* two of its commands, into a new actor of the same kind at `into` (ADR 0017, ADR 0018). The copy starts quiet, with
+* its own key, and nothing reads it before it is whole. `commandId` names the fork, so a retry with it answers the
+* same fork instead of making a second copy.
+*/
+const forkRpcOf = ({ actor, key }) => Rpc.make(forkTag(actor), {
+	error: ForkFailure,
+	payload: {
+		commandId: CommandId,
+		into: key,
+		key
+	},
+	success: Forked
+});
+export { ForkFailure, Forked, forkRpcOf, forkTag };

package/dist/contract/history/actor-journal.service.d.mts

@@ -0,0 +1,58 @@
+import { ActorUnavailableError } from "../client/actor-unavailable.errors.mjs";
+import { ActorErasedError } from "../actor/actor-erased.errors.mjs";
+import { ActorDefinition } from "../actor/actor.contract.mjs";
+import { CreatedEntry, HistoryEntry, JobResultEntry, RecordedCommand, UnreadableCommand } from "./history-entry.pure.mjs";
+import { InvalidRequestError } from "../client/invalid-request.errors.mjs";
+import { Context, Duration, Effect, Stream } from "effect";
+interface JournalEntry {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: string;
+  readonly payload: string;
+  readonly principal: string;
+  readonly seq: number;
+}
+interface JournalScope {
+  readonly actor: string;
+  readonly key: string;
+  readonly since: number;
+}
+interface JournalRead extends JournalScope {
+  readonly after: number;
+  readonly limit: number;
+}
+interface JournalWindow {
+  readonly coveredSince: number;
+  readonly entries: readonly JournalEntry[];
+}
+type JournalFailure = ActorErasedError | ActorUnavailableError | InvalidRequestError;
+interface HistorySource {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+interface HistoryWindow<Entry> {
+  readonly coveredSince: number;
+  readonly entries: readonly Entry[];
+}
+interface HistoryOptions {
+  readonly since?: Duration.Input;
+}
+type HistoryOf<Definition extends ActorDefinition> = (key: Definition["key"]["Type"], options?: HistoryOptions) => Effect.Effect<HistoryWindow<HistoryEntry<Definition>>, JournalFailure, ActorJournal>;
+type HistoryStreamOf<Definition extends ActorDefinition> = (key: Definition["key"]["Type"], options?: HistoryOptions) => Stream.Stream<HistoryWindow<HistoryEntry<Definition>>, JournalFailure, ActorJournal>;
+type CoveredSinceOf<Definition extends ActorDefinition> = (key: Definition["key"]["Type"], options?: HistoryOptions) => Effect.Effect<number, JournalFailure, ActorJournal>;
+interface ActorHistory<Definition extends ActorDefinition> {
+  readonly history: HistoryOf<Definition>;
+  readonly historyCoveredSince: CoveredSinceOf<Definition>;
+  readonly historyStream: HistoryStreamOf<Definition>;
+}
+declare const ActorJournal_base: Context.ServiceClass<ActorJournal, "@akterjs/effect/contract/history/actor-journal.service/ActorJournal", {
+  readonly coveredSince: (request: JournalScope) => Effect.Effect<number, JournalFailure>;
+  readonly read: (request: JournalRead) => Effect.Effect<JournalWindow, JournalFailure>;
+}>;
+export declare class ActorJournal extends ActorJournal_base {
+  static coveredSince<Definition extends ActorDefinition>(source: HistorySource): CoveredSinceOf<Definition>;
+  static history<Definition extends ActorDefinition>(source: HistorySource): HistoryOf<Definition>;
+  static historyStream<Definition extends ActorDefinition>(source: HistorySource): HistoryStreamOf<Definition>;
+}
+export type { ActorHistory, CoveredSinceOf, CreatedEntry, HistoryEntry, HistoryOf, HistoryOptions, HistoryStreamOf, HistoryWindow, JobResultEntry, JournalEntry, JournalFailure, JournalRead, JournalScope, JournalWindow, RecordedCommand, UnreadableCommand };

package/dist/contract/history/actor-journal.service.mjs

@@ -0,0 +1,67 @@
+import { decodeEntries } from "./history-entry.pure.mjs";
+import { InvalidRequestError } from "../client/invalid-request.errors.mjs";
+import { Array, Clock, Context, Duration, Effect, Option, Schema, Stream } from "effect";
+// src/contract/history/actor-journal.service.ts
+const everything = 0;
+const beforeFirst = 0;
+const pageSize = 500;
+const sinceOf = (now, options) => Option.match(Option.fromNullishOr(options.since), {
+	onNone: () => everything,
+	onSome: (since) => now - Duration.toMillis(since)
+});
+const nextAfter = (entries) => Option.map(Option.filter(Array.last(entries), () => entries.length === pageSize), (entry) => entry.seq);
+const scopeOf = Effect.fnUntraced(function* scopeOf(source, key, options) {
+	const encoded = yield* Schema.encodeUnknownEffect(source.definition.key)(key).pipe(Effect.mapError((issue) => InvalidRequestError.make({
+		actor: source.name,
+		message: issue.message
+	})));
+	const now = yield* Clock.currentTimeMillis;
+	return {
+		actor: source.name,
+		key: encoded,
+		since: sinceOf(now, options)
+	};
+});
+const joined = (pages) => {
+	const all = Array.fromIterable(pages);
+	return {
+		coveredSince: Option.match(Array.last(all), {
+			onNone: () => everything,
+			onSome: (page) => page.coveredSince
+		}),
+		entries: Array.flatMap(all, (page) => page.entries)
+	};
+};
+var ActorJournal = class ActorJournal extends Context.Service()("@akterjs/effect/contract/history/actor-journal.service/ActorJournal") {
+	static coveredSince(source) {
+		return Effect.fnUntraced(function* coveredSince(key, options = {}) {
+			const scope = yield* scopeOf(source, key, options);
+			return yield* (yield* ActorJournal).coveredSince(scope);
+		});
+	}
+	static history(source) {
+		const stream = ActorJournal.historyStream(source);
+		return (key, options) => Effect.map(Stream.runCollect(stream(key, options)), joined);
+	}
+	static historyStream(source) {
+		const decode = decodeEntries(source);
+		const pagesOf = Effect.fnUntraced(function* pagesOf(key, options) {
+			const scope = yield* scopeOf(source, key, options);
+			const journal = yield* ActorJournal;
+			const window = {
+				...scope,
+				limit: pageSize
+			};
+			const page = (after) => Effect.flatMap(journal.read({
+				...window,
+				after
+			}), (read) => Effect.map(decode(read.entries), (entries) => [[{
+				coveredSince: read.coveredSince,
+				entries
+			}], nextAfter(read.entries)]));
+			return Stream.paginate(beforeFirst, page);
+		});
+		return (key, options = {}) => Stream.unwrap(pagesOf(key, options));
+	}
+};
+export { ActorJournal };

package/dist/contract/history/history-entry.pure.d.mts

@@ -0,0 +1,79 @@
+import { JournalEntry } from "./actor-journal.service.mjs";
+import { ActorAlreadyExistsError } from "../actor/actor-already-exists.errors.mjs";
+import { ActorDefinition, Decoded, PrincipalOf } from "../actor/actor.contract.mjs";
+import { NoJobs } from "../command/command.contract.mjs";
+import { HandlerFailedError } from "../hosted/handler-failed.errors.mjs";
+import { Effect, Exit, Schema } from "effect";
+interface RecordedCommand<Definition extends ActorDefinition, Name extends keyof Definition["commands"]> {
+  readonly at: number;
+  readonly command: Name;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<Definition["commands"][Name]["success"]["Type"], Definition["commands"][Name]["error"]["Type"] | HandlerFailedError>;
+  readonly kind: "recorded";
+  readonly payload: Definition["commands"][Name]["payload"]["Type"];
+  readonly principal: PrincipalOf<Definition>;
+  readonly seq: number;
+}
+type CreationMode = "create" | "ensure";
+interface CreatedEntry<Definition extends ActorDefinition> {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<void, ActorAlreadyExistsError | HandlerFailedError>;
+  readonly kind: "created";
+  readonly mode: CreationMode;
+  readonly payload: Definition["create"]["Type"];
+  readonly principal: PrincipalOf<Definition>;
+  readonly seq: number;
+}
+interface JobResultEntry<Definition extends ActorDefinition, Name extends keyof Definition["jobs"]> {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly exit: Exit.Exit<void, HandlerFailedError>;
+  readonly job: Name;
+  readonly kind: "result";
+  readonly result: Exit.Exit<Definition["jobs"][Name]["success"]["Type"], Definition["jobs"][Name]["error"]["Type"]>;
+  readonly seq: number;
+}
+interface UnreadableCommand {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly kind: "unreadable";
+  readonly reason: string;
+  readonly seq: number;
+}
+type HistoryEntry<Definition extends ActorDefinition> = { readonly [Name in keyof Definition["commands"]]: RecordedCommand<Definition, Name>; }[keyof Definition["commands"]] | (Definition["create"] extends Schema.Never ? never : CreatedEntry<Definition>) | (Definition["jobs"] extends NoJobs ? never : { readonly [Name in keyof Definition["jobs"]]: JobResultEntry<Definition, Name>; }[keyof Definition["jobs"]]) | UnreadableCommand;
+interface EntryPlace {
+  readonly at: number;
+  readonly command: string;
+  readonly commandId: string;
+  readonly seq: number;
+}
+interface ErasedRecorded extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly kind: "recorded";
+  readonly payload: Decoded;
+  readonly principal: Decoded;
+}
+interface ErasedCreated extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly kind: "created";
+  readonly mode: CreationMode;
+  readonly payload: Decoded;
+  readonly principal: Decoded;
+}
+interface ErasedResult extends EntryPlace {
+  readonly exit: Exit.Exit<Decoded, Decoded>;
+  readonly job: string;
+  readonly kind: "result";
+  readonly result: Exit.Exit<Decoded, Decoded>;
+}
+type ErasedEntry = ErasedCreated | ErasedRecorded | ErasedResult | UnreadableCommand;
+interface NamedDefinition {
+  readonly definition: ActorDefinition;
+  readonly name: string;
+}
+declare const decodeEntries: (source: NamedDefinition) => ((entries: readonly JournalEntry[]) => Effect.Effect<readonly ErasedEntry[]>);
+export { type CreatedEntry, type ErasedEntry, type HistoryEntry, type JobResultEntry, type RecordedCommand, type UnreadableCommand, decodeEntries };