effect-browser 0.3.0-beta.6 → 0.3.0-beta.8

package/dist/{Supervisor-Im6-wbg5.d.mts → Supervisor-CYWFK3vM.d.mts}

@@ -1,8 +1,8 @@
-import { c as DisconnectCause } from "./BrowserEvent-DzdNdvoh.mjs";
+import { c as DisconnectCause } from "./BrowserEvent-BRu2juEz.mjs";
 import { Service, t as Browser_d_exports } from "./Browser.mjs";
 import { Cause, Duration, Effect, Schedule, Schema, Scope, Stream } from "effect";
 declare namespace lifecycle_d_exports {
-  export { Closed, Command, Down, GenerationState, Input, Kept, Live, Lost, Open, Opening, Released, Reopening, Resolution, Settled, State, Step, Unconfirmed, resolve, start, transition };
+  export { Closed, Command, Down, Drain, Draining, GenerationState, Held, Input, Kept, Live, Lost, Open, Opening, Released, Reopening, Resolution, Settled, State, Step, Unconfirmed, lookup, resolve, start, transition };
 }
 declare const Settled_base: Schema.Class<Settled, Schema.TaggedStruct<"Settled", {}>, {}>;
 /** The provider confirmed that the generation's browser ended. */
@@ -23,6 +23,12 @@ declare class Reopening extends Reopening_base {}
 declare const Open_base: Schema.Class<Open, Schema.TaggedStruct<"Open", {}>, {}>;
 /** Open: `browser` gives this generation until the next one opens. */
 declare class Open extends Open_base {}
+declare const Draining_base: Schema.Class<Draining, Schema.TaggedStruct<"Draining", {
+  readonly reason: Schema.Literals<readonly ["rotated", "lost", "retired"]>;
+  readonly revokeAt: Schema.Finite;
+}>, {}>;
+/** No longer serving; holds end at this host-monotonic deadline or when their owners let go. */
+declare class Draining extends Draining_base {}
 declare const Lost_base: Schema.Class<Lost, Schema.TaggedStruct<"Lost", {
   readonly cause: Schema.Literals<readonly ["connection", "session", "released"]>;
 }>, {}>;
@@ -48,99 +54,115 @@ declare const Kept_base: Schema.Class<Kept, Schema.TaggedStruct<"Kept", {}>, {}>
  * closed, and its provider runs it on, and bills, until something adopts and releases it.
  */
 declare class Kept extends Kept_base {}
-declare const GenerationState: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
+declare const GenerationState: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Draining, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
 type GenerationState = typeof GenerationState.Type;
 /** A generation that opened: its number, and what the runtime keeps to serve and end it. */
 interface Live<A> {
   readonly number: number;
   readonly value: A;
 }
