@livestore/utils 0.4.0-dev.9 → 0.5.0-dev.0

package/src/mod.ts

@@ -1,67 +1,109 @@
 export { default as prettyBytes } from 'pretty-bytes'
 export * as base64 from './base64.ts'
 export * from './binary.ts'
-export * from './browser.ts'
 export * from './Deferred.ts'
 export * from './env.ts'
 export * from './fast-deep-equal.ts'
-export * from './guards.ts'
 export * from './misc.ts'
 export * from './NoopTracer.ts'
 export * from './object/index.ts'
 export * from './promise.ts'
+export * as QR from './qr.ts'
 export * from './set.ts'
 export * from './string.ts'
-export * from './time.ts'
 
 import type * as otel from '@opentelemetry/api'
 import type { Types } from 'effect'
 
 import { objectToString } from './misc.ts'
 
-export type Prettify<T> = T extends infer U ? { [K in keyof U]: Prettify<U[K]> } : never
-
-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
-export type AssertTrue<T extends true> = T
 
-export type Writeable<T> = { -readonly [P in keyof T]: T[P] }
-export type DeepWriteable<T> = { -readonly [P in keyof T]: DeepWriteable<T[P]> }
+/** Compile-time assertion that `T` is `true`. Useful for type tests. */
+export type AssertTrue<T extends true> = T
 
+/** 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_()
   } catch (e: any) {
-    // biome-ignore lint/suspicious/noDebugger: debugging
+    // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for debugging exceptions
     debugger
     throw e
   }
 }
 
+/**
+ * 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)) {
+  if (Array.isArray(val) === true) {
     val.forEach(recRemoveUndefinedValues)
   } else if (typeof val === 'object') {
     Object.keys(val).forEach((key) => {
@@ -79,36 +121,60 @@ 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)
 
-export const isReadonlyArray = <I, T>(value: ReadonlyArray<I> | T): value is ReadonlyArray<I> => Array.isArray(value)
-
 /**
  * Use this to make assertion at end of if-else chain that all members of a
  * union have been accounted for.
  */
 
