effect 4.0.7 → 4.1.0

package/src/internal/matcher.ts

@@ -511,6 +511,23 @@ export const tags = discriminators("_tag")
 /** @internal */
 export const tagsExhaustive = discriminatorsExhaustive("_tag")
 
+/** @internal */
+export const literals = (fields: object) => {
+  const predicate = makeWhen(
+    (arg: any) =>
+      (typeof arg === "string" || typeof arg === "number") && Object.hasOwn(fields, arg) &&
+      (fields as any)[arg] !== undefined,
+    (data: any) => (fields as any)[data](data)
+  )
+  return (self: any): any => self.add(predicate)
+}
+
+/** @internal */
+export const literalsExhaustive = (fields: object) => {
+  const addCases = literals(fields)
+  return (matcher: any): any => exhaustive(addCases(matcher))
+}
+
 /** @internal */
 export const not = <
   R,

package/src/internal/persistence.ts

@@ -1,2 +1,13 @@
 /** @internal */
 export const sqlCleanupBatchSize = 1000
+
+/**
+ * Key prefix for a persistence store. The store id is escaped so the namespace
+ * always ends at its first `:`, and distinct store / key pairs never collide.
+ *
+ * @internal
+ */
+export const storeNamespace = (storeId: string): string => `${storeId.replace(/%/g, "%25").replace(/:/g, "%3A")}:`
+
+/** @internal */
+export const escapeRedisGlob = (pattern: string): string => pattern.replace(/[\\*?[\]]/g, "\\$&")

package/src/internal/rcRef.ts

@@ -225,7 +225,10 @@ const release = <A, E>(self: RcRefImpl<A, E>, state: State.Acquired<A>): Effect.
     Effect.flatMap(restore(Effect.sleep(idleTimeToLive)), () => {
       if (self.state === state && state.refCount === 0) {
         self.state = stateEmpty
-        return Scope.close(state.scope, Exit.void)
+        return Effect.ignoreCause(Scope.close(state.scope, Exit.void), {
+          log: "Unhandled",
+          message: "Unhandled error in RcRef finalizer"
+        })
       }
       return Effect.void
     })

package/src/internal/schema/toCodeDocument.ts

@@ -16,6 +16,10 @@ export function makeCode(runtime: string, Type: string): SchemaRepresentation.Co
   return { runtime, Type }
 }
 
