@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/contract/errors.d.mts

@@ -15,7 +15,9 @@ declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<
     readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
     readonly message: Schema.String;
   }>>>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The request's input does not decode against the action's input: its message is the schema's
  * own description of what is wrong, and `issues` the same an issue at a time, for a caller that
@@ -44,7 +46,9 @@ export declare class InvalidInput extends InvalidInput_base {
 }
 declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedStruct<"Unauthenticated", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The caller is not authenticated: authentication refuses the credential, or an implementation's
  * `authorize` or a handler fails with it.
@@ -62,7 +66,9 @@ export declare class Unauthenticated extends Unauthenticated_base {
 declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
   readonly scopes: Schema.optionalKey<Schema.NonEmptyArray<Schema.String>>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The caller may not run this action: authentication refuses the credential, an
  * implementation's `authorize` refuses, or a handler fails with it. `scopes`, when given, are every OAuth scope the call needs: a refusal naming

package/dist/contract/errors.mjs

@@ -55,7 +55,7 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 * - From another service's client, such as `ActionHttp.client`, one passed on tells a caller whose token is valid to sign in again: map it to an error the action declares, or to a defect.
 */
 var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: 401 }) {};
-const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+const scopeToken = /^[\u0021\u0023-\u005B\u005D-\u007E]+$/;
 const ScopeToken = Schema.String.check(Schema.isPattern(scopeToken));
 /**
 * The caller may not run this action: authentication refuses the credential, an

package/dist/contract/feed.d.mts

@@ -0,0 +1,127 @@
+import { Anyone } from "./caller.mjs";
+import { Fed, Page } from "./pages.mjs";
+import { Any } from "../Event.mjs";
+import { ErasedAuthorize, ErasedValue, Memoized, Protected } from "./implementation.mjs";
+import { Context, Duration, Effect, Layer, Stream } from "effect";
+/**
+ * An implemented event type, behind its authorizer, as a surface serves it: a poll, whose
+ * subscription `subscriber` names, such as its principal, and a stream, which lasts as long as it
+ * is read. Both authenticate and authorize the subscriber first, and run as it.
+ */
+export interface Feed {
+  readonly event: Any;
+  /**
+   * Releases the `subscription` hook `subscriber`'s polls of `input` hold: present exactly where
+   * its source has a hook, held per subscriber.
+   */
+  readonly release?: ((input: ErasedValue, subscriber: string) => Effect.Effect<void>) | undefined;
+  /**
+   * Authenticates the subscriber, checks `input` by `Action.InputCheck` and authorizes it, as
+   * `poll` and `stream` do first.
+   */
+  readonly admit: (input: ErasedValue) => Effect.Effect<void, unknown, unknown>;
+  readonly poll: (input: ErasedValue, cursor: string | null, options: PollOptions) => Effect.Effect<Page, unknown, unknown>;
+  /**
+   * Admits the subscriber, then reads the feed from a cursor, as often as a subscription
+   * reopens it.
+   */
+  readonly stream: (input: ErasedValue) => Effect.Effect<(cursor: string | null) => Stream.Stream<Fed, unknown, unknown>, unknown, unknown>;
+}
+/** Who polls, and how many occurrences at most a log source's page holds. */
+export interface PollOptions {
+  readonly subscriber?: string | undefined;
+  /** Capped at the page a log source reads anyway; a check's page is answered whole. */
+  readonly maxEvents?: number | undefined;
+}
+/** What reads one event type's source, before its subscriber is admitted. */
+export interface Run extends Omit<Feed, "event" | "stream" | "admit"> {
+  readonly stream: (input: ErasedValue, cursor: string | null) => Stream.Stream<Fed, unknown, unknown>;
+}
+/**
+ * Each event of an implementation with what runs its source, each built on its own over the
+ * implementation's one builder, so a selection runs only the sources of the events it holds.
+ */
+export type Running<E = unknown, R = unknown> = ReadonlyArray<readonly [Any, Memoized<Run, E, R>]>;
+/**
+ * Event types bound to their sources and their authorizer: everything one `Event.implement` call
+ * produced. Its type parameters may be written out, as a package emitting declarations prints
+ * them: `E` its event types, `R` what its sources read per subscription, by event name, `EX` and `RX` the
+ * failures and services of its builder, `RA` what its authorizer reads per subscription, and
+ * `EAX` and `RAX` the failures and services of the authorizer's builder.
+ */
+export declare class EventImplementation<E extends Any, R, EX, RX, RA = never, EAX = never, RAX = never> {
+  #private;
+  /** Tells an event implementation from an action implementation among what a surface is given. */
+  readonly _tag = "EventImplementation";
+  /** Type-only: what its sources read per subscription, by event name. */
+  readonly "~eventRequest": R;
+  /** Type-only: what building its sources fails with. */
+  readonly "~eventBuildError": EX;
+  /** Type-only: what building its sources needs. */
+  readonly "~eventBuildServices": RX;
+  /** Type-only: what its authorizer reads per subscription. */
+  readonly "~eventAuthorizeRequest": RA;
+  /** Type-only: what building its authorizer fails with. */
+  readonly "~eventAuthorizeBuildError": EAX;
+  /** Type-only: what building its authorizer needs. */
+  readonly "~eventAuthorizeBuildServices": RAX;
+  /** The event types this implementation answers. */
+  readonly events: readonly E[];
+  constructor(events: readonly E[], running: Running<EX, RX>, authorizer: Memoized<ErasedAuthorize<Any>, EAX, RAX>);
+  /** Select event types while retaining their sources, authorization and shared builder. */
+  static share(events: readonly Any[], app: AnyEventImplementation): AnyEventImplementation;
+  /** The builders of `app`, its sources' and its authorizer's, as one layer. */
+  static layerOf(app: AnyEventImplementation): Layer.Layer<never, unknown, unknown>;
+  /** The event types of `app` with what runs them, behind its authorizer. */
+  static feedsOf(app: AnyEventImplementation): Effect.Effect<readonly Feed[], never, unknown>;
+  /** What runs each event type `app` holds. */
+  private static held;
+  private static own;
+}
+/** Any event implementation, with its events and channels erased. */
+export type AnyEventImplementation<E extends Any = Any> = EventImplementation<E, unknown, unknown, unknown, unknown, unknown, unknown>;
+/** The event types of the implementations `App`. */
+export type EventOf<App> = App extends {
+  readonly events: ReadonlyArray<infer E extends Any>;
+} ? E : never;
+type IdentityOf<K> = K extends Context.Key<infer I, unknown> ? I : never;
+type RequestOf<R, Name> = Name extends keyof R ? R[Name] : never;
+/**
+ * What a subscription of `E` owes per subscriber where the implementations `App` serve it: its
+ * sources' services, and for a protected event its authorizer's and the subscriber's identity.
+ */
+export type EventRequestOf<App, E extends Any> = App extends {
+  readonly events: ReadonlyArray<infer Held>;
+  readonly "~eventRequest": infer R;
+  readonly "~eventAuthorizeRequest": infer RA;
+} ? E extends Held ? RequestOf<R, E["name"]> | (E["caller"] extends typeof Anyone ? never : RA | IdentityOf<E["caller"]>) : never : never;
+/**
+ * The event types of `App` a surface given the event types `Listed` serves, as `selectEvents`
+ * selects them by identity: one whose type either is assignable to, or is assigned by, one
+ * listed, so an implementation or a list typed wider than its event types still counts.
+ */
+export type ServingEvents<App, Listed extends Any> = EventOf<App> extends (infer E extends Any) ? E extends unknown ? [E] extends [Listed] ? E : [Extract<Listed, E>] extends [never] ? never : E : never : never;
+/** The event implementations among `App` holding an event type of `Listed`: those a surface builds. */
+export type HoldingEvents<App, Listed extends Any> = App extends unknown ? [ServingEvents<App, Listed>] extends [never] ? never : App : never;
+type ServesProtected<App, Listed extends Any> = [Protected<ServingEvents<App, Listed>>] extends [never] ? false : true;
+/**
+ * What a remote surface's requests owe the event implementations `App` per subscription where it
+ * serves their event types of `Listed`: their sources' services, and their authorizer's where a
+ * served one is protected; the identity is the endpoint's own to provide.
+ */
+export type EventServedRequest<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventRequest": infer R;
+  readonly "~eventAuthorizeRequest": infer RA;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : EndpointRequest<R, ServingEvents<App, Listed>> | (ServesProtected<App, Listed> extends true ? Exclude<RA, IdentityOf<Protected<ServingEvents<App, Listed>>["caller"]>> : never) : never;
+type EndpointRequest<R, E extends Any> = E extends unknown ? E["caller"] extends typeof Anyone ? RequestOf<R, E["name"]> : Exclude<RequestOf<R, E["name"]>, IdentityOf<E["caller"]>> : never;
+/** What building the event implementations `App` fails with, where their event types of `Listed` are served. */
+export type EventBuildError<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventBuildError": infer EX;
+  readonly "~eventAuthorizeBuildError": infer EAX;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : EX | (ServesProtected<App, Listed> extends true ? EAX : never) : never;
+/** What building the event implementations `App` reads at startup, where their event types of `Listed` are served. */
+export type EventBuildServices<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventBuildServices": infer RX;
+  readonly "~eventAuthorizeBuildServices": infer RAX;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : RX | (ServesProtected<App, Listed> extends true ? RAX : never) : never;
+export {};

