effect 4.0.1 → 4.0.3

package/src/observability/internal/otlpProtobuf.ts

@@ -493,6 +493,62 @@ export const encodeHistogram = (histogram: {
     Proto.varintField(2, histogram.aggregationTemporality)
   )
 
+/**
+ * Encodes a SummaryDataPoint message.
+ *
+ * message SummaryDataPoint {
+ *   repeated KeyValue attributes = 7;
+ *   fixed64 start_time_unix_nano = 2;
+ *   fixed64 time_unix_nano = 3;
+ *   fixed64 count = 4;
+ *   double sum = 5;
+ *   repeated ValueAtQuantile quantile_values = 6;
+ *   uint32 flags = 8;
+ * }
+ *
+ * message ValueAtQuantile {
+ *   double quantile = 1;
+ *   double value = 2;
+ * }
+ *
+ * @internal
+ */
+export const encodeSummaryDataPoint = (point: {
+  readonly attributes: ReadonlyArray<KeyValue>
+  readonly startTimeUnixNano: string
+  readonly timeUnixNano: string
+  readonly count: string | number | bigint
+  readonly sum: number
+  readonly quantileValues: ReadonlyArray<{ readonly quantile: number; readonly value: number }>
+  readonly flags?: number | undefined
+}): Uint8Array =>
+  Proto.concat(
+    Proto.fixed64Field(2, BigInt(point.startTimeUnixNano)),
+    Proto.fixed64Field(3, BigInt(point.timeUnixNano)),
+    Proto.fixed64Field(4, BigInt(point.count)),
+    Proto.doubleField(5, point.sum),
+    Proto.repeatedField(
+      6,
+      point.quantileValues,
+      (q) => Proto.concat(Proto.doubleField(1, q.quantile), Proto.doubleField(2, q.value))
+    ),
+    Proto.repeatedField(7, point.attributes, encodeKeyValue),
+    point.flags !== undefined ? Proto.varintField(8, point.flags) : new Uint8Array(0)
+  )
+
+/**
+ * Encodes a Summary message.
+ *
+ * message Summary {
+ *   repeated SummaryDataPoint data_points = 1;
+ * }
+ *
+ * @internal
+ */
+export const encodeSummary = (summary: {
+  readonly dataPoints: ReadonlyArray<Parameters<typeof encodeSummaryDataPoint>[0]>
+}): Uint8Array => Proto.repeatedField(1, summary.dataPoints, encodeSummaryDataPoint)
+
 /**
  * Encodes a Metric message.
  *
@@ -518,6 +574,7 @@ export const encodeMetric = (metric: {
   readonly gauge?: Parameters<typeof encodeGauge>[0] | undefined
   readonly sum?: Parameters<typeof encodeSum>[0] | undefined
   readonly histogram?: Parameters<typeof encodeHistogram>[0] | undefined
+  readonly summary?: Parameters<typeof encodeSummary>[0] | undefined
 }): Uint8Array =>
   Proto.concat(
     Proto.stringField(1, metric.name),
@@ -531,6 +588,9 @@ export const encodeMetric = (metric: {
       : new Uint8Array(0),
     metric.histogram !== undefined
       ? Proto.messageField(9, encodeHistogram(metric.histogram))
+      : new Uint8Array(0),
+    metric.summary !== undefined
+      ? Proto.messageField(11, encodeSummary(metric.summary))
       : new Uint8Array(0)
   )
 

package/src/persistence/PersistedQueue.ts

@@ -34,6 +34,7 @@ import * as Scope from "../Scope.ts"
 import * as Migrator from "../sql/Migrator.ts"
 import * as SqlClient from "../sql/SqlClient.ts"
 import type { SqlError } from "../sql/SqlError.ts"
+import type { Fragment } from "../sql/Statement.ts"
 import * as Redis from "./Redis.ts"
 
 /**
@@ -80,11 +81,27 @@ export interface PersistedQueue<in out A, out R = never> {
    * **Details**
    *
    * If an element with the same id already exists in the queue, it will not be
-   * added again. De-duplication survives completion until the id is removed by
+   * added again, and the `delay` of the duplicate offer is ignored.
+   * De-duplication survives completion until the id is removed by
    * `layerCleanup`.
+   *
+   * `delay` postpones the first delivery. Measured by the store's clock, the
+   * element is never delivered before the delay elapses, and is typically
+   * delivered within the store's `pollInterval` after. The SQL store uses the
+   * database clock and rounds delays up to whole seconds. The Redis store
+   * compares the offering process's clock with the polling worker's, so it
+   * relies on those clocks agreeing.
+   * Retries still use the queue's `retrySchedule`, and the delay does not
+   * count an attempt. A zero, negative or omitted delay enqueues the element
+   * immediately.
+   *
+   * An infinite delay does nothing: the id is returned, but nothing is stored
+   * and no de-duplication record is written, so the same id can be offered
+   * again later.
    */
   readonly offer: (value: A, options?: {
-    readonly id: string | undefined
+    readonly id?: string | undefined
+    readonly delay?: Duration.Input | undefined
   }) => Effect.Effect<string, PersistedQueueError | Schema.SchemaError, R>
 
   /**
@@ -232,21 +249,27 @@ export const makeFactory = Effect.gen(function*() {
       return Effect.succeed<PersistedQueue<S["Type"], S["EncodingServices"] | S["DecodingServices"]>>({
         [TypeId]: TypeId,
         offer: (value, opts) =>
-          Effect.flatMap(
-            encodeUnknown(value),
-            (element) => {
-              const id = opts?.id ?? crypto.randomUUID()
-              return Effect.as(
-                store.offer({
-                  name: options.name,
-                  id,
-                  element,
-                  isCustomId: opts?.id !== undefined
-                }),
-                id
-              )
+          Effect.suspend(() => {
+            const id = opts?.id ?? crypto.randomUUID()
+            const delay = positiveDelay(opts?.delay)
+            if (delay !== undefined && !Duration.isFinite(delay)) {
+              return Effect.succeed(id)
             }
-          ),
+            return Effect.flatMap(
+              encodeUnknown(value),
+              (element) =>
+                Effect.as(
+                  store.offer({
+                    name: options.name,
+                    id,
+                    element,
+                    isCustomId: opts?.id !== undefined,
+                    delay
+                  }),
+                  id
+                )
+            )
+          }),
         take: <XA, XE, XR>(
           f: (value: S["Type"], metadata: {
             readonly id: string
@@ -430,6 +453,13 @@ class DeadLetter {
 const isDeadLetter = (u: unknown): u is DeadLetter =>
   Predicate.isTagged(u, "~effect/persistence/PersistedQueue/DeadLetter")
 
+// stores only see a positive delay, so a zero or negative one is dropped here
+const positiveDelay = (input: Duration.Input | undefined): Duration.Duration | undefined => {
+  if (input === undefined) return undefined
+  const delay = Duration.fromInputUnsafe(input)
+  return Duration.isPositive(delay) ? delay : undefined
+}
+
 const deadLetterFromCause = (cause: Cause.Cause<unknown>): DeadLetter | undefined => {
   for (const reason of cause.reasons) {
     if (Cause.isFailReason(reason) && isDeadLetter(reason.error)) {
@@ -452,6 +482,9 @@ const deadLetterFromCause = (cause: Cause.Cause<unknown>): DeadLetter | undefine
  * The store persists offered elements and returns taken elements in a scope so
  * the finalizer can complete or retry them based on the processing exit.
  *
+ * An offered `delay` is always finite and positive, and the element must not
+ * be taken before it elapses. It is `undefined` for immediate elements.
+ *
  * Claiming an element counts an attempt, so the `attempts` returned by `take`
  * is 1-based. When the take scope closes with a success the element is marked
  * completed; a failure retries it according to `retryDelay` or marks it failed
@@ -471,6 +504,7 @@ export class PersistedQueueStore extends Context.Service<
         readonly id: string
         readonly element: unknown
         readonly isCustomId: boolean
+        readonly delay?: Duration.Duration | undefined
       }
     ) => Effect.Effect<void, PersistedQueueError>
 
@@ -509,6 +543,9 @@ export class PersistedQueueStore extends Context.Service<
  * queue's retry schedule until the configured maximum attempts is reached,
  * after which the element is marked as failed.
  *
+ * Delayed elements are scanned on every take loop, so the store is meant for
+ * development and tests rather than large delayed backlogs.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -558,7 +595,7 @@ export const layerStoreMemory: Layer.Layer<
             element: options.element,
             attempts: 0,
             state: "pending",
-            visibleAt: now,
+            visibleAt: options.delay === undefined ? now : now + Duration.toMillis(options.delay),
             stateChangedAt: now
           }
           queue.entries.set(options.id, entry)
@@ -655,7 +692,9 @@ export const layerStoreMemory: Layer.Layer<
  * The store uses Redis lists, hashes, and sorted sets with worker locks,
  * periodically refreshes locks while items are being processed, delays retried
  * items with the queue's retry schedule, and moves exhausted items to a failed
- * queue.
+ * queue. Delayed offers share the retry sorted set: they are scored with the
+ * offering process's clock and released by the polling worker's clock, so
+ * clock skew between hosts shifts their delivery.
  *
  * @stability unstable
  * @category constructors
@@ -716,6 +755,7 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
   const retry = redis.eval(retryRedis)
   const resetQueue = redis.eval(resetQueueRedis)
   const offer = redis.eval(offerRedis)
+  const offerDelayed = redis.eval(offerDelayedRedis)
   const take = redis.eval(takeRedis)
   const expireAll = redis.eval(expireAllRedis)
   const trimFailed = redis.eval(trimFailedRedis)
@@ -856,24 +896,33 @@ export const makeStoreRedis = Effect.fnUntraced(function*(
     })
 
   return PersistedQueueStore.of({
-    offer: ({ element, id, isCustomId, name }) => {
+    offer: ({ delay, element, id, isCustomId, name }) => {
       const keys = keysFor(name)
       const payload = JSON.stringify({ id, element })
-      return (isCustomId
-        ? offer(keys.queue, keys.ids, id, payload)
-        : redis.send("RPUSH", keys.queue, payload)).pipe(
-          Effect.mapError(({ cause }) =>
-            new PersistedQueueError({
-              message: "Failed to offer element to persisted queue",
-              cause
-            })
-          ),
-          Effect.tap(() =>
-            Effect.sync(() => {
-              queueStates.peek(name)?.nudge.openUnsafe()
-            })
-          )
+      const send = Effect.suspend(() => {
+        if (delay === undefined) {
+          return isCustomId
+            ? offer(keys.queue, keys.ids, id, payload)
+            : redis.send("RPUSH", keys.queue, payload)
+        }
+        const visibleAt = clock.currentTimeMillisUnsafe() + Duration.toMillis(delay)
+        return isCustomId
+          ? offerDelayed(keys.delayed, keys.ids, id, payload, visibleAt)
+          : redis.send("ZADD", keys.delayed, visibleAt.toString(), payload)
+      })
+      return send.pipe(
+        Effect.mapError(({ cause }) =>
+          new PersistedQueueError({
+            message: "Failed to offer element to persisted queue",
+            cause
+          })
+        ),
+        Effect.tap(() =>
+          Effect.sync(() => {
+            queueStates.peek(name)?.nudge.openUnsafe()
+          })
         )
+      )
     },
     take: (options) =>
       Effect.uninterruptibleMask((restore) => {
@@ -1009,6 +1058,25 @@ end
   }
 )
 
+const offerDelayedRedis = Redis.script(
+  (...args: [keyDelayed: string, keyIds: string, id: string, payload: string, visibleAt: number]) => args,
+  {
+    lua: `
+local key_delayed = KEYS[1]
+local key_ids = KEYS[2]
+local id = ARGV[1]
+local payload = ARGV[2]
+local visible_at = ARGV[3]
+
+local result = redis.call("ZADD", key_ids, "NX", "+inf", id)
+if result == 1 then
+  redis.call("ZADD", key_delayed, visible_at, payload)
+end
+`,
+    numberOfKeys: 2
+  }
+)
+
 const resetQueueRedis = Redis.script(
   (
     ...args: [
@@ -1296,6 +1364,9 @@ export const layerStoreRedis: (
  * per-worker locks, refreshes active locks while scoped takes are running, and
  * retries or completes rows according to the processing exit.
  *
+ * Offer and retry delays are measured with the database clock and rounded up
+ * to whole seconds.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -1360,34 +1431,46 @@ export const makeStoreSql: (
   }
   const secondsAgo = (seconds: number) => secondsOffset(-Math.max(Math.ceil(seconds), 0))
   const secondsFromNow = (seconds: number) => secondsOffset(Math.max(Math.ceil(seconds), 0))
+  // Deadline for a delayed offer, which must never land before the delay
+  // elapses. pg reads clock_timestamp() since NOW() is fixed at transaction
+  // start. mysql and sqlite clocks drop the fraction of the current second, so
+  // they get a whole extra second to cover it.
+  const delayedVisibleAt = (delay: Duration.Duration) => {
+    const seconds = Math.ceil(Duration.toSeconds(delay))
+    return sql.onDialectOrElse({
+      pg: () => sql`clock_timestamp() + INTERVAL '${sql.literal(seconds.toString())} seconds'`,
+      mssql: () => secondsOffset(seconds),
+      orElse: () => secondsOffset(seconds + 1)
+    })
+  }
   const expiresAt = secondsAgo(Duration.toSeconds(lockExpiration))
 
   const offer = sql.onDialectOrElse({
-    pg: () => (id: string, name: string, element: string) =>
+    pg: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
         ON CONFLICT (id, queue_name) DO NOTHING
       `,
-    mysql: () => (id: string, name: string, element: string) =>
+    mysql: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT IGNORE INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
       `,
-    mssql: () => (id: string, name: string, element: string) =>
+    mssql: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         MERGE ${tableNameSql} WITH (HOLDLOCK) AS target
         USING (SELECT ${id} AS id, ${name} AS queue_name) AS source
         ON target.id = source.id AND target.queue_name = source.queue_name
         WHEN NOT MATCHED THEN
           INSERT (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-          VALUES (source.id, source.queue_name, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow});
+          VALUES (source.id, source.queue_name, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow});
       `,
     // sqlite
-    orElse: () => (id: string, name: string, element: string) =>
+    orElse: () => (id: string, name: string, element: string, visibleAt: Fragment) =>
       sql`
         INSERT OR IGNORE INTO ${tableNameSql} (id, queue_name, element, state, attempts, visible_at, created_at, updated_at)
-        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${sqlNow}, ${sqlNow}, ${sqlNow})
+        VALUES (${id}, ${name}, ${element}, 'pending', 0, ${visibleAt}, ${sqlNow}, ${sqlNow})
       `
   })
 
@@ -1696,20 +1779,30 @@ export const makeStoreSql: (
     )
 
   return PersistedQueueStore.of({
-    offer: ({ element, id, name }) =>
-      Effect.catchCause(Effect.suspend(() => offer(id, name, JSON.stringify(element))), (cause) =>
-        Effect.fail(
-          new PersistedQueueError({
-            message: "Failed to offer element to persisted queue",
-            cause
-          })
-        )).pipe(
-          Effect.tap(() =>
-            Effect.sync(() => {
-              queueStates.peek(name)?.nudge.openUnsafe()
-            })
+    offer: ({ delay, element, id, name }) =>
+      Effect.catchCause(
+        Effect.suspend(() =>
+          offer(
+            id,
+            name,
+            JSON.stringify(element),
+            delay === undefined ? sqlNow : delayedVisibleAt(delay)
           )
         ),
+        (cause) =>
+          Effect.fail(
+            new PersistedQueueError({
+              message: "Failed to offer element to persisted queue",
+              cause
+            })
+          )
+      ).pipe(
+        Effect.tap(() =>
+          Effect.sync(() => {
+            queueStates.peek(name)?.nudge.openUnsafe()
+          })
+        )
+      ),
     take: (options) => {
       queueStates.get(options.name).maxAttempts = options.maxAttempts
       const loop: Effect.Effect<

package/src/reactivity/AsyncResult.ts

@@ -644,7 +644,7 @@ export const flatMap: {
    * @category combinators
    * @since 4.0.0
    */
-  <A, E, B, E2>(f: (a: A, prev: Success<A, E>) => AsyncResult<A, E2>): (self: AsyncResult<A, E>) => AsyncResult<B, E | E2>
+  <A, E, B, E2>(f: (a: A, prev: Success<A, E>) => AsyncResult<B, E2>): (self: AsyncResult<A, E>) => AsyncResult<B, E | E2>
   /**
    * Maps the success value of an `AsyncResult` and flattens the result.
    *

package/src/reactivity/Atom.ts

@@ -818,7 +818,7 @@ export interface AtomRuntime<R, ER = never> extends Atom<AsyncResult.AsyncResult
       | ((
         get: AtomContext
       ) => Effect.Effect<SubscriptionRef.SubscriptionRef<A>, E, Scope.Scope | R | AtomRegistry | Reactivity.Reactivity>)
-  ) => Writable<AsyncResult.AsyncResult<A, E>, A>
+  ) => Writable<AsyncResult.AsyncResult<A, E | ER>, A>
 }
 
 /**
@@ -2774,18 +2774,21 @@ export const batch: (f: () => void) => void = Registry.batch
 // -----------------------------------------------------------------------------
 
 /**
- * Creates a browser-only signal atom that increments when the document becomes visible.
+ * Creates a signal atom that increments when the document becomes visible.
  *
  * **Details**
  *
  * It listens for `visibilitychange` events on `window` and removes the listener
- * when the atom is disposed.
+ * when the atom is disposed. Without `window`, it stays at `0` and adds no listener.
  *
  * @stability unstable
  * @category constants
  * @since 4.0.0
  */
 export const windowFocusSignal: Atom<number> = readable((get) => {
+  if (typeof window === "undefined") {
+    return 0
+  }
   let count = 0
   function update() {
     if (document.visibilityState === "visible") {
@@ -2825,8 +2828,8 @@ export const makeRefreshOnSignal = <_>(signal: Atom<_>) => <A extends Atom<any>>
  *
  * **Details**
  *
- * This helper is browser-only because `windowFocusSignal` depends on `window` and
- * `document.visibilityState`.
+ * Without `window`, this helper does not trigger refreshes. Source atom updates
+ * are still forwarded.
  *
  * @stability unstable
  * @category combinators
@@ -2991,7 +2994,8 @@ function updateSearchParams() {
     }
   }
   searchParamState.updates.clear()
-  const newUrl = `${window.location.pathname}?${searchParams.toString()}`
+  const search = searchParams.toString()
+  const newUrl = `${window.location.pathname}${search.length > 0 ? `?${search}` : ""}${window.location.hash}`
   window.history.pushState({}, "", newUrl)
   searchParamState.updating = false
 }

package/src/reactivity/AtomHttpApi.ts

@@ -57,7 +57,7 @@ export interface AtomHttpApiClient<Self, Id extends string, Groups extends HttpA
       HttpApiGroup.Endpoints<Group>,
       EndpointIdentifier
     >,
-    const ResponseMode extends HttpApiEndpoint.ClientResponseMode = HttpApiEndpoint.ClientResponseMode
+    const ResponseMode extends HttpApiEndpoint.ClientResponseMode = "decoded-only"
   >(
     group: GroupIdentifier,
     endpoint: EndpointIdentifier,
@@ -353,9 +353,7 @@ type ResponseByMode<
   Endpoint extends HttpApiEndpoint.Constraint,
   ResponseMode extends HttpApiEndpoint.ClientResponseMode
 > = HttpApiClient.Client.Response<
-  Effect.Success<
-    ReturnType<HttpApiClient.Client.Method<Extract<Endpoint, HttpApiEndpoint.ConstraintRequest>, never, never>>
-  >,
+  HttpApiClient.SuccessType<Extract<Endpoint, HttpApiEndpoint.ConstraintRequest>["~Success"]>,
   ResponseMode
 >
 

package/src/reactivity/AtomRegistry.ts

@@ -71,11 +71,13 @@ export interface AtomRegistry {
   readonly scheduler: Scheduler
   readonly schedulerAsync: Scheduler
   readonly getNodes: () => ReadonlyMap<Atom.Atom<any> | string, Node<any>>
+  readonly ensureNode: <A>(atom: Atom.Atom<A>) => Node<A>
   readonly get: <A>(atom: Atom.Atom<A>) => A
   readonly mount: <A>(atom: Atom.Atom<A>) => () => void
   readonly refresh: <A>(atom: Atom.Atom<A>) => void
   readonly set: <R, W>(atom: Atom.Writable<R, W>, value: W) => void
   readonly setSerializable: (key: string, encoded: unknown) => void
+  readonly preloadedSerializable: Map<string, unknown>
   readonly modify: <R, W, A>(atom: Atom.Writable<R, W>, f: (_: R) => [returnValue: A, nextValue: W]) => A
   readonly update: <R, W>(atom: Atom.Writable<R, W>, f: (_: R) => W) => void
   readonly subscribe: <A>(atom: Atom.Atom<A>, f: (_: A) => void, options?: {
@@ -83,6 +85,7 @@ export interface AtomRegistry {
   }) => () => void
   readonly reset: () => void
   readonly dispose: () => void
+  scheduleNodeRemoval(node: Node<any>): void
   onNodeAdded?: ((node: Node<any>) => void) | undefined
   onNodeRemoved?: ((node: Node<any>) => void) | undefined
 }
@@ -102,10 +105,14 @@ export interface AtomRegistry {
 export interface Node<A> {
   readonly atom: Atom.Atom<A>
   readonly value: () => A
+  readonly valueOption: () => Option.Option<A>
+  readonly canBeRemoved: boolean
   parents: Set<Node<any>>
   children: Set<Node<any>>
   listeners: Set<() => void>
   currentState(): "uninitialized" | "stale" | "valid" | "removed"
+  setInitialValue(value: A): void
+  subscribe(listener: () => void): () => void
 }
 
 /**