-/**
- * At most one generation opens and at most one serves. Both do while a rotation makes the next
- * before it breaks the current, and `Down` keeps serving one that a rotation failed to replace.
- */
-type State<A> = {
+interface Held<A, H> extends Live<A> {
+  readonly holds: ReadonlySet<H>;
+}
+/** Release ownership remains here until the provider and generation scope have finished. */
+interface Drain<A, H> {
+  readonly _tag: "Draining" | "Releasing" | "Leaving";
+  readonly live: Held<A, H>;
+  readonly ending: Draining;
+}
+/** One serving generation, one shared acquisition, and prior generations still owned. */
+type State<A, H = unknown> = ({
   readonly _tag: "Opening";
   readonly number: number;
-  readonly serving: Live<A> | undefined;
+  readonly serving: Held<A, H> | undefined;
 } | {
   readonly _tag: "Open";
-  readonly serving: Live<A>;
+  readonly serving: Held<A, H>;
 } | {
   readonly _tag: "Down";
   readonly number: number;
   readonly detail: string;
   readonly cause: unknown;
-  readonly serving: Live<A> | undefined;
+  readonly serving: Held<A, H> | undefined;
 } | {
   readonly _tag: "Retired";
+}) & {
+  readonly draining: ReadonlyMap<number, Drain<A, H>>;
 };
-type Input<A> = {
+type Input<A, H = unknown> = {
   readonly _tag: "Opened";
   readonly live: Live<A>;
-} |
-/** The open of `number` failed for good. */
-{
+} | {
   readonly _tag: "Failed";
   readonly number: number;
   readonly detail: string;
   readonly cause: unknown;
-} |
-/** The open of `number` was stopped, as on retiring, before it opened. */
-{
+} | {
   readonly _tag: "Abandoned";
   readonly number: number;
 } | {
   readonly _tag: "Lost";
   readonly number: number;
   readonly cause: DisconnectCause;
-} |
-/** A caller asks for the next generation, or the rotation time of `due` came. */
-{
+} | {
   readonly _tag: "Rotate";
   readonly due?: number | undefined;
 } | {
   readonly _tag: "Retire";
-} |
-/** Stop as `Retire` does, but leave the serving generation running. */
-{
+} | {
   readonly _tag: "Keep";
+} | {
+  readonly _tag: "Hold";
+  readonly number?: number | undefined;
+  readonly hold: H;
+} | {
+  readonly _tag: "Let";
+  readonly number: number;
+  readonly hold: H;
+} | {
+  readonly _tag: "Revoke";
+  readonly number: number;
 } | {
   readonly _tag: "Released";
   readonly number: number;
-  readonly released: Released;
+  readonly released?: Released | undefined;
 };
-type Command<A> =
-/** Open `number`, after the release of `after` has finished. */
-{
+type Command<A> = {
   readonly _tag: "Open";
   readonly number: number;
   readonly after: number | undefined;
-} |
-/** Watch a generation that opened for its loss and its rotation time. */
-{
+} | {
   readonly _tag: "Watch";
   readonly live: Live<A>;
-} | {
-  readonly _tag: "Release";
+} |
+/** Signal ending and arrange revocation. Repeated only when loss/retirement accelerates it. */
+{
+  readonly _tag: "Drain";
   readonly live: Live<A>;
+  readonly ending: Draining;
 } |
-/** Close its scope without asking its provider to release it. */
+/** Revoke/close holds, await their Let inputs, release the provider, then close its scope. */
 {
+  readonly _tag: "Release";
+  readonly live: Live<A>;
+  readonly ending: Draining;
+} | {
   readonly _tag: "Leave";
   readonly live: Live<A>;
+  readonly ending: Draining;
 };
-interface Step<A> {
-  readonly state: State<A>;
-  /** Generation numbers and their new states, to publish in this order. */
+interface Step<A, H = unknown> {
+  readonly state: State<A, H>;
   readonly events: ReadonlyArray<readonly [number, GenerationState]>;
   readonly commands: ReadonlyArray<Command<A>>;
-  /** For `Rotate`, the generation to wait for, unless retired. */
   readonly reply?: number | undefined;
+  readonly borrowed?: Live<A> | undefined;
 }
-declare const start: <A>() => Step<A>;
-/** The state after `input`, with the events to publish and the commands to run. */
-declare const transition: <A>(state: State<A>, input: Input<A>, exclusive: boolean) => Step<A>;
+declare const start: <A, H = unknown>() => Step<A, H>;
+/** The holds still owned for a generation, including one whose release has begun. */
+declare const lookup: <A, H>(state: State<A, H>, number: number) => Held<A, H> | undefined;
+/** Pure admission and lifecycle changes. A rejected hold preserves state identity. */
+declare const transition: <A, H = unknown>(state: State<A, H>, input: Input<A, H>, exclusive: boolean, now?: number, handover?: number) => Step<A, H>;
 type Resolution<A> = {
   readonly _tag: "Serve";
   readonly live: Live<A>;
@@ -150,18 +172,16 @@ type Resolution<A> = {
   readonly detail: string;
   readonly cause?: unknown;
 };
-/**
- * What a caller waiting for generation `target`, or for any when it is undefined, gets in
- * `state`; undefined while it should go on waiting.
- */
-declare const resolve: <A>(state: State<A>, target: number | undefined) => Resolution<A> | undefined;
+/** An unheld browser resolution; use obtains its hold atomically through Hold instead. */
+declare const resolve: <A, H>(state: State<A, H>, target: number | undefined) => Resolution<A> | undefined;
 declare namespace Supervisor_d_exports {
-  export { Closed, Down, Generation, GenerationState, Kept, Lost, Open, Opened, Opening, Options, Released, Reopening, Settled, Supervisor, Unavailable, Unconfirmed, make };
+  export { Closed, Down, Draining, Generation, GenerationState, Kept, Lease, Lost, Open, Opened, Opening, Options, Released, Reopening, Settled, Superseded, Supervisor, Unavailable, Unconfirmed, UseOptions, make };
 }
 declare const Generation_base: Schema.Class<Generation, Schema.Struct<{
   readonly number: Schema.Int;
   readonly at: Schema.Finite;
-  readonly state: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
+  readonly hostTime: Schema.Finite;
+  readonly state: Schema.Union<readonly [typeof Opening, typeof Reopening, typeof Open, typeof Draining, typeof Lost, typeof Down, typeof Closed, typeof Kept]>;
 }>, {}>;
 /** One change in a generation's life. `at` is wall-clock epoch milliseconds from the Effect `Clock`. */
 declare class Generation extends Generation_base {}
@@ -178,7 +198,8 @@ declare class Unavailable extends Unavailable_base {
   get message(): string;
 }
 /** One generation, as a provider opened it in the scope the supervisor gave it. */
-interface Opened {
+interface Opened<A = void> {
+  readonly value: A;
   readonly browser: Service;
   /**
    * End the generation, and say whether the provider confirmed its end. The supervisor asks it
@@ -187,9 +208,9 @@ interface Opened {
    */
   readonly release?: Effect.Effect<Released> | undefined;
 }
-interface Options<E, R> {
+interface Options<E, R, A = void> {
   /** Opens one generation in the scope it is given. */
-  readonly open: Effect.Effect<Opened, E, R>;
+  readonly open: Effect.Effect<Opened<A>, E, R>;
   /** When to try a failed open again. Defaults to exponential from 1 second, for 5 minutes. */
   readonly reopen?: Schedule.Schedule<unknown, E> | undefined;
   /**
@@ -204,6 +225,8 @@ interface Options<E, R> {
   readonly rotateBefore?: Duration.Input | undefined;
   /** Generations must not overlap: a rotation releases the current one before it opens the next. */
   readonly exclusive?: boolean | undefined;
+  /** Finite, nonnegative time outgoing holds may finish; defaults to 30 seconds. */
+  readonly handover?: Duration.Input | undefined;
   /**
    * Closing the scope leaves the serving generation running, `Kept`: it closes the generation's
    * scope but never asks `release`. For providers whose scope only disconnects, such as
@@ -213,7 +236,29 @@ interface Options<E, R> {
   /** How long `browser` and `rotate` wait for a generation to open. Defaults to 2 minutes. */
   readonly waitTimeout?: Duration.Input | undefined;
 }
-interface Supervisor {
+declare const Superseded_base: Schema.Class<Superseded, Schema.TaggedStruct<"Superseded", {
+  readonly generation: Schema.Int;
+  readonly reason: Schema.Literals<readonly ["rotated", "lost", "retired"]>;
+  readonly revokeAt: Schema.Finite;
+}>, Cause.YieldableError>;
+/** Work whose generation was revoked; input receipts still determine whether input reached a site. */
+declare class Superseded extends Superseded_base {}
+interface Lease<A> {
+  readonly generation: number;
+  readonly browser: Service;
+  readonly value: A;
+  /** First notice that serving ended; loss or retirement may revoke before its deadline. */
+  readonly ending: Effect.Effect<Superseded>;
+  /** An independent scope; its resources close before provider release. Fails once revoked. */
+  readonly retain: Effect.Effect<Scope.Closeable, Superseded>;
+}
+interface UseOptions {
+  /** Finite, nonnegative wait for a serving generation. Zero makes an immediate attempt. */
+  readonly wait?: Duration.Input | undefined;
+}
+interface Supervisor<A = void> {
+  /** Scoped work on the current generation. Revocation interrupts it and waits for its cleanup. */
+  readonly use: <B, E, R>(work: (lease: Lease<A>) => Effect.Effect<B, E, R>, options?: UseOptions) => Effect.Effect<B, E | Unavailable | Superseded, Exclude<R, Scope.Scope>>;
   /** The current generation's browser, waiting up to `waitTimeout` while none is open. */
   readonly browser: Effect.Effect<Service, Unavailable>;
   /** Each generation's changes, in order. A new reader first gets the latest 64; ends on retiring. */
@@ -223,8 +268,13 @@ interface Supervisor {
   /** Stop opening at once, release every generation, and wait until each release has finished. */
   readonly retire: Effect.Effect<void>;
 }
-/** Supervise generations of a provider's browser for as long as the scope is open. */
-declare const make: <E, R>(options: Options<E, R>) => Effect.Effect<Supervisor, never, Scope.Scope | Exclude<R, Scope.Scope>>;
+type Provider = Omit<Opened, "value">;
+type MakeOptions<E, R, A> = Omit<Options<E, R, A>, "open"> & {
+  readonly open: Effect.Effect<Opened<A> | Provider, E, R>;
+};
+/** Supervise scoped generation values. Browser-only providers retain their existing void value. */
+declare function make<E, R, A = void>(options: Options<E, R, A>): Effect.Effect<Supervisor<A>, never, Scope.Scope | Exclude<R, Scope.Scope>>;
+declare function make<E, R>(options: MakeOptions<E, R, never>): Effect.Effect<Supervisor<void>, never, Scope.Scope | Exclude<R, Scope.Scope>>;
 //#endregion
-export { Settled as _, Supervisor_d_exports as a, Closed as c, Kept as d, Lost as f, Reopening as g, Released as h, Supervisor as i, Down as l, Opening as m, Opened as n, Unavailable as o, Open as p, Options as r, make as s, Generation as t, GenerationState as u, Unconfirmed as v };
-//# sourceMappingURL=Supervisor-Im6-wbg5.d.mts.map
+export { Unconfirmed as S, Open as _, Superseded as a, Reopening as b, Unavailable as c, Closed as d, Down as f, Lost as g, Kept as h, Options as i, UseOptions as l, GenerationState as m, Lease as n, Supervisor as o, Draining as p, Opened as r, Supervisor_d_exports as s, Generation as t, make as u, Opening as v, Settled as x, Released as y };
+//# sourceMappingURL=Supervisor-CYWFK3vM.d.mts.map