@livestore/utils 0.4.0-dev.20 → 0.4.0-dev.22

package/src/effect/Schema/debug-diff.test.ts

@@ -75,8 +75,8 @@ describe('debug-diff', () => {
 
   test('tagged union', () => {
     const schema = Schema.Union(
-      Schema.Struct({ _tag: Schema.Literal('a'), a: Schema.String }),
-      Schema.Struct({ _tag: Schema.Literal('b'), b: Schema.Number }),
+      Schema.TaggedStruct('a', { a: Schema.String }),
+      Schema.TaggedStruct('b', { b: Schema.Number }),
     )
     const a = { _tag: 'a', a: 'hello' } as const
     const b = { _tag: 'b', b: 1 } as const

package/src/effect/mod.ts

@@ -117,7 +117,10 @@ export {
   // Subscribable,
   pipe,
   Queue,
+  RcMap,
+  RcRef,
   Record as ReadonlyRecord,
+  Redacted,
   Ref,
   Request,
   Runtime,

package/src/global.ts

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

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/mod.ts

@@ -19,37 +19,102 @@ import type { Types } from 'effect'
 
 import { objectToString } from './misc.ts'
 
+/**
+ * Recursively expands type aliases for better IDE hover display.
+ *
+ * Transforms `{ a: string } & { b: number }` into `{ a: string; b: number }`.
+ */
 export type Prettify<T> = T extends infer U ? { [K in keyof U]: Prettify<U[K]> } : never
 
+/**
+ * Type-level equality check. Returns `true` if `A` and `B` are exactly the same type.
+ *
+ * @example
+ * ```ts
+ * type Test1 = TypeEq<string, string> // true
+ * type Test2 = TypeEq<string, number> // false
+ * type Test3 = TypeEq<{ a: 1 }, { a: 1 }> // true
+ * ```
+ */
 export type TypeEq<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false
 
-/** `A` is subtype of `B` */
+/**
+ * Type-level subtype check. Returns `true` if `A` extends `B`.
+ *
+ * @example
+ * ```ts
+ * type Test1 = IsSubtype<'foo', string> // true
+ * type Test2 = IsSubtype<string, 'foo'> // false
+ * ```
+ */
 export type IsSubtype<A, B> = A extends B ? true : false
+
+/** Compile-time assertion that `T` is `true`. Useful for type tests. */
 export type AssertTrue<T extends true> = T
 
+/** Removes `readonly` modifier from all properties of `T`. */
 export type Writeable<T> = { -readonly [P in keyof T]: T[P] }
+
+/** Recursively removes `readonly` modifier from all properties. */
 export type DeepWriteable<T> = { -readonly [P in keyof T]: DeepWriteable<T[P]> }
 
+/** Makes all properties of `T` nullable (allows `null`). */
 export type Nullable<T> = { [K in keyof T]: T[K] | null }
 
+/** Union of JavaScript primitive types. */
 export type Primitive = null | undefined | string | number | boolean | symbol | bigint
 
+/**
+ * Creates a union type that allows specific literals while still accepting the base type.
+ * Useful for string/number enums with autocomplete support.
+ *
+ * @example
+ * ```ts
+ * type Status = LiteralUnion<'pending' | 'active', string>
+ * // Allows 'pending', 'active', or any other string
+ * ```
+ */
 export type LiteralUnion<LiteralType, BaseType extends Primitive> = LiteralType | (BaseType & Record<never, never>)
 
+/** Extracts the value type for key `K` from object type `T`, or `never` if key doesn't exist. */
 export type GetValForKey<T, K> = K extends keyof T ? T[K] : never
 
+/** Accepts either a single value or a readonly array of values. */
 export type SingleOrReadonlyArray<T> = T | ReadonlyArray<T>
 
+/** Returns a Promise that resolves after `ms` milliseconds. */
 export const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
 
+/**
+ * Creates a mutable reference object with a `current` property.
+ * Similar to React's `useRef` but works outside of React.
+ *
+ * @example
+ * ```ts
+ * const counter = ref(0)
+ * counter.current += 1
+ * ```
+ */
 export const ref = <T>(val: T): { current: T } => ({ current: val })
 
+/**
+ * Calls a function `n` times with the current index.
+ *
+ * @example
+ * ```ts
+ * times(3, (i) => console.log(i)) // logs 0, 1, 2
+ * ```
+ */
 export const times = (n: number, fn: (index: number) => {}): void => {
   for (let i = 0; i < n; i++) {
     fn(i)
   }
 }
 
+/**
+ * Wraps a function call in a try/catch that triggers the debugger on error.
+ * Useful for debugging exceptions during development.
+ */
 export const debugCatch = <T>(try_: () => T): T => {
   try {
     return try_()
@@ -60,6 +125,10 @@ export const debugCatch = <T>(try_: () => T): T => {
   }
 }
 
+/**
+ * Recursively removes `undefined` values from an object or array in place.
+ * Mutates the input value.
+ */
 export const recRemoveUndefinedValues = (val: any): void => {
   if (Array.isArray(val)) {
     val.forEach(recRemoveUndefinedValues)
@@ -79,13 +148,24 @@ export const recRemoveUndefinedValues = (val: any): void => {
  */
 export const sluggify = (str: string, separator = '-') => str.replace(/[^a-zA-Z0-9]/g, separator)
 
+/**
+ * Creates a property accessor function for use in pipelines.
+ *
+ * @example
+ * ```ts
+ * const users = [{ name: 'Alice' }, { name: 'Bob' }]
+ * const names = users.map(prop('name')) // ['Alice', 'Bob']
+ * ```
+ */
 export const prop =
   <T extends {}, K extends keyof T>(key: K) =>
   (obj: T): T[K] =>
     obj[key]
 
+/** Capitalizes the first letter of a string. */
 export const capitalizeFirstLetter = (str: string): string => str.charAt(0).toUpperCase() + str.slice(1)
 
+/** Type guard that checks if a value is a readonly array. */
 export const isReadonlyArray = <I, T>(value: ReadonlyArray<I> | T): value is ReadonlyArray<I> => Array.isArray(value)
 
 /**
@@ -99,6 +179,14 @@ export function casesHandled(unexpectedCase: never): never {
   throw new Error(`A case was not handled for value: ${truncate(objectToString(unexpectedCase), 1000)}`)
 }
 
+/**
+ * Throws if the condition is false. Use for runtime assertions that should never fail.
+ *
+ * @example
+ * ```ts
+ * assertNever(user !== undefined, 'User must be loaded')
+ * ```
+ */
 export const assertNever = (failIfFalse: boolean, msg?: string): void => {
   if (failIfFalse === false) {
     // biome-ignore lint/suspicious/noDebugger: debugging
@@ -107,6 +195,14 @@ export const assertNever = (failIfFalse: boolean, msg?: string): void => {
   }
 }
 
+/**
+ * Identity function that triggers the debugger. Useful for debugging pipelines.
+ *
+ * @example
+ * ```ts
+ * data.pipe(transform, debuggerPipe, format) // Pauses debugger here
+ * ```
+ */
 export const debuggerPipe = <T>(val: T): T => {
   // biome-ignore lint/suspicious/noDebugger: debugging
   debugger
@@ -121,16 +217,40 @@ const truncate = (str: string, length: number): string => {
   }
 }
 
+/**
+ * Placeholder for unimplemented code paths. Triggers debugger and throws.
+ *
+ * @example
+ * ```ts
+ * const parseFormat = (format: Format) => {
+ *   switch (format) {
+ *     case 'json': return parseJson
+ *     case 'xml': return notYetImplemented('XML parsing')
+ *   }
+ * }
+ * ```
+ */
 export const notYetImplemented = (msg?: string): never => {
   // biome-ignore lint/suspicious/noDebugger: debugging
   debugger
   throw new Error(`Not yet implemented: ${msg}`)
 }
 
+/** A function that does nothing. Useful as a default callback. */
 export const noop = () => {}
 
+/** A function that returns a value of type `T`. */
 export type Thunk<T> = () => T
 
+/**
+ * If the input is a function, calls it and returns the result. Otherwise returns the value directly.
+ *
+ * @example
+ * ```ts
+ * unwrapThunk(5) // 5
+ * unwrapThunk(() => 5) // 5
+ * ```
+ */
 export const unwrapThunk = <T>(_: T | (() => T)): T => {
   if (typeof _ === 'function') {
     return (_ as any)()
@@ -139,6 +259,10 @@ export const unwrapThunk = <T>(_: T | (() => T)): T => {
   }
 }
 
+/**
+ * Transforms nullable fields (those that include `null`) into optional fields.
+ * Useful for converting database schemas to TypeScript types.
+ */
 export type NullableFieldsToOptional<T> = Types.Simplify<
   Partial<T> & {
     [K in keyof T as null extends T[K] ? K : never]?: Exclude<T[K], null>
@@ -147,12 +271,33 @@ export type NullableFieldsToOptional<T> = Types.Simplify<
   }
 >
 
-/** `end` is not included */
+/**
+ * Creates an array of numbers from `start` (inclusive) to `end` (exclusive).
+ *
+ * @example
+ * ```ts
+ * range(0, 5) // [0, 1, 2, 3, 4]
+ * range(3, 7) // [3, 4, 5, 6]
+ * ```
+ */
 export const range = (start: number, end: number): number[] => {
   const length = end - start
   return Array.from({ length }, (_, i) => start + i)
 }
 
+/**
+ * Rate-limits function calls to at most once per `ms` milliseconds.
+ * Trailing calls are preserved—if called during the wait period, the function
+ * will be called again after the timeout.
+ *
+ * @example
+ * ```ts
+ * const throttledSave = throttle(() => saveData(), 1000)
+ * throttledSave() // Executes immediately
+ * throttledSave() // Queued, executes after 1 second
+ * throttledSave() // Ignored (already queued)
+ * ```
+ */
 export const throttle = (fn: () => void, ms: number) => {
   let shouldWait = false
   let shouldCallAgain = false
@@ -179,13 +324,26 @@ export const throttle = (fn: () => void, ms: number) => {
   }
 }
 
+/**
+ * Generates a W3C Trace Context `traceparent` header from an OpenTelemetry span.
+ * @see https://www.w3.org/TR/trace-context/#examples-of-http-traceparent-headers
+ */
 export const getTraceParentHeader = (parentSpan: otel.Span) => {
   const spanContext = parentSpan.spanContext()
-  // Format: {version}-{trace_id}-{span_id}-{trace_flags}
-  // https://www.w3.org/TR/trace-context/#examples-of-http-traceparent-headers
   return `00-${spanContext.traceId}-${spanContext.spanId}-01`
 }
 
+/**
+ * Asserts that a tagged union value has a specific tag, narrowing its type.
+ * Throws if the tag doesn't match.
+ *
+ * @example
+ * ```ts
+ * type Result = { _tag: 'ok'; value: number } | { _tag: 'error'; message: string }
+ * const result: Result = ...
+ * const ok = assertTag(result, 'ok') // Type is { _tag: 'ok'; value: number }
+ * ```
+ */
 export const assertTag = <TObj extends { _tag: string }, TTag extends TObj['_tag']>(
   obj: TObj,
   tag: TTag,
@@ -197,6 +355,20 @@ export const assertTag = <TObj extends { _tag: string }, TTag extends TObj['_tag
   return obj as any
 }
 
+/**
+ * Memoizes a function by JSON-stringifying its arguments as the cache key.
+ * Suitable for functions with serializable arguments.
+ *
+ * @example
+ * ```ts
+ * const expensiveCalc = memoizeByStringifyArgs((a: number, b: number) => {
+ *   console.log('Computing...')
+ *   return a + b
+ * })
+ * expensiveCalc(1, 2) // logs 'Computing...', returns 3
+ * expensiveCalc(1, 2) // returns 3 (cached, no log)
+ * ```
+ */
 export const memoizeByStringifyArgs = <T extends (...args: any[]) => any>(fn: T): T => {
   const cache = new Map<string, ReturnType<T>>()
 
@@ -212,6 +384,18 @@ export const memoizeByStringifyArgs = <T extends (...args: any[]) => any>(fn: T)
   }) as any
 }
 
+/**
+ * Memoizes a single-argument function using reference equality for cache lookup.
+ * Suitable for functions where arguments are objects that should be compared by reference.
+ *
+ * @example
+ * ```ts
+ * const processUser = memoizeByRef((user: User) => expensiveTransform(user))
+ * processUser(userA) // Computes
+ * processUser(userA) // Returns cached (same reference)
+ * processUser(userB) // Computes (different reference)
+ * ```
+ */
 export const memoizeByRef = <T extends (arg: any) => any>(fn: T): T => {
   const cache = new Map<Parameters<T>[0], ReturnType<T>>()
 
@@ -226,15 +410,23 @@ export const memoizeByRef = <T extends (arg: any) => any>(fn: T): T => {
   }) as any
 }
 
+/** Type guard that checks if a value is a non-empty string. */
 export const isNonEmptyString = (str: string | undefined | null): str is string => {
   return typeof str === 'string' && str.length > 0
 }
 
+/** Type guard that checks if a value is a Promise (has a `then` method). */
 export const isPromise = (value: any): value is Promise<unknown> => typeof value?.then === 'function'
 
+/** Type guard that checks if a value is iterable (has a `Symbol.iterator` method). */
 export const isIterable = <T>(value: any): value is Iterable<T> => typeof value?.[Symbol.iterator] === 'function'
 
-/** This utility "lies" as a means of compat with libs that don't explicitly type optionals as unioned with `undefined`. */
+/**
+ * Type-level utility that removes `undefined` from all property types.
+ * Used for compatibility with libraries that don't type optionals as `| undefined`.
+ *
+ * Note: This is a type-level lie—the runtime value is unchanged.
+ */
 export const omitUndefineds = <T extends Record<keyof any, unknown>>(
   rec: T,
 ): {

package/src/node/mod.ts

@@ -1,5 +1,4 @@
 import * as http from 'node:http'
-import * as PlatformNode from '@effect/platform-node'
 import { layer as ParcelWatcherLayer } from '@effect/platform-node/NodeFileSystem/ParcelWatcher'
 import { Effect, Layer } from 'effect'
 import { OtelTracer, UnknownError } from '../effect/mod.ts'
@@ -53,8 +52,39 @@ export const OtelLiveDummy: Layer.Layer<OtelTracer.OtelTracer> = Layer.suspend((
 })
 
 /**
- * Layer that enables recursive file watching by combining the Node filesystem implementation with
- * the Parcel-based watch backend. Mirrored from Effect’s platform-node Parcel watcher layer:
- * https://github.com/Effect-TS/effect/blob/main/packages/platform-node/src/NodeFileSystem/ParcelWatcher.ts
+ * Layer that provides WatchBackend for recursive file watching via @parcel/watcher.
+ * This layer alone does NOT provide FileSystem - it only provides the watch backend.
+ *
+ * IMPORTANT: Layer ordering matters! When composing with NodeFileSystem.layer, use
+ * `NodeFileSystemWithWatch` instead, or ensure WatchBackend is available when FileSystem
+ * is constructed by using `Layer.provideMerge`:
+ *
+ * ```ts
+ * // ✅ CORRECT: Use the pre-composed layer
+ * Effect.provide(NodeFileSystemWithWatch)
+ *
+ * // ✅ CORRECT: Manual composition with Layer.provideMerge
+ * const layer = PlatformNode.NodeFileSystem.layer.pipe(Layer.provideMerge(NodeRecursiveWatchLayer))
+ * Effect.provide(layer)
+ *
+ * // ❌ WRONG: Chained Effect.provide - WatchBackend won't be used!
+ * Effect.provide(NodeRecursiveWatchLayer).pipe(Effect.provide(PlatformNode.NodeFileSystem.layer))
+ * ```
+ *
+ * @see https://github.com/Effect-TS/effect/issues/5913
  */
-export const NodeRecursiveWatchLayer = Layer.mergeAll(PlatformNode.NodeFileSystem.layer, ParcelWatcherLayer)
+export const NodeRecursiveWatchLayer = ParcelWatcherLayer
+
+/**
+ * Pre-composed layer providing FileSystem with recursive file watching via @parcel/watcher.
+ * This is the recommended way to get a FileSystem that supports recursive watching.
+ *
+ * Use this layer when you need to watch files recursively (e.g., watching nested directories).
+ * Without recursive watching, Node.js's built-in fs.watch only detects changes in the
+ * immediate directory, not in subdirectories.
+ */
+export { NodeFileSystem } from '@effect/platform-node'
+
+import { NodeFileSystem } from '@effect/platform-node'
+
+export const NodeFileSystemWithWatch = NodeFileSystem.layer.pipe(Layer.provideMerge(ParcelWatcherLayer))