+function formatObjectLiteralKey(key: PropertyKey, formatted = formatPropertyKey(key)): string {
+  return key === "__proto__" ? `[${formatted}]` : formatted
+}
+
 function renderEmittableAnnotation(input: unknown): string | undefined {
   if (
     input === null ||
@@ -43,7 +47,7 @@ function renderEmittableAnnotation(input: unknown): string | undefined {
   for (const [key, value] of Object.entries(input)) {
     const rendered = renderEmittableAnnotation(value)
     if (rendered === undefined) return undefined
-    entries.push(`${formatPropertyKey(key)}: ${rendered}`)
+    entries.push(`${formatObjectLiteralKey(key)}: ${rendered}`)
   }
   return entries.length === 0 ? "{}" : `{ ${entries.join(", ")} }`
 }
@@ -63,7 +67,7 @@ function renderAnnotations(
   for (const [key, value] of Object.entries(annotations)) {
     if (InternalAnnotations.annotationExcludedKeys.has(key)) continue
     const rendered = renderEmittableAnnotation(value)
-    if (rendered !== undefined) entries.push(`${formatPropertyKey(key)}: ${rendered}`)
+    if (rendered !== undefined) entries.push(`${formatObjectLiteralKey(key)}: ${rendered}`)
   }
   return entries.length === 0 ? undefined : `{ ${entries.join(", ")} }`
 }
@@ -499,7 +503,7 @@ export function toCodeDocument(
           if (property.isMutable) runtime = `Schema.mutableKey(${runtime})`
           if (property.isOptional) runtime = `Schema.optionalKey(${runtime})`
           runtime += runtimeAnnotate(property.annotations, "annotateKey")
-          const runtimeName = property.name === "__proto__" ? `[${name}]` : name
+          const runtimeName = formatObjectLiteralKey(property.name, name)
           const typeName = `${property.isMutable ? "" : "readonly "}${name}${property.isOptional ? "?" : ""}`
           return {
             code: makeCode(`${runtimeName}: ${runtime}`, `${typeName}: ${type.Type}`)

package/src/internal/trie.ts

@@ -21,6 +21,7 @@ type TraversalFilter<K, V> = (k: K, v: V) => boolean
 /** @internal */
 export interface TrieImpl<in out V> extends TR.Trie<V> {
   readonly _root: Node<V> | undefined
+  readonly _empty: Entry<V> | undefined
   readonly _count: number
 }
 
@@ -70,15 +71,17 @@ const TrieProto: TR.Trie<unknown> = {
   }
 }
 
-const makeImpl = <V>(root: Node<V> | undefined): TrieImpl<V> => {
+const makeImpl = <V>(root: Node<V> | undefined, emptyEntry: Entry<V> | undefined): TrieImpl<V> => {
   const trie = Object.create(TrieProto)
   trie._root = root
-  trie._count = root?.count ?? 0
+  trie._empty = emptyEntry
+  trie._count = (root?.count ?? 0) + (emptyEntry === undefined ? 0 : 1)
   return trie
 }
 
 class TrieIterator<in out V, out T> implements IterableIterator<T> {
   stack: Array<[Node<V>, string, boolean]> = []
+  emptyEntry: Entry<V> | undefined
   readonly f: TraversalMap<string, V, T>
   readonly filter: TraversalFilter<string, V>
 
@@ -89,6 +92,7 @@ class TrieIterator<in out V, out T> implements IterableIterator<T> {
   ) {
     this.f = f
     this.filter = filter
+    this.emptyEntry = trie._empty
     const root = trie._root !== undefined ? trie._root : undefined
     if (root !== undefined) {
       this.stack.push([root, "", false])
@@ -96,6 +100,13 @@ class TrieIterator<in out V, out T> implements IterableIterator<T> {
   }
 
   next(): IteratorResult<T> {
+    const emptyEntry = this.emptyEntry
+    if (emptyEntry !== undefined) {
+      this.emptyEntry = undefined
+      if (this.filter("", emptyEntry.value)) {
+        return { done: false, value: this.f("", emptyEntry.value) }
+      }
+    }
     while (this.stack.length > 0) {
       const [node, keyString, isAdded] = this.stack.pop()!
 
@@ -140,7 +151,7 @@ export const isTrie: {
 } = (u: unknown): u is TR.Trie<unknown> => hasProperty(u, TrieTypeId)
 
 /** @internal */
-export const empty = <V = never>(): TR.Trie<V> => makeImpl<V>(undefined)
+export const empty = <V = never>(): TR.Trie<V> => makeImpl<V>(undefined, undefined)
 
 /** @internal */
 export const fromIterable = <V>(entries: Iterable<readonly [string, V]>) => {
@@ -163,7 +174,7 @@ export const insert = dual<
   <V>(key: string, value: V) => (self: TR.Trie<V>) => TR.Trie<V>,
   <V>(self: TR.Trie<V>, key: string, value: V) => TR.Trie<V>
 >(3, <V>(self: TR.Trie<V>, key: string, value: V) => {
-  if (key.length === 0) return self
+  if (key.length === 0) return makeImpl((self as TrieImpl<V>)._root, { value })
 
   // -1:left | 0:mid | 1:right
   const dStack: Array<Ordering.Ordering> = []
@@ -255,11 +266,11 @@ export const insert = dual<
   }
 
   nStack[0].count = count
-  return makeImpl(nStack[0])
+  return makeImpl(nStack[0], (self as TrieImpl<V>)._empty)
 })
 
 /** @internal */
-export const size = <V>(self: TR.Trie<V>): number => (self as TrieImpl<V>)._root?.count ?? 0
+export const size = <V>(self: TR.Trie<V>): number => (self as TrieImpl<V>)._count
 
 /** @internal */
 export const isEmpty = <V>(self: TR.Trie<V>): boolean => size(self) === 0
@@ -394,8 +405,12 @@ export const get = dual<
 >(
   2,
   <V>(self: TR.Trie<V>, key: string) => {
+    if (key.length === 0) {
+      const emptyEntry = (self as TrieImpl<V>)._empty
+      return emptyEntry === undefined ? Option.none() : Option.some(emptyEntry.value)
+    }
     let n: Node<V> | undefined = (self as TrieImpl<V>)._root
-    if (n === undefined || key.length === 0) return Option.none()
+    if (n === undefined) return Option.none()
     let cIndex = 0
     while (cIndex < key.length) {
       const c = key[cIndex]
@@ -453,8 +468,11 @@ export const remove = dual<
 >(
   2,
   <V>(self: TR.Trie<V>, key: string) => {
+    if (key.length === 0) {
+      return (self as TrieImpl<V>)._empty === undefined ? self : makeImpl((self as TrieImpl<V>)._root, undefined)
+    }
     let n: Node<V> | undefined = (self as TrieImpl<V>)._root
-    if (n === undefined || key.length === 0) return self
+    if (n === undefined) return self
 
     const count = n.count - 1
     // -1:left | 0:mid | 1:right
@@ -554,7 +572,7 @@ export const remove = dual<
     }
 
     nStack[0].count = count
-    return makeImpl(nStack[0])
+    return makeImpl(nStack[0], (self as TrieImpl<V>)._empty)
   }
 )
 
@@ -589,8 +607,12 @@ export const modify = dual<
 >(
   3,
   <V>(self: TR.Trie<V>, key: string, f: (v: V) => V): TR.Trie<V> => {
+    if (key.length === 0) {
+      const emptyEntry = (self as TrieImpl<V>)._empty
+      return emptyEntry === undefined ? self : makeImpl((self as TrieImpl<V>)._root, { value: f(emptyEntry.value) })
+    }
     let n: Node<V> | undefined = (self as TrieImpl<V>)._root
-    if (n === undefined || key.length === 0) return self
+    if (n === undefined) return self
 
     // -1:left | 0:mid | 1:right
     const dStack: Array<Ordering.Ordering> = []
@@ -689,7 +711,7 @@ export const modify = dual<
       }
     }
 
-    return makeImpl(nStack[0])
+    return makeImpl(nStack[0], (self as TrieImpl<V>)._empty)
   }
 )
 
@@ -700,9 +722,12 @@ export const longestPrefixOf = dual<
 >(
   2,
   <V>(self: TR.Trie<V>, key: string): Option.Option<[string, V]> => {
+    const emptyEntry = (self as TrieImpl<V>)._empty
+    let longestPrefixNode: Option.Option<[string, V]> = emptyEntry === undefined
+      ? Option.none()
+      : Option.some(["", emptyEntry.value])
     let n: Node<V> | undefined = (self as TrieImpl<V>)._root
-    if (n === undefined || key.length === 0) return Option.none()
-    let longestPrefixNode: Option.Option<[string, V]> = Option.none()
+    if (n === undefined || key.length === 0) return longestPrefixNode
     let cIndex = 0
     while (cIndex < key.length) {
       const c = key[cIndex]
@@ -735,10 +760,14 @@ export const longestPrefixOf = dual<
   }
 )
 
+interface Entry<V> {
+  readonly value: V
+}
+
 interface Node<V> {
   key: string
   count: number
-  value?: { readonly value: V } | undefined
+  value?: Entry<V> | undefined
   left?: Node<V> | undefined
   mid?: Node<V> | undefined
   right?: Node<V> | undefined

package/src/internal/ulid.ts

@@ -28,3 +28,47 @@ export const ulidString = (timestampMillis: number, bytes: Uint8Array): string =
 
   return out
 }
+
+/**
+ * Makes a ULID generator in the ULID spec's monotonic mode: within a
+ * millisecond, or when the clock moves back, the 80-bit random part of the last
+ * ULID is incremented. The ordering ends at the maximum timestamp, 2^48 − 1 ms,
+ * which overflow cannot advance. `randomBytes` is only called for fresh
+ * randomness.
+ *
+ * @internal
+ */
+export const makeMonotonic = () => {
+  let lastTimestamp = -1
+  const random = new Uint8Array(10)
+  return (timestampMillis: number, randomBytes: () => Uint8Array): string => {
+    const timestamp = timestampMillis >= 0 ? Math.min(Math.trunc(timestampMillis), maxTimestamp) : 0
+    if (timestamp > lastTimestamp) {
+      lastTimestamp = timestamp
+      random.set(randomBytes())
+    } else if (!increment(random)) {
+      lastTimestamp = Math.min(lastTimestamp + 1, maxTimestamp)
+      random.set(randomBytes())
+    }
+    return ulidString(lastTimestamp, random)
+  }
+}
+
+// Returns false when the bytes overflow, leaving them all zero.
+const increment = (bytes: Uint8Array): boolean => {
+  for (let i = bytes.length - 1; i >= 0; i--) {
+    if (bytes[i] !== 0xff) {
+      bytes[i]++
+      return true
+    }
+    bytes[i] = 0
+  }
+  return false
+}
+
+/**
+ * The ULID ordering state shared by every `Date.now()` caller in the realm.
+ *
+ * @internal
+ */
+export const monotonic = makeMonotonic()

package/src/internal/uuid.ts

@@ -18,30 +18,20 @@ export const stringify = (bytes: Uint8Array): string => {
     hex[bytes[10]] + hex[bytes[11]] + hex[bytes[12]] + hex[bytes[13]] + hex[bytes[14]] + hex[bytes[15]]
 }
 
-const randomBytes = (): Uint8Array<ArrayBuffer> => globalThis.crypto.getRandomValues(new Uint8Array(16))
-
-/** @internal */
-export function v4Bytes(): Uint8Array<ArrayBuffer>
-/** @internal */
-export function v4Bytes<A extends ArrayBufferLike>(bytes: Uint8Array<A>): Uint8Array<A>
 /** @internal */
-export function v4Bytes(bytes: Uint8Array = randomBytes()): Uint8Array {
+export const v4Bytes = <A extends ArrayBufferLike>(bytes: Uint8Array<A>): Uint8Array<A> => {
   bytes[6] = (bytes[6] & 0x0f) | 0x40
   bytes[8] = (bytes[8] & 0x3f) | 0x80
   return bytes
 }
 
 /** @internal */
-export const v4String = (bytes?: Uint8Array): string => stringify(bytes === undefined ? v4Bytes() : v4Bytes(bytes))
+export const v4String = (bytes: Uint8Array): string => stringify(v4Bytes(bytes))
 
 const maxV7Timestamp = 2 ** 48 - 1
 
 /** @internal */
-export function v7Bytes(timestampMillis: number): Uint8Array<ArrayBuffer>
-/** @internal */
-export function v7Bytes<A extends ArrayBufferLike>(timestampMillis: number, bytes: Uint8Array<A>): Uint8Array<A>
-/** @internal */
-export function v7Bytes(timestampMillis: number, bytes: Uint8Array = randomBytes()): Uint8Array {
+export const v7Bytes = <A extends ArrayBufferLike>(timestampMillis: number, bytes: Uint8Array<A>): Uint8Array<A> => {
   const timestamp = Math.min(Math.max(0, Math.trunc(timestampMillis)), maxV7Timestamp)
 
   bytes[0] = Math.floor(timestamp / 2 ** 40)
@@ -55,6 +45,57 @@ export function v7Bytes(timestampMillis: number, bytes: Uint8Array = randomBytes
   return bytes
 }
 
-/** @internal */
-export const v7String = (timestampMillis: number, bytes?: Uint8Array): string =>
-  stringify(bytes === undefined ? v7Bytes(timestampMillis) : v7Bytes(timestampMillis, bytes))
+const clampV7Timestamp = (timestampMillis: number): number =>
+  timestampMillis >= 0 ? Math.min(Math.trunc(timestampMillis), maxV7Timestamp) : 0
+
+const maxV7Counter = 2 ** 42 - 1
+
+/**
+ * Makes a UUIDv7 generator that orders the UUIDs it returns, following RFC
+ * 9562 §6.2 Method 1. A 42-bit counter fills the 12 bits of `rand_a` and the
+ * top 30 bits of `rand_b`; the last 32 bits stay random. The ordering ends at
+ * the maximum timestamp, 2^48 − 1 ms, which counter overflow cannot advance.
+ *
+ * @internal
+ */
+export const makeV7Monotonic = () => {
+  let lastTimestamp = -1
+  let counter = 0
+  return <A extends ArrayBufferLike>(timestampMillis: number, bytes: Uint8Array<A>): Uint8Array<A> => {
+    const timestamp = clampV7Timestamp(timestampMillis)
+    if (timestamp > lastTimestamp) {
+      lastTimestamp = timestamp
+      counter = seedV7Counter(bytes)
+    } else if (counter < maxV7Counter) {
+      // The clock stalled or moved back, so keep the last timestamp.
+      counter++
+    } else {
+      lastTimestamp = Math.min(lastTimestamp + 1, maxV7Timestamp)
+      counter = seedV7Counter(bytes)
+    }
+    v7Bytes(lastTimestamp, bytes)
+    const high = Math.floor(counter / 2 ** 30)
+    const low = counter - high * 2 ** 30
+    bytes[6] = 0x70 | (high >>> 8)
+    bytes[7] = high & 0xff
+    bytes[8] = 0x80 | (low >>> 24)
+    bytes[9] = (low >>> 16) & 0xff
+    bytes[10] = (low >>> 8) & 0xff
+    bytes[11] = low & 0xff
+    return bytes
+  }
+}
+
+// Clears the counter's top bit, so a millisecond has at least 2^41 increments
+// before it overflows.
+const seedV7Counter = (bytes: Uint8Array): number =>
+  (((bytes[6] & 0x07) << 8) | bytes[7]) * 2 ** 30 +
+  (((bytes[8] & 0x3f) << 24) | (bytes[9] << 16) | (bytes[10] << 8) | bytes[11])
+
+/**
+ * The UUIDv7 ordering state shared by every `Date.now()` or `Clock` caller in
+ * the realm that has no `SecureRandom` instance of its own.
+ *
+ * @internal
+ */
+export const v7Monotonic = makeV7Monotonic()

package/src/internal/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = "4.0.7"
+export const version = "4.1.0"

package/src/observability/Otlp.ts

@@ -16,6 +16,7 @@ import type * as HttpClient from "../http/HttpClient.ts"
 import * as HttpClientRequest from "../http/HttpClientRequest.ts"
 import * as Layer from "../Layer.ts"
 import type * as Tracer from "../Tracer.ts"
+import type * as OtlpExporter from "./OtlpExporter.ts"
 import * as OtlpLogger from "./OtlpLogger.ts"
 import type { AggregationTemporality } from "./OtlpMetrics.ts"
 import * as OtlpMetrics from "./OtlpMetrics.ts"
@@ -30,6 +31,10 @@ import * as OtlpTracer from "./OtlpTracer.ts"
  * The layer sends data to `/v1/logs`, `/v1/metrics`, and `/v1/traces` below
  * `baseUrl` and requires an `OtlpSerialization` implementation.
  *
+ * The layer provides the `OtlpExporter.Flusher` shared by all three signals,
+ * so one `flush` exports their buffered telemetry, for example before a
+ * serverless instance is suspended.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -56,7 +61,7 @@ export const layer = (options: {
   readonly metricsTemporality?: AggregationTemporality | undefined
   readonly tracerExportInterval?: Duration.Input | undefined
   readonly shutdownTimeout?: Duration.Input | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization.OtlpSerialization> => {
+}): Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization.OtlpSerialization> => {
   const base = HttpClientRequest.get(options.baseUrl)
   const url = (path: string) => HttpClientRequest.appendUrl(base, path).url
   return Layer.mergeAll(
@@ -97,6 +102,12 @@ export const layer = (options: {
  * Creates a combined OTLP layer for logs, metrics, and traces from
  * OpenTelemetry configuration.
  *
+ * **Details**
+ *
+ * The layer provides the `OtlpExporter.Flusher` shared by all enabled signals.
+ * It is provided even when configuration disables every signal, in which case
+ * `flush` is a no-op.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -111,7 +122,7 @@ export const layerFromConfig = (options?: {
   readonly tracerContext?: (<X>(primitive: Tracer.EffectPrimitive<X>, span: Tracer.AnySpan) => X) | undefined
   readonly loggerExcludeLogSpans?: boolean | undefined
   readonly loggerMergeWithExisting?: boolean | undefined
-}): Layer.Layer<never, never, HttpClient.HttpClient | OtlpSerialization.OtlpSerialization> =>
+}): Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient | OtlpSerialization.OtlpSerialization> =>
   Layer.mergeAll(
     OtlpLogger.layerFromConfig({
       resource: options?.resource,
@@ -160,7 +171,10 @@ export const layerJson: (options: {
   readonly metricsTemporality?: AggregationTemporality | undefined
   readonly tracerExportInterval?: Duration.Input | undefined
   readonly shutdownTimeout?: Duration.Input | undefined
-}) => Layer.Layer<never, never, HttpClient.HttpClient> = flow(layer, Layer.provide(OtlpSerialization.layerJson))
+}) => Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient> = flow(
+  layer,
+  Layer.provide(OtlpSerialization.layerJson)
+)
 
 /**
  * Creates the combined OTLP logs, metrics, and traces layer using protobuf
@@ -192,4 +206,7 @@ export const layerProtobuf: (options: {
   readonly metricsTemporality?: AggregationTemporality | undefined
   readonly tracerExportInterval?: Duration.Input | undefined
   readonly shutdownTimeout?: Duration.Input | undefined
-}) => Layer.Layer<never, never, HttpClient.HttpClient> = flow(layer, Layer.provide(OtlpSerialization.layerProtobuf))
+}) => Layer.Layer<OtlpExporter.Flusher, never, HttpClient.HttpClient> = flow(
+  layer,
+  Layer.provide(OtlpSerialization.layerProtobuf)
+)

package/src/observability/OtlpResource.ts

@@ -79,6 +79,13 @@ export const make = (options: {
  * precedence over matching attributes in `OTEL_RESOURCE_ATTRIBUTES`. Missing
  * required configuration is converted to a defect.
  *
+ * Keys and values in `OTEL_RESOURCE_ATTRIBUTES` are trimmed, then
+ * percent-decoded. Entries with an empty value are kept as `""`; entries
+ * without `=` or with an empty key are skipped. When a key is repeated as
+ * written, the last entry wins and the earlier ones are not decoded. Invalid
+ * percent-encoding in the remaining entries is a `ConfigError` and is
+ * converted to a defect.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -97,7 +104,8 @@ export const fromConfig: (
   const env = yield* Config.Record(
     Schema.StringFromUriComponent,
     Schema.StringFromUriComponent,
-    "OTEL_RESOURCE_ATTRIBUTES"
+    "OTEL_RESOURCE_ATTRIBUTES",
+    { trim: true, keepEmptyValues: true }
   ).pipe(Config.withDefault(undefined))
 
   const serviceName = options?.serviceName