-export function casesHandled(unexpectedCase: never): never {
-  // biome-ignore lint/suspicious/noDebugger: debugging
+export const casesHandled = (unexpectedCase: never): never => {
+  // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for unhandled cases
   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: boolean, msg?: string): void => {
   if (failIfFalse === false) {
-    // biome-ignore lint/suspicious/noDebugger: debugging
+    // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for impossible states
     debugger
     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 = <T>(val: T): T => {
-  // biome-ignore lint/suspicious/noDebugger: debugging
+  // oxlint-disable-next-line eslint(no-debugger) -- intentional: this function's purpose is to trigger debugger
   debugger
   return val
 }
@@ -121,16 +187,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
+  // oxlint-disable-next-line eslint(no-debugger) -- intentional breakpoint for unimplemented code paths
   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 +229,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,18 +241,39 @@ 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
 
   const timeoutFunc = () => {
-    if (shouldCallAgain) {
+    if (shouldCallAgain === true) {
       fn()
       shouldCallAgain = false
       setTimeout(timeoutFunc, ms)
@@ -168,7 +283,7 @@ export const throttle = (fn: () => void, ms: number) => {
   }
 
   return () => {
-    if (shouldWait) {
+    if (shouldWait === true) {
       shouldCallAgain = true
       return
     }
@@ -179,13 +294,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,12 +325,26 @@ 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>>()
 
   return ((...args: any[]) => {
     const key = JSON.stringify(args)
-    if (cache.has(key)) {
+    if (cache.has(key) === true) {
       return cache.get(key)
     }
 
@@ -212,11 +354,23 @@ 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>>()
 
   return ((arg: any) => {
-    if (cache.has(arg)) {
+    if (cache.has(arg) === true) {
       return cache.get(arg)
     }
 
@@ -226,15 +380,17 @@ 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
 }
 
-export const isPromise = (value: any): value is Promise<unknown> => typeof value?.then === 'function'
-
-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,23 +1,21 @@
 import * as http from 'node:http'
 
-import { Effect, Layer } from 'effect'
+import { NodeFileSystem } from '@effect/platform-node'
+import { Effect, FileSystem, Layer, Option } from 'effect'
 
-import { OtelTracer, UnknownError } from '../effect/index.ts'
+import { OtelTracer, Tracer, UnknownError } from '../effect/mod.ts'
 import { makeNoopTracer } from '../NoopTracer.ts'
 
-export * as Cli from '@effect/cli'
-export * as SocketServer from '@effect/platform/SocketServer'
+export * as Cli from 'effect/unstable/cli'
+export * as SocketServer from 'effect/unstable/socket/SocketServer'
 export * as PlatformNode from '@effect/platform-node'
 
-export * as ChildProcessRunner from './ChildProcessRunner/ChildProcessRunner.ts'
-export * as ChildProcessWorker from './ChildProcessRunner/ChildProcessWorker.ts'
-
 // Enable debug logging for OpenTelemetry
 // otel.diag.setLogger(new otel.DiagConsoleLogger(), otel.DiagLogLevel.ERROR)
 
 // export const OtelLiveHttp = (args: any): Layer.Layer<never> => Layer.empty
 
-export const getFreePort: Effect.Effect<number, UnknownError> = Effect.async<number, UnknownError>((cb, signal) => {
+export const getFreePort: Effect.Effect<number, UnknownError> = Effect.callback<number, UnknownError>((cb, signal) => {
   const server = http.createServer()
 
   signal.addEventListener('abort', () => {
@@ -28,7 +26,7 @@ export const getFreePort: Effect.Effect<number, UnknownError> = Effect.async<num
   server.listen(0, () => {
     const address = server.address()
 
-    if (address && typeof address === 'object') {
+    if (address !== null && typeof address === 'object') {
       const port = address.port
       server.close(() => cb(Effect.succeed(port)))
     } else {
@@ -45,9 +43,56 @@ export const getFreePort: Effect.Effect<number, UnknownError> = Effect.async<num
 export const OtelLiveDummy: Layer.Layer<OtelTracer.OtelTracer> = Layer.suspend(() => {
   const OtelTracerLive = Layer.succeed(OtelTracer.OtelTracer, makeNoopTracer())
 
-  const TracingLive = Layer.unwrapEffect(Effect.map(OtelTracer.make, Layer.setTracer)).pipe(
-    Layer.provideMerge(OtelTracerLive),
-  )
+  const TracingLive = OtelTracer.layerWithoutOtelTracer.pipe(Layer.provideMerge(OtelTracerLive))
 
   return TracingLive
 })
+
+/**
+ * Compatibility layer for the old Effect v3 @parcel/watcher backend.
+ *
+ * Effect v4 removed `@effect/platform-node/NodeFileSystem/ParcelWatcher`; its
+ * NodeFileSystem layer now performs recursive watching through Node's native
+ * `fs.watch(path, { recursive: true })` fallback. This layer deliberately
+ * registers no custom backend so existing `NodeRecursiveWatchLayer` consumers
+ * continue to compile while the v4 NodeFileSystem implementation handles watch
+ * events.
+ *
+ * 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.Layer<FileSystem.WatchBackend> = Layer.succeed(
+  FileSystem.WatchBackend,
+  FileSystem.WatchBackend.of({
+    register: () => Option.none(),
+  }),
+)
+
+/**
+ * Pre-composed layer providing FileSystem with recursive file watching.
+ * 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).
+ * Effect v4's NodeFileSystem uses Node.js's native recursive `fs.watch` support
+ * instead of the removed ParcelWatcher backend from Effect v3.
+ */
+export { NodeFileSystem } from '@effect/platform-node'
+
+export const NodeFileSystemWithWatch = NodeFileSystem.layer.pipe(Layer.provideMerge(NodeRecursiveWatchLayer))

package/src/object/index.ts

@@ -1,25 +1 @@
-import { pipe } from 'effect'
-
-export * from './omit.ts'
-export * from './pick.ts'
 export * from './stringify-object.ts'
-
-type ValueOfRecord<R extends Record<any, any>> = R extends Record<any, infer V> ? V : never
-
-export const mapObjectValues = <O_In extends Record<string, any>, V_Out>(
-  obj: O_In,
-  mapValue: (key: keyof O_In, val: ValueOfRecord<O_In>) => V_Out,
-): { [K in keyof O_In]: V_Out } => {
-  const mappedEntries = Object.entries(obj).map(([key, val]) => [key, mapValue(key as keyof O_In, val)] as const)
-  return Object.fromEntries(mappedEntries) as any
-}
-
-export type Entries<T> = { [K in keyof T]: [K, T[K]] }[keyof T][]
-
-export const objectEntries = <T extends Record<string, any>>(obj: T): Entries<T> => Object.entries(obj) as Entries<T>
-
-export const keyObjectFromObject = <TObj extends Record<string, any>>(obj: TObj): { [K in keyof TObj]: K } =>
-  pipe(
-    objectEntries(obj).map(([k]) => [k, k]),
-    Object.fromEntries,
-  ) as any

package/src/object/stringify-object.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+
 import { stringifyObject } from './stringify-object.ts'
 
 describe('stringifyObject', () => {

package/src/object/stringify-object.ts

@@ -11,10 +11,10 @@ export const stringifyObject = (obj: object, prefix = ''): string => {
   for (const [key, value] of Object.entries(obj)) {
     const fullKey = prefix !== '' ? `${prefix}.${key}` : key
 
-    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    if (typeof value === 'object' && value !== null && Array.isArray(value) === false) {
       // Recursively stringify nested objects with dot notation
       entries.push(stringifyObject(value, fullKey))
-    } else if (Array.isArray(value)) {
+    } else if (Array.isArray(value) === true) {
       // Arrays get converted to comma-separated values
       entries.push(`${fullKey}=${value.join(',')}`)
     } else {

package/src/qr.ts

@@ -0,0 +1,125 @@
+import qrcode from 'qrcode-generator'
+
+export { default as QR } from 'qrcode-generator'
+
+export type QRErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H'
+
+export type PrintQrTerminalOptions = {
+  errorCorrectionLevel?: QRErrorCorrectionLevel
+  /** number of white-cell rows/cols around the QR (default 2) */
+  margin?: number
+  /** Swap dark/light rendering (default false) */
+  invert?: boolean
+  /** Use ANSI colors for compact half-block rendering. Default: auto (true on TTY) */
+  useAnsi?: boolean
+}
+
+/**
+ * Print a QR code to the terminal using Unicode block characters.
+ *
+ * Notes
+ * - Uses `qrcode-generator` under the hood. `typeNumber` is set to `0` which means
+ *   “auto-select the smallest QR version (1..40) that fits the data”. Larger versions
+ *   create larger matrices (each version adds 4 modules per side). See the library:
+ *   - Types (TypeNumber, ErrorCorrectionLevel):
+ *     https://unpkg.com/qrcode-generator@2.0.4/dist/qrcode.d.ts
+ *   - Repository / README:
+ *     https://github.com/kazuhikoarase/qrcode-generator
+ * - Error correction level (ECL) controls how much damage/occlusion can be
+ *   tolerated by adding redundancy. Higher ECL means bigger codes and lower
+ *   payload capacity:
+ *   - L ≈ 7% recovery (highest capacity, lowest redundancy)
+ *   - M ≈ 15% recovery (balanced, common default)
+ *   - Q ≈ 25% recovery (more robust in noisy/low-contrast prints)
+ *   - H ≈ 30% recovery (most robust; largest symbols)
+ *   Reference: https://www.qrcode.com/en/about/error_correction.html
+ * - `small` mode compresses two QR rows into one terminal row using the half-block
+ *   character `▀` and optional ANSI colors (foreground=top, background=bottom).
+ *   This roughly halves the height while keeping readability in modern terminals.
+ * - The QR “quiet zone” (margin) is important for scanners. If scanning is unreliable,
+ *   consider increasing `margin` to 2–4.
+ */
+export const printQrTerminal = (text: string, options?: PrintQrTerminalOptions): void => {
+  const ec: QRErrorCorrectionLevel = options?.errorCorrectionLevel ?? 'M'
+  const margin = options?.margin ?? 2
+  const invert = options?.invert ?? false
+  // Auto-enable ANSI on TTY; avoid in browsers
+  const useAnsi = options?.useAnsi ?? (typeof process !== 'undefined' && !!(process as any)?.stdout?.isTTY)
+
+  // Create the QR code. `0` means: choose the smallest possible version automatically.
+  // Error correction level (L/M/Q/H) trades capacity for redundancy.
+  const qr = qrcode(0, ec)
+  qr.addData(text)
+  qr.make()
+
+  const size = qr.getModuleCount()
+
+  // Helper: read a module, applying margin and optional inversion.
+  // qrcode-generator’s `isDark` signature is (row, col) i.e. (y, x).
+  const isDarkAt = (x: number, y: number): boolean => {
+    const row = y - margin
+    const col = x - margin
+    if (row < 0 || col < 0 || row >= size || col >= size) return false
+    const bit = qr.isDark(row, col)
+    return invert === true ? !bit : bit
+  }
+
+  const lines: string[] = []
+
+  // Compact rendering: combine two QR rows into one terminal row using half-blocks.
+  // With ANSI enabled: use `▀` and paint top as FG, bottom as BG (clear and crisp).
+  // Without ANSI: fall back to block chars (`█`, `▀`, `▄`, space). Note that the
+  // non-ANSI fallback cannot enforce a white background on dark themes, which may
+  // reduce scanner reliability—prefer ANSI when possible.
+  const width = size + 2 * margin
+  const height = size + 2 * margin
+
+  // ANSI helpers (only used when enabled)
+  // Use bright white for a strong “paper-like” background on dark terminals.
+  const RESET = '\x1b[0m'
+  const FG_BLACK = '\x1b[30m'
+  const FG_WHITE = '\x1b[97m'
+  const BG_BLACK = '\x1b[40m'
+  const BG_WHITE = '\x1b[107m'
+
+  for (let y = 0; y < height; y += 2) {
+    let row = ''
+    let currentStyle = ''
+    const setStyle = (style: string) => {
+      if (style !== currentStyle) {
+        if (currentStyle !== undefined) row += RESET
+        if (style !== undefined) row += style
+        currentStyle = style
+      }
+    }
+
+    for (let x = 0; x < width; x++) {
+      const top = isDarkAt(x, y)
+      const bottom = isDarkAt(x, y + 1)
+
+      if (useAnsi === true) {
+        // Represent two stacked modules with a single `▀` character.
+        // Foreground corresponds to the top pixel; background to the bottom pixel.
+        // Always paint both halves to enforce a white quiet zone even on dark terminals.
+        const fg = top === true ? FG_BLACK : FG_WHITE
+        const bg = bottom === true ? BG_BLACK : BG_WHITE
+        setStyle(fg + bg)
+        row += '▀'
+      } else {
+        // No ANSI: approximate using block characters.
+        let ch = ' '
+        if (top === true && bottom === true) ch = '█'
+        else if (top === true && bottom === false) ch = '▀'
+        else if (top === false && bottom === true) ch = '▄'
+        row += ch
+      }
+    }
+
+    if (useAnsi === true) {
+      if (currentStyle !== undefined) row += RESET
+    }
+    lines.push(row)
+  }
+
+  console.log(lines.join('\n'))
+}

package/src/set.ts

@@ -1,7 +1,7 @@
 export const difference = <T>(a: Set<T>, b: Set<T>) => {
   const diff = new Set<T>()
   for (const item of a) {
-    if (!b.has(item)) {
+    if (b.has(item) === false) {
       diff.add(item)
     }
   }

package/src/string.ts

@@ -1,6 +1,3 @@
-export const lowercaseFirstChar = (str: string) => str.charAt(0).toLowerCase() + str.slice(1)
-export const uppercaseFirstChar = (str: string) => str.charAt(0).toUpperCase() + str.slice(1)
-
 /** Indents a string each line by `n` characters (default: spaces) */
 export const indent = (str: string, n: number, char = ' '): string =>
   str