package/dist/contract/feed.mjs

@@ -0,0 +1,249 @@
+import { Anyone } from "./caller.mjs";
+import { Unauthenticated } from "./errors.mjs";
+import { checkInput } from "./input-check.mjs";
+import { assertKnown } from "./names.mjs";
+import { builderLayer, memoized, notMadeHere, selectHeld } from "./implementation.mjs";
+import { jsonRoundTrip } from "./call.mjs";
+import { canonicalInput } from "./canonical.mjs";
+import { reported } from "./reported.mjs";
+import { Events, attachmentsOf, reaches } from "./hub.mjs";
+import { makeLeases } from "./lease.mjs";
+import { AnyOccurrence, Gap } from "./occurrence.mjs";
+import { fedOf, pagedFrom } from "./pages.mjs";
+import { Array, DateTime, Duration, Effect, Layer, Option, Predicate, Stream } from "effect";
+// src/contract/feed.ts
+const defaultNextPoll = Duration.seconds(5);
+const longestNextPoll = Duration.minutes(5);
+const logPageSize = 100;
+const pageLimit = (maxEvents) => Math.min(Math.max(Math.floor(maxEvents), 1), logPageSize);
+const occurrencesOf = (event) => {
+	const sent = jsonRoundTrip(event.payload);
+	return (emitted, cursor) => Effect.matchCauseEffect(sent(emitted.data), {
+		onFailure: (cause) => Effect.as(Effect.annotateLogs(reported(cause), "event", event.name), Gap.make({ cursor })),
+		onSuccess: ({ value }) => Effect.map(DateTime.now, (now) => AnyOccurrence.make({
+			eventId: emitted.eventId ?? globalThis.crypto.randomUUID(),
+			name: event.name,
+			timestamp: emitted.timestamp ?? now,
+			data: value,
+			cursor
+		}))
+	});
+};
+const isOccurrence = (fed) => Predicate.isTagged(fed, "Occurrence");
+/** A poll's page of `items`: their occurrences, `truncated` too where a gap stands for one. */
+const pageOf = (items, { truncated, ...page }) => {
+	const events = items.filter(isOccurrence);
+	return {
+		...page,
+		events,
+		truncated: truncated || events.length < items.length
+	};
+};
+const lifted = (value) => Effect.isEffect(value) ? value : Effect.succeed(value);
+/** The key a subscriber of `input` is reached by, as the source's `key` answers it. */
+const keyOf = (source, input) => source.key === void 0 ? Effect.undefined : lifted(source.key(input));
+const leaseKey = (event, subscriber, input) => Effect.map(canonicalInput(event.input, input), (encoded) => `${subscriber ?? ""}\u0000${encoded}`);
+const answeredPage = ({ answered, items }) => pageOf(items, {
+	cursor: answered.cursor,
+	truncated: answered.truncated === true,
+	hasMore: answered.hasMore === true,
+	nextPoll: Duration.min(Duration.fromInputUnsafe(answered.nextPoll ?? defaultNextPoll), longestNextPoll)
+});
+const checkRun = (event, source, { wakes, polls }) => {
+	const occurrenceOf = occurrencesOf(event);
+	const read = (input, cursor) => Effect.flatMap(source.check(input, cursor), (answered) => Effect.map(Effect.forEach(answered.events, (emitted, index) => occurrenceOf(emitted, index === answered.events.length - 1 ? answered.cursor : cursor)), (items) => ({
+		answered,
+		items
+	})));
+	return {
+		poll: (input, cursor) => Effect.map(read(input, cursor), answeredPage),
+		stream: (input, cursor) => Stream.unwrap(Effect.map(Effect.flatMap(keyOf(source, input), wakes), (woken) => pagedFrom((at) => Effect.map(read(input, at), (delivered) => ({
+			...answeredPage(delivered),
+			fed: fedOf({
+				items: delivered.items,
+				truncated: delivered.answered.truncated === true,
+				from: at,
+				to: delivered.answered.cursor
+			})
+		})), cursor, woken, polls)))
+	};
+};
+const currentRun = (event, source, checking) => checkRun(event, {
+	key: source.key,
+	check: (input, cursor) => Effect.gen(function* () {
+		const at = yield* checking.revision(yield* keyOf(source, input));
+		if (cursor === at) return {
+			cursor: at,
+			events: []
+		};
+		return {
+			cursor: at,
+			events: [{
+				eventId: at,
+				data: yield* source.current(input)
+			}]
+		};
+	})
+}, checking);
+const logRun = (event, source, log) => {
+	const occurrenceOf = occurrencesOf(event);
+	const delivered = (input, key, { cursor, at, value: logged }) => Effect.gen(function* () {
+		if (logged === void 0) {
+			yield* Effect.annotateLogs(Effect.logWarning(`An entry of the log of ${event.name} could not be read: sent as a gap`), "event", event.name);
+			return Gap.make({ cursor });
+		}
+		const emitted = logged.value;
+		if (!reaches(logged.key, key)) return;
+		if (source.match !== void 0 && !(yield* lifted(source.match(input, emitted.data)))) return;
+		const data = source.transform === void 0 ? emitted.data : yield* lifted(source.transform(input, emitted.data));
+		return yield* occurrenceOf({
+			data,
+			eventId: emitted.eventId ?? cursor,
+			timestamp: emitted.timestamp ?? DateTime.makeUnsafe(at)
+		}, cursor);
+	});
+	const received = (input, key, read) => Effect.map(Effect.forEach(read.entries, (entry) => delivered(input, key, entry)), (items) => items.filter(Predicate.isNotUndefined));
+	return {
+		poll: (input, cursor, { maxEvents = logPageSize }) => Effect.flatMap(Effect.all([keyOf(source, input), log.read(cursor, pageLimit(maxEvents))]), ([key, read]) => Effect.map(received(input, key, read), (items) => pageOf(items, {
+			cursor: read.cursor,
+			truncated: read.truncated,
+			hasMore: read.hasMore,
+			nextPoll: defaultNextPoll
+		}))),
+		stream: (input, cursor) => Stream.unwrap(Effect.map(keyOf(source, input), (key) => log.follow(cursor, logPageSize).pipe(Stream.mapEffect((read) => Effect.map(received(input, key, read), (items) => fedOf({
+			items,
+			truncated: read.truncated,
+			from: read.after,
+			to: read.cursor
+		}))), Stream.flattenIterable)))
+	};
+};
+/** `run` with the source's `subscription` held while each subscription lasts. */
+const hooked = (event, run, subscription, leases) => ({
+	...run,
+	poll: (input, cursor, options) => Effect.flatMap(leaseKey(event, options.subscriber, input), (key) => Effect.andThen(leases.hold(key, input), () => run.poll(input, cursor, options))),
+	release: (input, subscriber) => Effect.flatMap(leaseKey(event, subscriber, input), leases.release),
+	stream: (input, cursor) => Stream.unwrap(Effect.map(subscription(input), () => run.stream(input, cursor)))
+});
+const isCheck = (source) => Predicate.isFunction(source.check);
+const isCurrent = (source) => Predicate.isFunction(source.current);
+const runOf = (event, source) => Effect.gen(function* () {
+	const attach = yield* Effect.flatMap(Events, attachmentsOf);
+	let run;
+	if (isCheck(source)) run = checkRun(event, source, yield* attach.check(event, false));
+	else if (isCurrent(source)) run = currentRun(event, source, yield* attach.check(event, true));
+	else run = logRun(event, source, yield* attach.log(event, source.log, source.log.emit));
+	if (source.subscription === void 0) return run;
+	return hooked(event, run, source.subscription, yield* makeLeases(source.subscription, source.lease));
+});
+const isSource = (source) => {
+	const log = Predicate.hasProperty(source, "log") ? source.log : void 0;
+	const logged = Predicate.isObject(log) && (!Predicate.hasProperty(log, "emit") || log.emit === void 0 || Stream.isStream(log.emit));
+	return [
+		Predicate.isFunction(Predicate.hasProperty(source, "check") ? source.check : void 0),
+		Predicate.isFunction(Predicate.hasProperty(source, "current") ? source.current : void 0),
+		logged
+	].filter(Boolean).length === 1;
+};
+const assertSource = (event, source) => {
+	if (!isSource(source)) throw new Error(`Event "${event.name}": its source needs exactly one of check, current or log (give check or current a function, or log its options, {} or { emit: stream })`);
+	return source;
+};
+/**
+* The runtime of `events`' sources: one per event, from the source given for one event alone, or
+* from a record keyed by event name, the builder run once for all of them.
+*/
+const sourcesOf = (events, single, sources) => {
+	const names = events.map((event) => event.name);
+	const checked = (built) => {
+		const keyed = single ? Object.fromEntries(names.map((name) => [name, built])) : Object.fromEntries(Predicate.isObject(built) ? Object.entries(built) : []);
+		assertKnown("sources", Object.keys(keyed), names, "remove it, or list its event");
+		const missing = names.filter((name) => !Object.hasOwn(keyed, name));
+		if (missing.length > 0) throw new Error(`Missing sources: ${missing.join(", ")} (give the source of one event, or a record with an own source per listed event)`);
+		return keyed;
+	};
+	const built = memoized(Effect.isEffect(sources) ? Effect.map(sources, checked) : Effect.sync(() => checked(sources)));
+	return events.map((event) => {
+		const run = memoized(Effect.flatMap(Effect.service(built.key), (keyed) => runOf(event, assertSource(event, keyed[event.name]))));
+		return [event, {
+			key: run.key,
+			layer: Layer.provide(run.layer, built.layer)
+		}];
+	});
+};
+const guarded = (event, run, before) => {
+	const attributes = { "event.name": event.name };
+	const admit = (input) => event.caller === Anyone ? checkInput(event, input) : Effect.flatMap(Effect.serviceOption(event.caller), (subscriber) => Option.isSome(subscriber) ? Effect.andThen(checkInput(event, input), Effect.suspend(() => before(event))) : Effect.fail(new Unauthenticated()));
+	return {
+		event,
+		release: run.release,
+		admit,
+		poll: (input, cursor, options) => Effect.andThen(admit(input), () => run.poll(input, cursor, options)).pipe(Effect.annotateLogs(attributes), Effect.withSpan(event.name, { attributes }, { captureStackTrace: false })),
+		stream: (input) => Effect.as(admit(input), (cursor) => run.stream(input, cursor).pipe(Stream.withSpan(event.name, { attributes })))
+	};
+};
+/**
+* Event types bound to their sources and their authorizer: everything one `Event.implement` call
+* produced. Its type parameters may be written out, as a package emitting declarations prints
+* them: `E` its event types, `R` what its sources read per subscription, by event name, `EX` and `RX` the
+* failures and services of its builder, `RA` what its authorizer reads per subscription, and
+* `EAX` and `RAX` the failures and services of the authorizer's builder.
+*/
+var EventImplementation = class EventImplementation {
+	/** Tells an event implementation from an action implementation among what a surface is given. */
+	_tag = "EventImplementation";
+	/** The event types this implementation answers. */
+	events;
+	#running;
+	#authorizer;
+	constructor(events, running, authorizer) {
+		this.events = events;
+		this.#running = running;
+		this.#authorizer = authorizer;
+	}
+	/** Select event types while retaining their sources, authorization and shared builder. */
+	static share(events, app) {
+		const source = EventImplementation.own(app);
+		return new EventImplementation(events, source.#running, source.#authorizer);
+	}
+	/** The builders of `app`, its sources' and its authorizer's, as one layer. */
+	static layerOf(app) {
+		const source = EventImplementation.own(app);
+		const runs = Layer.mergeAll(Layer.empty, ...EventImplementation.held(app).map(([, run]) => run.layer));
+		return builderLayer(app.events, { layer: runs }, source.#authorizer);
+	}
+	/** The event types of `app` with what runs them, behind its authorizer. */
+	static feedsOf(app) {
+		const source = EventImplementation.own(app);
+		return Effect.gen(function* () {
+			const before = app.events.some((event) => event.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
+			return yield* Effect.forEach(EventImplementation.held(app), ([event, run]) => Effect.map(Effect.service(run.key), (ran) => guarded(event, ran, before)));
+		});
+	}
+	/** What runs each event type `app` holds. */
+	static held(app) {
+		return EventImplementation.own(app).#running.filter(([event]) => app.events.includes(event));
+	}
+	static own(app) {
+		if (!(#running in app)) throw notMadeHere("Event");
+		return app;
+	}
+};
+/**
+* Why `surface` cannot serve `feeds` unless its authentication is `keyed` by a principal: a
+* protected event type whose `subscription` hook is held per subscriber between polls, which a
+* principal names.
+*/
+const unkeyedHook = (surface, feeds, keyed) => keyed ? void 0 : Array.findFirst(feeds, ({ event, release }) => release !== void 0 && event.caller !== Anyone).pipe(Option.map(({ event }) => `${surface} event "${event.name}" is protected and has a subscription hook, so its authentication needs principal to tell poll subscribers apart (give Authentication.make a principal, such as (user) => user.id)`), Option.getOrUndefined);
+/** The event implementations among what a surface is given. */
+const eventsOf = (served) => Array.ensure(served).filter((app) => Predicate.isTagged(app, "EventImplementation"));
+/**
+* The event implementations among `apps` holding an event type of `listed`, each holding those
+* alone, refusing one listed that none holds; every one where `listed` is absent.
+*/
+const selectEvents = (apps, listed) => selectHeld(apps, listed, (app) => app.events, (own, app) => EventImplementation.share(own, app));
+/** The builder layers of event implementations, as a surface provides them. */
+const feedBuilders = (events) => events.map((app) => EventImplementation.layerOf(app));
+/** Every feed of event implementations, from the context their builders provide. */
+const acquireFeeds = (events) => Effect.map(Effect.forEach(events, (app) => EventImplementation.feedsOf(app)), (feeds) => feeds.flat());
+export { EventImplementation, acquireFeeds, defaultNextPoll, eventsOf, feedBuilders, selectEvents, sourcesOf, unkeyedHook };

package/dist/contract/hub.d.mts

@@ -0,0 +1,94 @@
+import { LogStorage } from "./log.mjs";
+import { Any, Emitted } from "../Event.mjs";
+import { Context, Effect, Layer, Scope, Stream } from "effect";
+/** What `notify` and `publish` take: the key whose subscribers they reach. */
+export interface KeyOptions {
+  /**
+   * Reach only the subscribers whose source's `key` answers this, such as one room's; without
+   * it, every subscriber of the event. A subscriber of a source without `key` is reached either way.
+   */
+  readonly key?: string | undefined;
+}
+type ErasedEmitted = Emitted<Any>;
+/**
+ * Where an `Events` keeps its current sources' revisions: counters by name, which only count up,
+ * in an `epoch` telling them from counters that started again.
+ */
+export interface RevisionStorage {
+  /** Changes whenever the counters start again, so a cursor from before is behind every revision. */
+  readonly epoch: string;
+  readonly get: (name: string) => Effect.Effect<number>;
+  /** Adds one to each counter `names` names. */
+  readonly bump: (names: readonly string[]) => Effect.Effect<void>;
+}
+declare const Events_base: Context.ServiceClass<Events, "effect-actions/Event/Events", {
+  /** Wakes the subscribers of `event`'s check source to read it now, rather than at their next poll. */
+  readonly notify: (event: Any, options?: KeyOptions) => Effect.Effect<void>;
+  /** Appends `emitted` to `event`'s log, delivering it to the log source's subscribers now. */
+  readonly publish: <E extends Any>(event: E, emitted: Emitted<E>, options?: KeyOptions) => Effect.Effect<void>;
+}>;
+/**
+ * Where an event's occurrences are announced as they happen: `notify` wakes the subscribers of a
+ * check source to read now, and `publish` appends an occurrence to a log source, both reaching
+ * the subscribers of one `key` or every one. Domain code yields it as it yields a store, and an
+ * entrypoint provides one implementation: `Event.layerMemory`, kept in a process's memory.
+ * Every surface serving events and `Action.client` watching them need it.
+ *
+ * **Gotchas**
+ *
+ * - The handlers announcing and the surfaces serving must share one, as they share a store: built separately, as a test building its handlers under a `provide` of their own does, each has its own, and an announcement reaches no subscriber of the other.
+ * - An event no implementation attached here has no subscribers here: `publish` does nothing for it, and `notify` only moves its revision, so a current source attached later answers the change.
+ * - `notify` of a log source and `publish` to a check source die naming the other: a check source reads your store, so write there and notify; a log source keeps what you publish.
+ * - Implementations attach only to one `layerMemory` or `makeEvents` made: built over another, such as `Events.of` in a test, they die, naming both.
+ */
+export declare class Events extends Events_base {}
+/** `makeEvents`' options: where it keeps logs, and whether check sources are read on a timer. */
+export interface MakeEventsOptions {
+  /**
+   * The storage of `event`'s log, made at its first attachment: the core keeps the log's cursors,
+   * bounds and expiry over it.
+   */
+  readonly log: (event: Any) => LogStorage<ErasedEmitted>;
+  /**
+   * Whether a check source's subscribers also read it again on a timer, each page's `nextPoll`,
+   * besides when notified; defaults to `true`. `false` where a pending timer would keep the host
+   * awake, as it keeps a Durable Object from hibernating: its sources are read when notified, and
+   * 5 seconds after a read that fails.
+   */
+  readonly polls?: boolean | undefined;
+  /**
+   * Whether a log source's `emit` is consumed; defaults to `true`. `false` where the host does not
+   * last, as a Durable Object is evicted while idle and misses what a stream sends meanwhile: a
+   * log source fed by `emit` dies as it attaches, naming `publish`.
+   */
+  readonly emits?: boolean | undefined;
+  /**
+   * Where current sources' revisions are kept; defaults to memory, a new epoch with each
+   * `makeEvents`. A host keeping its logs in storage keeps them there too, so a subscriber's
+   * cursor outlives the host.
+   */
+  readonly revisions?: RevisionStorage | undefined;
+}
+/**
+ * An `Events` for as long as the scope lasts, over the log storage `log` makes: what a host keeping
+ * logs elsewhere, such as a Durable Object's storage, provides as `Events`, its subscribers' wakes
+ * in memory and its logs where `log` keeps them.
+ *
+ * **Gotchas**
+ *
+ * - Make it once per host, around the handlers that announce and the surfaces that serve, as `layerMemory` is built.
+ * - A log's storage is made once per event for the life of the scope, its position read on every append and read: a storage emptied behind its back, as `storage.deleteAll` empties one, starts a new epoch, and a cursor from before reads a gap.
+ */
+export declare const makeEvents: (options: MakeEventsOptions) => Effect.Effect<Events["Service"], never, Scope.Scope>;
+/**
+ * An `Events` kept in the memory of the process that builds it: for a server holding its
+ * subscribers' connections itself, such as Node's, and for tests.
+ *
+ * **Gotchas**
+ *
+ * - Build it once, around the handlers that announce and the surfaces that serve, as a store is: each build is its own.
+ * - A log lives as long as this build, through rebuilds of the implementations attached to it: a restart forgets it, and a subscriber resuming from one of its cursors receives a gap.
+ * - Several builds of one log source share its log, and its `emit` feeds it from one build at a time, so nothing is appended twice.
+ */
+export declare const layerMemory: Layer.Layer<Events>;
+export {};

package/dist/contract/hub.mjs

@@ -0,0 +1,133 @@
+import { makeLog, makeLogStore, memoryStorage } from "./log.mjs";
+import { Context, Effect, Layer, Queue, Stream } from "effect";
+// src/contract/hub.ts
+/** Revisions kept in memory, starting again, in a new epoch, with each call. */
+const memoryRevisions = () => {
+	const counts = /* @__PURE__ */ new Map();
+	return {
+		epoch: globalThis.crypto.randomUUID(),
+		get: (name) => Effect.sync(() => counts.get(name) ?? 0),
+		bump: (names) => Effect.sync(() => {
+			for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+		})
+	};
+};
+const everyKey = (event) => event.name;
+const noKey = (event) => `${event.name}\u0000`;
+const ofKey = (event, key) => `${event.name}\u0000=${key}`;
+/**
+* Where an event's occurrences are announced as they happen: `notify` wakes the subscribers of a
+* check source to read now, and `publish` appends an occurrence to a log source, both reaching
+* the subscribers of one `key` or every one. Domain code yields it as it yields a store, and an
+* entrypoint provides one implementation: `Event.layerMemory`, kept in a process's memory.
+* Every surface serving events and `Action.client` watching them need it.
+*
+* **Gotchas**
+*
+* - The handlers announcing and the surfaces serving must share one, as they share a store: built separately, as a test building its handlers under a `provide` of their own does, each has its own, and an announcement reaches no subscriber of the other.
+* - An event no implementation attached here has no subscribers here: `publish` does nothing for it, and `notify` only moves its revision, so a current source attached later answers the change.
+* - `notify` of a log source and `publish` to a check source die naming the other: a check source reads your store, so write there and notify; a log source keeps what you publish.
+* - Implementations attach only to one `layerMemory` or `makeEvents` made: built over another, such as `Events.of` in a test, they die, naming both.
+*/
+var Events = class extends Context.Service()("effect-actions/Event/Events") {};
+const attached = /* @__PURE__ */ new WeakMap();
+/** How sources attach to `events`, the `Events` `makeEvents` made; one made otherwise dies. */
+const attachmentsOf = (events) => Effect.suspend(() => {
+	const attachments = attached.get(events);
+	return attachments === void 0 ? Effect.die(/* @__PURE__ */ new Error("This Event.Events serves no event implementation: provide Event.layerMemory, or one Event.makeEvents builds")) : Effect.succeed(attachments);
+});
+/** Whether an announcement to `target` reaches a subscriber of `key`: either absent means every one. */
+const reaches = (target, key) => target === void 0 || key === void 0 || target === key;
+const holding = (set, value) => Effect.acquireRelease(Effect.sync(() => {
+	set.add(value);
+	return value;
+}), () => Effect.sync(() => set.delete(value)));
+/**
+* An `Events` for as long as the scope lasts, over the log storage `log` makes: what a host keeping
+* logs elsewhere, such as a Durable Object's storage, provides as `Events`, its subscribers' wakes
+* in memory and its logs where `log` keeps them.
+*
+* **Gotchas**
+*
+* - Make it once per host, around the handlers that announce and the surfaces that serve, as `layerMemory` is built.
+* - A log's storage is made once per event for the life of the scope, its position read on every append and read: a storage emptied behind its back, as `storage.deleteAll` empties one, starts a new epoch, and a cursor from before reads a gap.
+*/
+const makeEvents = (options) => Effect.gen(function* () {
+	const polls = options.polls ?? true;
+	const emits = options.emits ?? true;
+	const revisions = options.revisions ?? memoryRevisions();
+	const scope = yield* Effect.scope;
+	const checks = /* @__PURE__ */ new Map();
+	const logs = /* @__PURE__ */ new Map();
+	const checkOf = (event) => {
+		const found = checks.get(event) ?? {
+			attached: /* @__PURE__ */ new Set(),
+			waiters: /* @__PURE__ */ new Set()
+		};
+		checks.set(event, found);
+		return found;
+	};
+	const isCheck = (event) => (checks.get(event)?.attached.size ?? 0) > 0;
+	const feed = (kept) => Effect.suspend(() => {
+		const [next] = kept.feeding ? [] : kept.waiting;
+		if (next === void 0) return Effect.void;
+		kept.waiting.delete(next);
+		kept.feeding = true;
+		const fed = Effect.andThen(kept.log.feed(Stream.map(next.emit, ({ key, ...value }) => ({
+			value,
+			key
+		}))), Effect.suspend(() => {
+			kept.feeding = false;
+			return feed(kept);
+		}));
+		return Effect.asVoid(Effect.forkIn(fed, scope));
+	});
+	const fedBy = (kept, emit) => Effect.tap(holding(kept.waiting, { emit }), () => feed(kept));
+	const events = Events.of({
+		notify: (event, notifyOptions) => Effect.suspend(() => {
+			if (!isCheck(event) && logs.has(event)) return Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a log source, which keeps what is published: give each occurrence to publish (Event.Events.publish(event, { data }))`));
+			const key = notifyOptions?.key;
+			return Effect.andThen(checks.get(event)?.current === false ? Effect.void : revisions.bump([everyKey(event), key === void 0 ? noKey(event) : ofKey(event, key)]), Effect.sync(() => {
+				for (const waiter of checkOf(event).waiters) if (reaches(key, waiter.key)) Queue.offerUnsafe(waiter.woken, void 0);
+			}));
+		}),
+		publish: (event, emitted, publishOptions) => Effect.suspend(() => {
+			const kept = logs.get(event);
+			if (kept !== void 0) return kept.log.append(emitted, publishOptions?.key);
+			return isCheck(event) ? Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a check source, which reads your store: write the occurrence there, then wake its subscribers (Event.Events.notify(event))`)) : Effect.void;
+		})
+	});
+	attached.set(events, {
+		check: (event, current) => Effect.map(holding(Object.assign(checkOf(event), { current }).attached, {}), () => ({
+			polls,
+			wakes: (key) => Effect.flatMap(Queue.sliding(1), (woken) => Effect.as(holding(checkOf(event).waiters, {
+				key,
+				woken
+			}), Queue.take(woken))),
+			revision: (key) => key === void 0 ? Effect.map(revisions.get(everyKey(event)), (count) => `${revisions.epoch}:${count}`) : Effect.map(Effect.all([revisions.get(noKey(event)), revisions.get(ofKey(event, key))]), ([unkeyed, keyed]) => `${revisions.epoch}:${unkeyed + keyed}:${key}`)
+		})),
+		log: (event, bounds, emit) => Effect.suspend(() => {
+			if (emit !== void 0 && !emits) return Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a log source fed by emit, which this Event.Events does not consume, as its host does not last between requests (publish each occurrence with Event.Events.publish as the host receives it, such as in a call or a route)`));
+			const kept = logs.get(event) ?? {
+				log: makeLog(makeLogStore(options.log(event), bounds)),
+				waiting: /* @__PURE__ */ new Set(),
+				feeding: false
+			};
+			logs.set(event, kept);
+			return Effect.as(emit === void 0 ? Effect.void : fedBy(kept, emit), kept.log);
+		})
+	});
+	return events;
+});
+/**
+* An `Events` kept in the memory of the process that builds it: for a server holding its
+* subscribers' connections itself, such as Node's, and for tests.
+*
+* **Gotchas**
+*
+* - Build it once, around the handlers that announce and the surfaces that serve, as a store is: each build is its own.
+* - A log lives as long as this build, through rebuilds of the implementations attached to it: a restart forgets it, and a subscriber resuming from one of its cursors receives a gap.
+* - Several builds of one log source share its log, and its `emit` feeds it from one build at a time, so nothing is appended twice.
+*/
+const layerMemory = Layer.effect(Events)(makeEvents({ log: () => memoryStorage() }));
+export { Events, attachmentsOf, layerMemory, makeEvents, reaches };