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

package/dist/mod.js

@@ -14,13 +14,36 @@ export * from "./set.js";
 export * from "./string.js";
 export * from "./time.js";
 import { objectToString } from "./misc.js";
+/** Returns a Promise that resolves after `ms` milliseconds. */
 export const sleep = (ms) => 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 = (val) => ({ 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, fn) => {
     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 = (try_) => {
     try {
         return try_();
@@ -31,6 +54,10 @@ export const debugCatch = (try_) => {
         throw e;
     }
 };
+/**
+ * Recursively removes `undefined` values from an object or array in place.
+ * Mutates the input value.
+ */
 export const recRemoveUndefinedValues = (val) => {
     if (Array.isArray(val)) {
         val.forEach(recRemoveUndefinedValues);
@@ -50,8 +77,19 @@ export const recRemoveUndefinedValues = (val) => {
  * Replace non-alphanumeric characters with a dash.
  */
 export const sluggify = (str, 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 = (key) => (obj) => obj[key];
+/** Capitalizes the first letter of a string. */
 export const capitalizeFirstLetter = (str) => str.charAt(0).toUpperCase() + str.slice(1);
+/** Type guard that checks if a value is a readonly array. */
 export const isReadonlyArray = (value) => Array.isArray(value);
 /**
  * Use this to make assertion at end of if-else chain that all members of a
@@ -62,6 +100,14 @@ export function casesHandled(unexpectedCase) {
     debugger;
     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, msg) => {
     if (failIfFalse === false) {
         // biome-ignore lint/suspicious/noDebugger: debugging
@@ -69,6 +115,14 @@ export const assertNever = (failIfFalse, msg) => {
         throw new Error(`This should never happen: ${msg}`);
     }
 };
+/**
+ * Identity function that triggers the debugger. Useful for debugging pipelines.
+ *
+ * @example
+ * ```ts
+ * data.pipe(transform, debuggerPipe, format) // Pauses debugger here
+ * ```
+ */
 export const debuggerPipe = (val) => {
     // biome-ignore lint/suspicious/noDebugger: debugging
     debugger;
@@ -82,12 +136,35 @@ const truncate = (str, length) => {
         return str;
     }
 };
+/**
+ * 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) => {
     // 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 = () => { };
+/**
+ * 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 = (_) => {
     if (typeof _ === 'function') {
         return _();
@@ -96,11 +173,32 @@ export const unwrapThunk = (_) => {
         return _;
     }
 };
-/** `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, end) => {
     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, ms) => {
     let shouldWait = false;
     let shouldCallAgain = false;
@@ -124,18 +222,45 @@ export const throttle = (fn, ms) => {
         setTimeout(timeoutFunc, ms);
     };
 };
+/**
+ * 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) => {
     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 = (obj, tag) => {
     if (obj._tag !== tag) {
         throw new Error(`Expected tag ${tag} but got ${obj._tag}`);
     }
     return obj;
 };
+/**
+ * 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 = (fn) => {
     const cache = new Map();
     return ((...args) => {
@@ -148,6 +273,18 @@ export const memoizeByStringifyArgs = (fn) => {
         return result;
     });
 };
+/**
+ * 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 = (fn) => {
     const cache = new Map();
     return ((arg) => {
@@ -159,12 +296,20 @@ export const memoizeByRef = (fn) => {
         return result;
     });
 };
+/** Type guard that checks if a value is a non-empty string. */
 export const isNonEmptyString = (str) => {
     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) => typeof value?.then === 'function';
+/** Type guard that checks if a value is iterable (has a `Symbol.iterator` method). */
 export const isIterable = (value) => 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 = (rec) => {
     return rec;
 };

package/dist/mod.js.map

@@ -1 +1 @@
-{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/utils",
-  "version": "0.4.0-dev.20",
+  "version": "0.4.0-dev.21",
   "type": "module",
   "sideEffects": [
     "./src/global.ts",
@@ -50,29 +50,29 @@
     "qrcode-generator": "2.0.4"
   },
   "devDependencies": {
-    "@effect/ai": "^0.29.0",
-    "@effect/cli": "^0.71.0",
-    "@effect/cluster": "^0.50.6",
-    "@effect/experimental": "^0.56.0",
+    "@effect/ai": "0.29.0",
+    "@effect/cli": "0.71.0",
+    "@effect/cluster": "0.50.6",
+    "@effect/experimental": "0.56.0",
     "@effect/opentelemetry": "0.58.0",
-    "@effect/platform": "^0.92.1",
-    "@effect/platform-browser": "^0.72.0",
-    "@effect/platform-bun": "^0.81.1",
-    "@effect/platform-node": "^0.98.4",
-    "@effect/printer": "^0.46.0",
-    "@effect/printer-ansi": "^0.46.0",
-    "@effect/rpc": "^0.71.1",
-    "@effect/sql": "^0.46.0",
-    "@effect/typeclass": "^0.37.0",
-    "@effect/vitest": "^0.26.0",
-    "@effect/workflow": "^0.11.5",
+    "@effect/platform": "0.92.1",
+    "@effect/platform-browser": "0.72.0",
+    "@effect/platform-bun": "0.81.1",
+    "@effect/platform-node": "0.98.4",
+    "@effect/printer": "0.46.0",
+    "@effect/printer-ansi": "0.46.0",
+    "@effect/rpc": "0.71.1",
+    "@effect/sql": "0.46.0",
+    "@effect/typeclass": "0.37.0",
+    "@effect/vitest": "0.26.0",
+    "@effect/workflow": "0.11.5",
     "@opentelemetry/api": "1.9.0",
     "@opentelemetry/resources": "2.0.1",
-    "@types/bun": "^1.2.21",
+    "@types/bun": "1.2.21",
     "@types/jsdom": "^21.1.7",
     "@types/node": "24.10.1",
-    "@types/web": "^0.0.264",
-    "effect": "3.18.4",
+    "@types/web": "0.0.264",
+    "effect": "3.19.9",
     "jsdom": "^26.1.0",
     "vitest": "3.2.4"
   },
@@ -99,7 +99,7 @@
     "@effect/typeclass": "^0.37.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/resources": "^2.0.1",
-    "effect": "^3.18.4"
+    "effect": "^3.19.9"
   },
   "publishConfig": {
     "access": "public"

package/src/NoopTracer.ts

@@ -21,7 +21,10 @@ export const makeNoopSpan = () => {
       ;(span as any)._duration = [durationSecs, durationRestNs]
     },
     spanContext: () => {
-      return { traceId: 'livestore-noop-trace-id', spanId: 'livestore-noop-span-id' }
+      return {
+        traceId: `livestore-noop-trace-id${crypto.randomUUID()}`,
+        spanId: `livestore-noop-span-id${crypto.randomUUID()}`,
+      }
     },
     _duration: [0, 0],
   } as unknown as otel.Span

package/src/browser/Opfs/utils.ts

@@ -210,6 +210,9 @@ export const getMetadata = Effect.fn('@livestore/utils:Opfs.getMetadata')(functi
  *
  * @param path - Slash-delimited file path.
  * @param data - Bytes to persist.
+ *
+ * @remarks
+ * - Only available in Safari 26 or higher (as of Dec 2025, not yet widely available).
  */
 export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function* (path: string, data: Uint8Array) {
   if (isRootPath(path)) {
@@ -234,10 +237,10 @@ export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function*
 })
 
 /**
- * Synchronously write bytes to the target file handle, truncating any existing content.
+ * Synchronously write bytes to an OPFS path, creating or replacing the target file.
  *
- * @param handle - Sync access handle to overwrite.
- * @param buffer - Raw data to persist.
+ * @param path - Slash-delimited file path.
+ * @param data - Bytes to persist.
  * @returns Effect that resolves once every byte is flushed to durable storage.
  *
  * @remarks
@@ -246,25 +249,38 @@ export const writeFile = Effect.fn('@livestore/utils:Opfs.writeFile')(function*
  *   For atomic replacement, prefer `writeFile` or a temp-file pattern with two prepared handles.
  */
 export const syncWriteFile = Effect.fn('@livestore/utils:Opfs.syncWriteFile')(function* (
-  handle: FileSystemSyncAccessHandle,
-  buffer: AllowSharedBufferSource,
+  path: string,
+  data: Uint8Array,
 ) {
-  const bytes = ArrayBuffer.isView(buffer)
-    ? new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength)
-    : new Uint8Array(buffer as ArrayBufferLike)
+  if (isRootPath(path)) {
+    return yield* new OpfsError({
+      message: `Invalid OPFS path '${path}': cannot write file directly to the OPFS root`,
+    })
+  }
 
-  yield* Opfs.syncTruncate(handle, 0)
+  const pathSegments = yield* parsePathSegments(path)
+  const { parentSegments, leafSegment: fileName } = splitPathSegments(pathSegments)
 
-  let offset = 0
-  while (offset < bytes.byteLength) {
-    const wrote = yield* Opfs.syncWrite(handle, bytes.subarray(offset), { at: offset })
-    if (wrote === 0) {
-      return yield* new OpfsError({
-        message: `Short write: wrote ${offset} of ${bytes.byteLength} bytes.`,
-      })
-    }
-    offset += Number(wrote)
-  }
+  return yield* Effect.scoped(
+    Effect.gen(function* () {
+      const parentDirHandle = yield* traverseDirectoryPath(parentSegments)
+      const fileHandle = yield* Opfs.getFileHandle(parentDirHandle, fileName, { create: true })
+      const syncHandle = yield* Opfs.createSyncAccessHandle(fileHandle)
+
+      yield* Opfs.syncTruncate(syncHandle, 0)
+
+      let offset = 0
+      while (offset < data.byteLength) {
+        const wrote = yield* Opfs.syncWrite(syncHandle, data.subarray(offset), { at: offset })
+        if (wrote === 0) {
+          return yield* new OpfsError({
+            message: `Short write: wrote ${offset} of ${data.byteLength} bytes.`,
+          })
+        }
+        offset += Number(wrote)
+      }
 
-  yield* Opfs.syncFlush(handle)
+      yield* Opfs.syncFlush(syncHandle)
+    }),
+  )
 })