@livestore/utils 0.4.0-dev.9 → 0.4.0

package/src/effect/WebChannel/WebChannel.ts

@@ -38,131 +38,10 @@ export const noopChannel = <MsgListen, MsgSend>(): Effect.Effect<WebChannel<MsgL
     }).pipe(Effect.withSpan(`WebChannel:noopChannel`)),
   )
 
-/** Only works in browser environments */
-export const broadcastChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
-  channelName,
-  schema: inputSchema,
-}: {
-  channelName: string
-  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
-}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
-  Effect.scopeWithCloseable((scope) =>
-    Effect.gen(function* () {
-      const schema = mapSchema(inputSchema)
-
-      const channel = new BroadcastChannel(channelName)
-
-      yield* Effect.addFinalizer(() => Effect.try(() => channel.close()).pipe(Effect.ignoreLogged))
-
-      const send = (message: MsgSend) =>
-        Effect.gen(function* () {
-          const messageEncoded = yield* Schema.encode(schema.send)(message)
-          channel.postMessage(messageEncoded)
-        })
-
-      // TODO also listen to `messageerror` in parallel
-      const listen = Stream.fromEventListener<MessageEvent>(channel, 'message').pipe(
-        Stream.map((_) => Schema.decodeEither(schema.listen)(_.data)),
-        listenToDebugPing(channelName),
-      )
-
-      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
-      const supportsTransferables = false
-
-      return {
-        [WebChannelSymbol]: WebChannelSymbol,
-        send,
-        listen,
-        closedDeferred,
-        shutdown: Scope.close(scope, Exit.succeed('shutdown')),
-        schema,
-        supportsTransferables,
-      }
-    }).pipe(Effect.withSpan(`WebChannel:broadcastChannel(${channelName})`)),
-  )
-
-/**
- * NOTE the `listenName` and `sendName` is needed for cases where both sides are using the same window
- * e.g. for a browser extension, so we need a way to know for which side a message is intended for.
- */
-export const windowChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>({
-  listenWindow,
-  sendWindow,
-  targetOrigin = '*',
-  ids,
-  schema: inputSchema,
-}: {
-  listenWindow: Window
-  sendWindow: Window
-  targetOrigin?: string
-  ids: { own: string; other: string }
-  schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
-}): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
-  Effect.scopeWithCloseable((scope) =>
-    Effect.gen(function* () {
-      const schema = mapSchema(inputSchema)
-
-      const debugInfo = {
-        sendTotal: 0,
-        listenTotal: 0,
-        targetOrigin,
-        ids,
-      }
-
-      const WindowMessageListen = Schema.Struct({
-        message: schema.listen,
-        from: Schema.Literal(ids.other),
-        to: Schema.Literal(ids.own),
-      }).annotations({ title: 'webmesh.WindowMessageListen' })
-
-      const WindowMessageSend = Schema.Struct({
-        message: schema.send,
-        from: Schema.Literal(ids.own),
-        to: Schema.Literal(ids.other),
-      }).annotations({ title: 'webmesh.WindowMessageSend' })
-
-      const send = (message: MsgSend) =>
-        Effect.gen(function* () {
-          debugInfo.sendTotal++
-
-          const [messageEncoded, transferables] = yield* Schema.encodeWithTransferables(WindowMessageSend)({
-            message,
-            from: ids.own,
-            to: ids.other,
-          })
-          sendWindow.postMessage(messageEncoded, targetOrigin, transferables)
-        })
-
-      const listen = Stream.fromEventListener<MessageEvent>(listenWindow, 'message').pipe(
-        // Stream.tap((_) => Effect.log(`${ids.other}→${ids.own}:message`, _.data)),
-        Stream.filter((_) => Schema.is(Schema.encodedSchema(WindowMessageListen))(_.data)),
-        Stream.map((_) => {
-          debugInfo.listenTotal++
-          return Schema.decodeEither(schema.listen)(_.data.message)
-        }),
-        listenToDebugPing('window'),
-      )
-
-      const closedDeferred = yield* Deferred.make<void>().pipe(Effect.acquireRelease(Deferred.done(Exit.void)))
-      const supportsTransferables = true
-
-      return {
-        [WebChannelSymbol]: WebChannelSymbol,
-        send,
-        listen,
-        closedDeferred,
-        shutdown: Scope.close(scope, Exit.succeed('shutdown')),
-        schema,
-        supportsTransferables,
-        debugInfo,
-      }
-    }).pipe(Effect.withSpan(`WebChannel:windowChannel`)),
-  )
-
 export const messagePortChannel: <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(args: {
   port: MessagePort
   schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
-  debugId?: string | number
+  debugId?: string | number | undefined
 }) => Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> = ({ port, schema: inputSchema, debugId }) =>
   Effect.scopeWithCloseable((scope) =>
     Effect.gen(function* () {
@@ -225,10 +104,7 @@ export const sameThreadChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendE
 
       const schema = mapSchema(inputSchema)
 
-      const send = (message: MsgSend) =>
-        Effect.gen(function* () {
-          yield* PubSub.publish(pubSub, message)
-        })
+      const send = (message: MsgSend) => PubSub.publish(pubSub, message)
 
       const listen = Stream.fromPubSub(pubSub).pipe(Stream.map(Either.right), listenToDebugPing(channelName))
 
@@ -249,7 +125,7 @@ export const sameThreadChannel = <MsgListen, MsgSend, MsgListenEncoded, MsgSendE
 export const messagePortChannelWithAck: <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(args: {
   port: MessagePort
   schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>
-  debugId?: string | number
+  debugId?: string | number | undefined
 }) => Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> = ({ port, schema: inputSchema, debugId }) =>
   Effect.scopeWithCloseable((scope) =>
     Effect.gen(function* () {
@@ -315,7 +191,7 @@ export const messagePortChannelWithAck: <MsgListen, MsgSend, MsgListenEncoded, M
                 yield* Deferred.succeed(requestAckMap.get(msg.right.reqId)!, void 0)
               } else if (msg.right._tag === 'ChannelRequest') {
                 debugInfo.listenTotal++
-                port.postMessage(Schema.encodeSync(ChannelMessage)({ _tag: 'ChannelRequestAck', reqId: msg.right.id }))
+                port.postMessage(yield* Schema.encode(ChannelMessage)({ _tag: 'ChannelRequestAck', reqId: msg.right.id }))
               }
             }
           }),
@@ -408,8 +284,8 @@ export const queueChannelProxy = <MsgListen, MsgSend>({
 /**
  * Eagerly starts listening to a channel by buffering incoming messages in a queue.
  */
-export const toOpenChannel = (
-  channel: WebChannel<any, any>,
+export const toOpenChannel = <MsgListen, MsgSend>(
+  channel: WebChannel<MsgListen, MsgSend>,
   options?: {
     /**
      * Sends a heartbeat message to the other end of the channel every `interval`.
@@ -420,9 +296,14 @@ export const toOpenChannel = (
       timeout: DurationInput
     }
   },
-): Effect.Effect<WebChannel<any, any>, never, Scope.Scope> =>
+): Effect.Effect<WebChannel<MsgListen, MsgSend>, never, Scope.Scope> =>
   Effect.gen(function* () {
-    const queue = yield* Queue.unbounded<Either.Either<any, any>>().pipe(Effect.acquireRelease(Queue.shutdown))
+    const queue = yield* Queue.unbounded<Either.Either<MsgListen, any>>().pipe(Effect.acquireRelease(Queue.shutdown))
+
+    const heartbeatChannel = channel as WebChannel<
+      MsgListen | typeof WebChannelHeartbeat.Type,
+      MsgSend | typeof WebChannelHeartbeat.Type
+    >
 
     const pendingPingDeferredRef = {
       current: undefined as { deferred: Deferred.Deferred<void>; requestId: string } | undefined,
@@ -430,12 +311,12 @@ export const toOpenChannel = (
 
     yield* channel.listen.pipe(
       // TODO implement this on the "chunk" level for better performance
-      options?.heartbeat
+      options?.heartbeat !== undefined
         ? Stream.filterEffect(
             Effect.fn(function* (msg) {
-              if (msg._tag === 'Right' && Schema.is(WebChannelHeartbeat)(msg.right)) {
+              if (msg._tag === 'Right' && Schema.is(WebChannelHeartbeat)(msg.right) === true) {
                 if (msg.right._tag === 'WebChannel.Ping') {
-                  yield* channel.send(WebChannelPong.make({ requestId: msg.right.requestId }))
+                  yield* heartbeatChannel.send(WebChannelPong.make({ requestId: msg.right.requestId }))
                 } else {
                   const { deferred, requestId } = pendingPingDeferredRef.current ?? shouldNeverHappen('No pending ping')
                   if (requestId !== msg.right.requestId) {
@@ -455,13 +336,13 @@ export const toOpenChannel = (
       Effect.forkScoped,
     )
 
-    if (options?.heartbeat) {
+    if (options?.heartbeat !== undefined) {
       const { interval, timeout } = options.heartbeat
       yield* Effect.gen(function* () {
         while (true) {
           yield* Effect.sleep(interval)
           const requestId = crypto.randomUUID()
-          yield* channel.send(WebChannelPing.make({ requestId }))
+          yield* heartbeatChannel.send(WebChannelPing.make({ requestId }))
           const deferred = yield* Deferred.make<void>()
           pendingPingDeferredRef.current = { deferred, requestId }
           yield* deferred.pipe(
@@ -492,7 +373,4 @@ export const toOpenChannel = (
     }
   })
 
-export const sendDebugPing = (channel: WebChannel<any, any>) =>
-  Effect.gen(function* () {
-    yield* channel.send(DebugPingMessage.make({ message: 'ping' }))
-  })
+export const sendDebugPing = (channel: WebChannel<any, any>) => channel.send(DebugPingMessage.make({ message: 'ping' }))

package/src/effect/WebChannel/broadcastChannelWithAck.ts

@@ -69,7 +69,7 @@ export const broadcastChannelWithAck = <MsgListen, MsgSend, MsgListenEncoded, Ms
                 peerIdRef.current = data.from
                 postMessage(ConnectAckMessage.make({ from: connectionId, to: data.from }))
                 yield* connectedLatch.open
-                break
+                return undefined
               }
               // Case: other side sends connect-ack message (because otherside was already online when this side connected)
               case 'ConnectAckMessage': {
@@ -77,7 +77,7 @@ export const broadcastChannelWithAck = <MsgListen, MsgSend, MsgListenEncoded, Ms
                   peerIdRef.current = data.from
                   yield* connectedLatch.open
                 }
-                break
+                return undefined
               }
               case 'DisconnectMessage': {
                 if (data.from === peerIdRef.current) {
@@ -85,13 +85,13 @@ export const broadcastChannelWithAck = <MsgListen, MsgSend, MsgListenEncoded, Ms
                   yield* connectedLatch.close
                   yield* establishConnection
                 }
-                break
+                return undefined
               }
               case 'PayloadMessage': {
                 if (data.to === connectionId) {
                   return Schema.decodeEither(schema.listen)(data.payload)
                 }
-                break
+                return undefined
               }
             }
           }),

package/src/effect/WebChannel/common.ts

@@ -15,7 +15,7 @@ export interface WebChannel<MsgListen, MsgSend, E = never> {
   closedDeferred: Deferred.Deferred<void>
   shutdown: Effect.Effect<void>
   schema: { listen: Schema.Schema<MsgListen, any>; send: Schema.Schema<MsgSend, any> }
-  debugInfo?: Record<string, any>
+  debugInfo?: Record<string, any> | undefined
 }
 
 export const DebugPingMessage = Schema.TaggedStruct('WebChannel.DebugPing', {
@@ -54,19 +54,19 @@ export type OutputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> =
 export const mapSchema = <MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>(
   schema: InputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded>,
 ): OutputSchema<MsgListen, MsgSend, MsgListenEncoded, MsgSendEncoded> =>
-  Predicate.hasProperty(schema, 'send') && Predicate.hasProperty(schema, 'listen')
+  Predicate.hasProperty(schema, 'send') === true && Predicate.hasProperty(schema, 'listen') === true
     ? (schemaWithWebChannelMessages(schema) as any)
     : (schemaWithWebChannelMessages({ send: schema, listen: schema }) as any)
 
 export const listenToDebugPing =
   (channelName: string) =>
   <MsgListen>(
-    stream: Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>, never>,
-  ): Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>, never> =>
+    stream: Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>>,
+  ): Stream.Stream<Either.Either<MsgListen, ParseResult.ParseError>> =>
     stream.pipe(
       Stream.filterEffect(
         Effect.fn(function* (msg) {
-          if (msg._tag === 'Right' && Schema.is(DebugPingMessage)(msg.right)) {
+          if (msg._tag === 'Right' && Schema.is(DebugPingMessage)(msg.right) === true) {
             yield* Effect.logDebug(`WebChannel:ping [${channelName}] ${msg.right.message}`, msg.right.payload)
             return false
           }

package/src/effect/WebSocket.ts

@@ -2,7 +2,7 @@ import { HttpClient } from '@effect/platform'
 import type { Schedule, Scope } from 'effect'
 import { Effect, Exit, identity, Schema } from 'effect'
 
-export class WebSocketError extends Schema.TaggedError<WebSocketError>()('WebSocketError', {
+export class WebSocketError extends Schema.TaggedError<WebSocketError>('~@livestore/utils/WebSocketError')('WebSocketError', {
   cause: Schema.Defect,
 }) {}
 
@@ -63,7 +63,7 @@ export const makeWebSocket = ({
       }
     }).pipe(
       Effect.tapErrorTag('WebSocketError', () => tryLogWebsocketConnectError(url)),
-      reconnect ? Effect.retry(reconnect) : identity,
+      reconnect !== undefined ? Effect.retry(reconnect) : identity,
     )
 
     /**
@@ -81,16 +81,17 @@ export const makeWebSocket = ({
      */
     yield* Effect.addFinalizer(
       Effect.fn(function* (exit) {
-        try {
-          if (Exit.isFailure(exit)) {
-            socket.close(3000)
-          } else {
-            socket.close(1000)
-          }
-        } catch (error) {
-          return yield* Effect.die(new WebSocketError({ cause: error }))
-        }
-      }),
+        yield* Effect.try({
+          try: () => {
+            if (Exit.isFailure(exit) === true) {
+              socket.close(3000)
+            } else {
+              socket.close(1000)
+            }
+          },
+          catch: (error) => new WebSocketError({ cause: error }),
+        })
+      }, Effect.orDie),
     )
 
     return socket

package/src/effect/{index.ts → mod.ts}

@@ -48,7 +48,6 @@ export {
   WorkerError,
   WorkerRunner,
 } from '@effect/platform'
-export { BrowserWorker, BrowserWorkerRunner } from '@effect/platform-browser'
 export {
   Rpc,
   // RpcClient, // TODO bring back "original" RpcClient from effect/rpc
@@ -72,6 +71,7 @@ export {
   Chunk,
   Config,
   ConfigError,
+  ConfigProvider,
   Console,
   Context,
   Data,
@@ -108,6 +108,7 @@ export {
   MutableHashMap,
   MutableHashSet,
   Option,
+  Order,
   ParseResult,
   Predicate,
   Pretty,
@@ -116,15 +117,21 @@ export {
   // Subscribable,
   pipe,
   Queue,
+  RcMap,
+  RcRef,
   Record as ReadonlyRecord,
+  Redacted,
   Ref,
   Request,
   Runtime,
   RuntimeFlags,
   Scope,
+  ScopedRef,
+  Sink,
   SortedMap,
   STM,
   SynchronizedRef,
+  TestClock,
   TestServices,
   TQueue,
   TRef,
@@ -133,10 +140,12 @@ export {
 } from 'effect'
 export type { NonEmptyArray } from 'effect/Array'
 export { constVoid, dual } from 'effect/Function'
+export * as Graph from 'effect/Graph'
 export { TreeFormatter } from 'effect/ParseResult'
 export type { Serializable, SerializableWithResult } from 'effect/Schema'
 export * as SchemaAST from 'effect/SchemaAST'
 export * as BucketQueue from './BucketQueue.ts'
+export * as Debug from './Debug.ts'
 export * as Effect from './Effect.ts'
 export * from './Error.ts'
 export * as Logger from './Logger.ts'
@@ -151,5 +160,4 @@ export * as Subscribable from './Subscribable.ts'
 export * as SubscriptionRef from './SubscriptionRef.ts'
 export * as TaskTracing from './TaskTracing.ts'
 export * as WebChannel from './WebChannel/mod.ts'
-export * as WebLock from './WebLock.ts'
 export * as WebSocket from './WebSocket.ts'

package/src/effect/spanEvent.test.ts

@@ -0,0 +1,95 @@
+import { it, describe, expect } from '@effect/vitest'
+import { Effect, Tracer } from 'effect'
+
+import { spanEvent } from './spanEvent.ts'
+
+type RecordedEvent = { name: string; attributes: Record<string, unknown> | undefined }
+
+/**
+ * Creates a test tracer that captures span events for assertion,
+ * using only the public `Tracer` API (no internal NativeSpan access).
+ * Each span records its own events, retrievable by span name.
+ */
+const makeTestTracer = () => {
+  const spanEvents = new Map<string, Array<RecordedEvent>>()
+
+  const tracer = Tracer.make({
+    span(name, parent, context, links, startTime, kind) {
+      const events: Array<RecordedEvent> = []
+      spanEvents.set(name, events)
+      const attributes = new Map<string, unknown>()
+      return {
+        _tag: 'Span' as const,
+        name,
+        spanId: `test-${name}`,
+        traceId: 'test-trace',
+        parent,
+        context,
+        status: { _tag: 'Started' as const, startTime },
+        attributes,
+        links: [...links],
+        sampled: true,
+        kind,
+        end() {},
+        attribute(key: string, value: unknown) {
+          attributes.set(key, value)
+        },
+        event(eventName: string, _startTime: bigint, attrs?: Record<string, unknown>) {
+          events.push({ name: eventName, attributes: attrs })
+        },
+        addLinks() {},
+      }
+    },
+    context(f) {
+      return f()
+    },
+  })
+
+  return {
+    tracer,
+    getEvents: (spanName: string): Array<RecordedEvent> => spanEvents.get(spanName) ?? [],
+  }
+}
+
+describe('spanEvent', () => {
+  it.effect('should emit a span event with the given message', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('test-event')
+      const events = getEvents('test-span')
+      expect(events).toHaveLength(1)
+      expect(events[0]!.name).toBe('test-event')
+    }).pipe(Effect.withSpan('test-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should emit a span event with attributes', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('event-with-attrs', { key1: 'value1', key2: 42 })
+      const events = getEvents('test-span')
+      expect(events).toHaveLength(1)
+      expect(events[0]!.name).toBe('event-with-attrs')
+      expect(events[0]!.attributes).toMatchObject({ key1: 'value1', key2: 42 })
+    }).pipe(Effect.withSpan('test-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should emit to the nearest enclosing span', () => {
+    const { tracer, getEvents } = makeTestTracer()
+    return Effect.gen(function* () {
+      yield* spanEvent('outer-event')
+
+      yield* spanEvent('inner-event').pipe(Effect.withSpan('inner-span'))
+
+      const outerEvents = getEvents('outer-span')
+      const innerEvents = getEvents('inner-span')
+
+      expect(outerEvents).toHaveLength(1)
+      expect(outerEvents[0]!.name).toBe('outer-event')
+
+      expect(innerEvents).toHaveLength(1)
+      expect(innerEvents[0]!.name).toBe('inner-event')
+    }).pipe(Effect.withSpan('outer-span'), Effect.withTracer(tracer))
+  })
+
+  it.effect('should be a no-op when no span is in context', () => spanEvent('orphan-event'))
+})

package/src/effect/spanEvent.ts

@@ -0,0 +1,15 @@
+import { Effect, FiberRef, HashSet, Logger } from 'effect'
+
+/**
+ * Emits a span event on the current Effect span via the tracer logger.
+ *
+ * @remarks
+ *
+ * Unlike raw `otelSpan.addEvent`, this doesn't require manual span threading —
+ * it automatically targets the nearest enclosing `Effect.withSpan`. If no span
+ * is in context, the call is a no-op.
+ */
+export const spanEvent = (message: any, attributes?: Record<string, unknown>) =>
+  Effect.locallyWith(Effect.log(message).pipe(Effect.annotateLogs(attributes ?? {})), FiberRef.currentLoggers, () =>
+    HashSet.make(Logger.tracerLogger),
+  )

package/src/env.ts

@@ -26,4 +26,5 @@ export const IS_CI = envTruish(env('CI'))
 
 export const IS_BUN = typeof Bun !== 'undefined'
 
-export const IS_REACT_NATIVE = typeof navigator !== 'undefined' && navigator.product === 'ReactNative'
+export const IS_REACT_NATIVE =
+  typeof navigator !== 'undefined' && (navigator as unknown as Record<string, unknown>)['product'] === 'ReactNative'

package/src/fast-deep-equal.ts

@@ -4,36 +4,36 @@
 export const deepEqual = <T>(a: T, b: T): boolean => {
   if (a === b) return true
 
-  if (a && b && typeof a === 'object' && typeof b === 'object') {
+  if (a != null && b != null && typeof a === 'object' && typeof b === 'object') {
     if (a.constructor !== b.constructor) return false
 
     let length: number
     let i: any
     let keys: any
-    if (Array.isArray(a)) {
+    if (Array.isArray(a) === true) {
       length = a.length
       // @ts-expect-error ...
       if (length !== b.length) return false
       for (i = length; i-- !== 0; )
         // @ts-expect-error ...
-        if (!deepEqual(a[i], b[i])) return false
+        if (deepEqual(a[i], b[i]) === false) return false
       return true
     }
 
     if (a instanceof Map && b instanceof Map) {
       if (a.size !== b.size) return false
-      for (i of a.entries()) if (!b.has(i[0])) return false
-      for (i of a.entries()) if (!deepEqual(i[1], b.get(i[0]))) return false
+      for (i of a.entries()) if (b.has(i[0]) === false) return false
+      for (i of a.entries()) if (deepEqual(i[1], b.get(i[0])) === false) return false
       return true
     }
 
     if (a instanceof Set && b instanceof Set) {
       if (a.size !== b.size) return false
-      for (i of a.entries()) if (!b.has(i[0])) return false
+      for (i of a.entries()) if (b.has(i[0]) === false) return false
       return true
     }
 
-    if (ArrayBuffer.isView(a) && ArrayBuffer.isView(b)) {
+    if (ArrayBuffer.isView(a) === true && ArrayBuffer.isView(b) === true) {
       // @ts-expect-error ...
       length = a.length
       // @ts-expect-error ...
@@ -53,13 +53,13 @@ export const deepEqual = <T>(a: T, b: T): boolean => {
     length = keys.length
     if (length !== Object.keys(b).length) return false
 
-    for (i = length; i-- !== 0; ) if (!Object.hasOwn(b, keys[i])) return false
+    for (i = length; i-- !== 0; ) if (Object.prototype.hasOwnProperty.call(b, keys[i]) === false) return false
 
     for (i = length; i-- !== 0; ) {
       const key = keys[i]
 
       // @ts-expect-error ...
-      if (!deepEqual(a[key], b[key])) return false
+      if (deepEqual(a[key], b[key]) === false) return false
     }
 
     return true

package/src/global.ts

@@ -1,6 +1,8 @@
 declare global {
   export type TODO<_Reason extends string = 'unknown'> = any
   export type UNUSED<_Reason extends string = 'unknown'> = any
-}
 
-export {}
+  interface ImportMeta {
+    main: boolean
+  }
+}

package/src/guards.ts

@@ -1,8 +1,23 @@
+/** Type guard that narrows `T | undefined` to `T`. Useful for filtering arrays. */
 export const isNotUndefined = <T>(_: T | undefined): _ is T => _ !== undefined
 
+/** Type guard that narrows `T | null` to `T`. */
 export const isNotNull = <T>(_: T | null): _ is T => _ !== null
+
+/** Type guard that checks if a value is `undefined`. */
 export const isUndefined = <T>(_: T | undefined): _ is undefined => _ === undefined
 
+/** Type guard that checks if a value is `null` or `undefined`. */
 export const isNil = (val: any): val is null | undefined => val === null || val === undefined
 
+/**
+ * Type guard that narrows `T | undefined | null` to `T`.
+ * Commonly used to filter out nullish values from arrays.
+ *
+ * @example
+ * ```ts
+ * const values = [1, null, 2, undefined, 3]
+ * const nonNil = values.filter(isNotNil) // [1, 2, 3] (type: number[])
+ * ```
+ */
 export const isNotNil = <T>(val: T | undefined | null): val is T => val !== null && val !== undefined

package/src/misc.ts

@@ -10,7 +10,7 @@ export const isDevEnv = () => {
   }
 
   // @ts-expect-error Only exists in Expo / RN
-  if (globalThis?.__DEV__) {
+  if (globalThis?.__DEV__ === true) {
     return true
   }
 
@@ -46,10 +46,18 @@ export const tryAsFunctionAndNew = <TArg, TResult>(
 export const envTruish = (env: string | undefined) =>
   env !== undefined && env.toLowerCase() !== 'false' && env.toLowerCase() !== '0'
 
-export const shouldNeverHappen = (msg?: string, ...args: any[]): never => {
+/**
+ * Logs and throws for impossible states, pausing at a breakpoint in development.
+ *
+ * @param msg - The error message to log and pass to the error.
+ * @param args - Arbitrary arguments to include in the log.
+ *
+ * @see {@link dieDebugger} for the Effect equivalent.
+ */
+export const shouldNeverHappen = (msg?: string, ...args: ReadonlyArray<unknown>): never => {
   console.error(msg, ...args)
-  if (isDevEnv()) {
-    // biome-ignore lint/suspicious/noDebugger: debugging
+  if (isDevEnv() === true) {
+    // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint during development
     debugger
   }