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

package/src/ClientSessionLeaderThreadProxy.ts

@@ -1,33 +1,48 @@
-import type { Effect, Stream } from '@livestore/utils/effect'
+import type { Effect, Stream, Subscribable } from '@livestore/utils/effect'
 
+import type { StorageMode } from './adapter-types.ts'
 import type { MigrationsReport } from './defs.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { UnexpectedError } from './errors.ts'
-import type * as EventSequenceNumber from './schema/EventSequenceNumber.ts'
+import type { RejectedPushError } from './leader-thread/RejectedPushError.ts'
+import type { StreamEventsOptions } from './leader-thread/types.ts'
+import type * as EventSequenceNumber from './schema/EventSequenceNumber/mod.ts'
 import type { LiveStoreEvent } from './schema/mod.ts'
-import type { LeaderAheadError } from './sync/sync.ts'
+import type { SyncBackend } from './sync/sync.ts'
 import type { PayloadUpstream, SyncState } from './sync/syncstate.ts'
 
 export interface ClientSessionLeaderThreadProxy {
   events: {
     pull: (args: {
-      cursor: EventSequenceNumber.EventSequenceNumber
-    }) => Stream.Stream<{ payload: typeof PayloadUpstream.Type }, UnexpectedError>
+      cursor: EventSequenceNumber.Client.Composite
+    }) => Stream.Stream<{ payload: typeof PayloadUpstream.Type }>
     /** It's important that a client session doesn't call `push` concurrently. */
-    push(batch: ReadonlyArray<LiveStoreEvent.AnyEncoded>): Effect.Effect<void, UnexpectedError | LeaderAheadError>
+    push(batch: ReadonlyArray<LiveStoreEvent.Client.Encoded>): Effect.Effect<void, RejectedPushError>
+    /** Stream events with filtering */
+    stream(options: StreamEventsOptions): Stream.Stream<LiveStoreEvent.Client.Encoded>
   }
   /** The initial state after the leader thread has booted */
   readonly initialState: {
     /** The latest event sequence number during boot. Used for the client session to resume syncing. */
-    readonly leaderHead: EventSequenceNumber.EventSequenceNumber
+    readonly leaderHead: EventSequenceNumber.Client.Composite
     /** The migrations report from the leader thread */
     readonly migrationsReport: MigrationsReport
+    /**
+     * Indicates how data is being stored.
+     * - `persisted`: Data is persisted to disk (e.g., via OPFS)
+     * - `in-memory`: Data is only stored in memory and will be lost on page refresh (e.g., private browsing)
+     */
+    readonly storageMode: StorageMode
   }
-  export: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>, UnexpectedError>
-  getSyncState: Effect.Effect<SyncState, UnexpectedError>
+  export: Effect.Effect<Uint8Array<ArrayBuffer>>
+  getEventlogData: Effect.Effect<Uint8Array<ArrayBuffer>>
+  syncState: Subscribable.Subscribable<SyncState>
   /** For debugging purposes it can be useful to manually trigger devtools messages (e.g. to reset the database) */
-  sendDevtoolsMessage: (message: Devtools.Leader.MessageToApp) => Effect.Effect<void, UnexpectedError>
+  sendDevtoolsMessage: (message: Devtools.Leader.MessageToApp) => Effect.Effect<void>
+  /**
+   * Reactive stream describing the connectivity between the leader and its upstream sync backend.
+   * Includes raw connection state, last transition timestamp, and devtools overrides (latch state).
+   */
+  networkStatus: Subscribable.Subscribable<SyncBackend.NetworkStatus>
 }
 
 export const of = (

package/src/MaterializationJournal.ts

@@ -0,0 +1,184 @@
+import { Context, Effect, Layer, Predicate, ReadonlyArray, Schema } from '@livestore/utils/effect'
+
+import { SqliteError, type SqliteDb } from './adapter-types.ts'
+import { execSql, execSqlPrepared } from './leader-thread/connection.ts'
+import * as EventSequenceNumber from './schema/EventSequenceNumber/mod.ts'
+import { SystemTables } from './schema/mod.ts'
+import { findManyRows, insertRow } from './sql-queries/index.ts'
+import * as SqliteDbHelper from './sqlite-db-helper.ts'
+import { prepareBindValues, sql } from './util.ts'
+
+export const TypeId = '~@livestore/common/MaterializationJournal' as const
+export type TypeId = typeof TypeId
+
+export const MaterializationJournalErrorTypeId = '~@livestore/common/MaterializationJournalError' as const
+
+export const isMaterializationJournalError = (u: unknown): u is MaterializationJournalError =>
+  Predicate.hasProperty(u, MaterializationJournalErrorTypeId)
+
+export class MaterializationJournalError extends Schema.TaggedError<MaterializationJournalError>(
+  MaterializationJournalErrorTypeId,
+)('MaterializationJournalError', {
+  method: Schema.Literals(['record', 'rollback', 'discardUpTo']),
+  cause: Schema.Defect(),
+}) {
+  readonly [MaterializationJournalErrorTypeId] = MaterializationJournalErrorTypeId
+}
+
+export type MaterializationChangeset = { _tag: 'changeset'; data: Uint8Array<ArrayBuffer> } | { _tag: 'no-op' }
+
+export type MaterializationRecord = {
+  key: EventSequenceNumber.Client.Composite
+  changeset: MaterializationChangeset
+}
+
+export interface Service {
+  readonly [TypeId]: TypeId
+  /** Stores a materialization record, replacing any record at the same key. */
+  record: (record: MaterializationRecord) => Effect.Effect<void, MaterializationJournalError>
+  /** Reverts the keyed materializations in reverse order, then discards their records. */
+  rollback: (
+    keys: ReadonlyArray<EventSequenceNumber.Client.Composite>,
+  ) => Effect.Effect<void, MaterializationJournalError>
+  /** Discards records whose key is less than or equal to `key`, ignoring rebase generation. */
+  discardUpTo: (key: EventSequenceNumber.Client.Composite) => Effect.Effect<void, MaterializationJournalError>
+}
+
+export class MaterializationJournal extends Context.Service<MaterializationJournal, Service>()(
+  '@livestore/common/MaterializationJournal',
+) {}
+
+interface Options {
+  readonly dbState: SqliteDb
+}
+
+export const make = ({ dbState }: Options) => {
+  const deleteByKeys = Effect.fnUntraced(function* (keys: ReadonlyArray<EventSequenceNumber.Client.Composite>) {
+    // Keep DELETE statements below SQLite's bound-parameter limit.
+    const keyChunks = ReadonlyArray.chunksOf(100)(keys)
+
+    for (const keyChunk of keyChunks) {
+      const placeholders = keyChunk.map(() => '(?, ?, ?)').join(', ')
+      const bindValues = keyChunk.flatMap((key) => [key.global, key.client, key.rebaseGeneration])
+      const statement = sql`DELETE FROM ${SystemTables.MATERIALIZATION_JOURNAL_META_TABLE}
+                            WHERE (seqNumGlobal, seqNumClient, seqNumRebaseGeneration) IN (${placeholders})`
+
+      yield* execSqlPrepared(dbState, statement, prepareBindValues(bindValues, statement))
+    }
+  }, SqliteDbHelper.withSavepoint(dbState))
+
+  return MaterializationJournal.of({
+    [TypeId]: TypeId,
+    record: Effect.fnUntraced(
+      function* (record: MaterializationRecord) {
+        yield* deleteByKeys([record.key])
+
+        // Generate the parameterized INSERT statement
+        const [statement, bindValues] = insertRow({
+          tableName: SystemTables.MATERIALIZATION_JOURNAL_META_TABLE,
+          columns: SystemTables.materializationJournalMetaTable.sqliteDef.columns,
+          values: {
+            seqNumGlobal: record.key.global,
+            seqNumClient: record.key.client,
+            seqNumRebaseGeneration: record.key.rebaseGeneration,
+            changeset: record.changeset._tag === 'changeset' ? record.changeset.data : null,
+            // Legacy processors still expose this column for development diagnostics.
+            debug: null,
+          },
+        })
+
+        yield* execSqlPrepared(dbState, statement, prepareBindValues(bindValues, statement))
+      },
+      SqliteDbHelper.withSavepoint(dbState),
+      Effect.mapError((cause) => new MaterializationJournalError({ method: 'record', cause })),
+    ),
+    rollback: Effect.fnUntraced(
+      function* (keys: ReadonlyArray<EventSequenceNumber.Client.Composite>) {
+        const sortedKeys = keys.toSorted((a, b) => EventSequenceNumber.Client.compare(b, a))
+        const rollbackRecords = yield* Effect.forEach(
+          sortedKeys,
+          Effect.fnUntraced(function* (key) {
+            const [statement, bindValues] = findManyRows({
+              tableName: SystemTables.MATERIALIZATION_JOURNAL_META_TABLE,
+              columns: SystemTables.materializationJournalMetaTable.sqliteDef.columns,
+              where: {
+                seqNumGlobal: key.global,
+                seqNumClient: key.client,
+                seqNumRebaseGeneration: key.rebaseGeneration,
+              },
+              limit: 1,
+            })
+            const preparedBindValues = prepareBindValues(bindValues, statement)
+            const row = yield* Effect.try({
+              try: () => dbState.select<SystemTables.MaterializationJournalMetaRow>(statement, preparedBindValues)[0],
+              catch: (cause) => new SqliteError({ cause, query: { sql: statement, bindValues: preparedBindValues } }),
+            })
+
+            if (row === undefined) {
+              return yield* new MaterializationJournalError({
+                method: 'rollback',
+                cause: new Error(
+                  `Missing materialization journal record for ${EventSequenceNumber.Client.toString(key)}`,
+                ),
+              })
+            }
+
+            return {
+              key,
+              changeset:
+                row.changeset === null
+                  ? { _tag: 'no-op' as const }
+                  : { _tag: 'changeset' as const, data: row.changeset },
+            }
+          }),
+        )
+
+        for (const record of rollbackRecords) {
+          if (record.changeset._tag === 'changeset') {
+            const data = record.changeset.data
+            yield* Effect.try({
+              try: () => dbState.makeChangeset(data).invert().apply(),
+              catch: (cause) => new SqliteError({ cause }),
+            })
+          }
+        }
+
+        yield* deleteByKeys(sortedKeys)
+      },
+      SqliteDbHelper.withSavepoint(dbState),
+      Effect.mapError((cause) =>
+        isMaterializationJournalError(cause) === true
+          ? cause
+          : new MaterializationJournalError({ method: 'rollback', cause }),
+      ),
+    ),
+    discardUpTo: Effect.fnUntraced(
+      function* (key: EventSequenceNumber.Client.Composite) {
+        yield* execSql(
+          dbState,
+          sql`DELETE FROM ${SystemTables.MATERIALIZATION_JOURNAL_META_TABLE}
+              WHERE seqNumGlobal < ${key.global}
+                 OR (
+                  seqNumGlobal = ${key.global}
+                      AND seqNumClient <= ${key.client}
+                  )`,
+          {},
+        )
+      },
+      SqliteDbHelper.withSavepoint(dbState),
+      Effect.mapError((cause) => new MaterializationJournalError({ method: 'discardUpTo', cause })),
+    ),
+  })
+}
+
+export const layer = (options: Options) => Layer.succeed(MaterializationJournal, make(options))
+
+export const layerTest = Layer.succeed(
+  MaterializationJournal,
+  MaterializationJournal.of({
+    [TypeId]: TypeId,
+    record: () => Effect.void,
+    rollback: () => Effect.void,
+    discardUpTo: () => Effect.void,
+  }),
+)

package/src/StateHead.ts

@@ -0,0 +1,80 @@
+import { Context, Effect, Layer } from '@livestore/utils/effect'
+
+import type { SqliteDb, SqliteError } from './adapter-types.ts'
+import { execSql, selectSql } from './leader-thread/connection.ts'
+import * as EventSequenceNumber from './schema/EventSequenceNumber/mod.ts'
+import { SystemTables } from './schema/mod.ts'
+import { findManyRows, insertRow } from './sql-queries/index.ts'
+
+export const TypeId = '~@livestore/common/StateHead' as const
+export type TypeId = typeof TypeId
+
+const STATE_HEAD_ROW_ID = 1
+
+/**
+ * Persists and reads the latest event sequence number reflected by the state database.
+ */
+export interface Service {
+  readonly [TypeId]: TypeId
+  /** Persists the latest event sequence number reflected by the state database. */
+  set: (head: EventSequenceNumber.Client.Composite) => Effect.Effect<void, SqliteError>
+  /** Returns the persisted head, or the root when the current-schema table has no row. */
+  get: Effect.Effect<EventSequenceNumber.Client.Composite, SqliteError>
+}
+
+export class StateHead extends Context.Service<StateHead, Service>()('@livestore/common/StateHead') {}
+
+interface Options {
+  readonly dbState: SqliteDb
+}
+
+export const make = ({ dbState }: Options) => {
+  return StateHead.of({
+    [TypeId]: TypeId,
+    set: (head) => {
+      const [statement, bindValues] = insertRow({
+        tableName: SystemTables.STATE_HEAD_META_TABLE,
+        columns: SystemTables.stateHeadMetaTable.sqliteDef.columns,
+        values: {
+          id: STATE_HEAD_ROW_ID,
+          seqNumGlobal: head.global,
+          seqNumClient: head.client,
+          seqNumRebaseGeneration: head.rebaseGeneration,
+        },
+        options: { orReplace: true },
+      })
+
+      return execSql(dbState, statement, bindValues)
+    },
+    get: Effect.suspend(() => {
+      const [statement, bindValues] = findManyRows({
+        tableName: SystemTables.STATE_HEAD_META_TABLE,
+        columns: SystemTables.stateHeadMetaTable.sqliteDef.columns,
+        where: { id: STATE_HEAD_ROW_ID },
+        limit: 1,
+      })
+      return selectSql<SystemTables.StateHeadMetaRow>(dbState, statement, bindValues).pipe(
+        Effect.map(([row]) =>
+          row === undefined
+            ? EventSequenceNumber.Client.ROOT
+            : EventSequenceNumber.Client.Composite.make({
+                global: row.seqNumGlobal,
+                client: row.seqNumClient,
+                rebaseGeneration: row.seqNumRebaseGeneration,
+              }),
+        ),
+      )
+    }),
+  })
+}
+
+export const layer = (options: Options) => Layer.succeed(StateHead, make(options))
+
+export const layerTest = Layer.succeed(
+  StateHead,
+  StateHead.of({
+    [TypeId]: TypeId,
+    set: () => Effect.void,
+    get: Effect.succeed(EventSequenceNumber.Client.ROOT),
+  }),
+)

package/src/WorkerTransportError.ts

@@ -0,0 +1,12 @@
+import { Schema, WorkerError } from '@livestore/utils/effect'
+
+/**
+ * Type guard that identifies infrastructure errors from the Effect Worker transport layer.
+ *
+ * @remarks
+ *
+ * These errors ({@link WorkerError.WorkerError}, {@link Schema.SchemaError}) represent communication failures between
+ * threads/processes — not application-level failures.
+ */
+export const isWorkerTransportError = (e: unknown): e is WorkerError.WorkerError | Schema.SchemaError =>
+  Schema.isSchemaError(e) || WorkerError.isWorkerError(e)

package/src/__tests__/fixture.ts

@@ -1,7 +1,7 @@
 import { Schema } from '@livestore/utils/effect'
 
-import { SessionIdSymbol } from '../adapter-types.ts'
 import { makeSchema, State } from '../schema/mod.ts'
+import { SessionIdSymbol } from '../session-id-symbol.ts'
 
 export const UiState = State.SQLite.clientDocument({
   name: 'UiState',
@@ -14,8 +14,8 @@ export const UiState = State.SQLite.clientDocument({
 })
 
 const Config = Schema.Struct({
-  fontSize: Schema.Number,
-  theme: Schema.Literal('light', 'dark'),
+  fontSize: Schema.Finite,
+  theme: Schema.Literals(['light', 'dark']),
 })
 
 export const appConfig = State.SQLite.clientDocument({

package/src/adapter-types.ts

@@ -2,6 +2,7 @@ import {
   type Effect,
   type Exit,
   type Queue,
+  type Latch,
   Schema,
   type Scope,
   type SubscriptionRef,
@@ -10,26 +11,31 @@ import {
 
 import type { ClientSessionLeaderThreadProxy } from './ClientSessionLeaderThreadProxy.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { IntentionalShutdownCause, MaterializeError, UnexpectedError } from './errors.ts'
+import type { IntentionalShutdownCause, MaterializeError, UnknownError } from './errors.ts'
 import type { LiveStoreSchema } from './schema/mod.ts'
 import type { SqliteDb } from './sqlite-types.ts'
-import type { IsOfflineError, SyncError } from './sync/index.js'
+import type { BackendIdMismatchError } from './sync/index.ts'
 
 export * as ClientSessionLeaderThreadProxy from './ClientSessionLeaderThreadProxy.ts'
 export * from './defs.ts'
 export * from './errors.ts'
 export * from './sqlite-types.ts'
 
+/**
+ * Runtime handle to an active LiveStore client session within the current process.
+ * Provides direct access to the embedded SQLite database, leader thread bridge,
+ * and lifecycle controls useful for application-level coordination.
+ */
 export interface ClientSession {
   /** SQLite database with synchronous API running in the same thread (usually in-memory) */
   sqliteDb: SqliteDb
-  devtools: { enabled: false } | { enabled: true; pullLatch: Effect.Latch; pushLatch: Effect.Latch }
+  devtools: { enabled: false } | { enabled: true; pullLatch: Latch.Latch; pushLatch: Latch.Latch }
   clientId: string
   sessionId: string
   /** Status info whether current session is leader or not */
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
   shutdown: (
-    cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError>,
+    cause: Exit.Exit<IntentionalShutdownCause, UnknownError | MaterializeError | BackendIdMismatchError>,
   ) => Effect.Effect<void>
   /** A proxy API to communicate with the leader thread */
   leaderThread: ClientSessionLeaderThreadProxy
@@ -40,83 +46,81 @@ export interface ClientSession {
 export type ResetMode = 'all-data' | 'only-app-db'
 
 export const BootStateProgress = Schema.Struct({
-  done: Schema.Number,
-  total: Schema.Number,
+  done: Schema.Finite,
+  total: Schema.Finite,
 })
 
-export const BootStatus = Schema.Union(
+/**
+ * Describes known reasons why LiveStore boot may encounter storage issues.
+ *
+ * @remarks
+ * - `private-browsing`: OPFS unavailable due to private/incognito browsing mode (Safari, Firefox)
+ * - `storage-unavailable`: OPFS access denied for other reasons (permissions, quota)
+ * - `unknown`: Unexpected error during storage initialization
+ */
+export const BootWarningReason = Schema.Literals(['private-browsing', 'storage-unavailable', 'unknown'])
+export type BootWarningReason = typeof BootWarningReason.Type
+
+/**
+ * Describes the storage mode the store is operating in.
+ *
+ * @remarks
+ * - `persisted`: Data is persisted to disk (e.g., via OPFS)
+ * - `in-memory`: Data is only stored in memory and will be lost on page refresh
+ */
+export const StorageMode = Schema.Literals(['persisted', 'in-memory'])
+export type StorageMode = typeof StorageMode.Type
+
+export const BootStatus = Schema.Union([
   Schema.Struct({ stage: Schema.Literal('loading') }),
   Schema.Struct({ stage: Schema.Literal('migrating'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('rehydrating'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('syncing'), progress: BootStateProgress }),
   Schema.Struct({ stage: Schema.Literal('done') }),
-).annotations({ title: 'BootStatus' })
+  /**
+   * Indicates a non-fatal issue occurred during boot that may degrade functionality.
+   * LiveStore continues running but without full capabilities (e.g., no persistence).
+   */
+  Schema.Struct({
+    stage: Schema.Literal('warning'),
+    reason: BootWarningReason,
+    message: Schema.String,
+  }),
+]).annotate({ title: 'BootStatus' })
 
 export type BootStatus = typeof BootStatus.Type
 
-/**
- * Can be used in queries to refer to the current session id.
- * Will be replaced with the actual session id at runtime
- *
- * In client document table:
- * ```ts
- * const uiState = State.SQLite.clientDocument({
- *   name: 'ui_state',
- *   schema: Schema.Struct({
- *     theme: Schema.Literal('dark', 'light', 'system'),
- *     user: Schema.String,
- *     showToolbar: Schema.Boolean,
- *   }),
- *   default: { value: defaultFrontendState, id: SessionIdSymbol },
- * })
- * ```
- *
- * Or in a client document query:
- * ```ts
- * const query$ = queryDb(tables.uiState.get(SessionIdSymbol))
- * ```
- */
-export const SessionIdSymbol = Symbol.for('@livestore/session-id')
-export type SessionIdSymbol = typeof SessionIdSymbol
-
 export type LockStatus = 'has-lock' | 'no-lock'
 
-// TODO possibly allow a combination of these options
 // TODO allow a way to stream the migration progress back to the app
-export type MigrationOptions =
-  | {
-      strategy: 'auto'
-      hooks?: Partial<MigrationHooks>
-      logging?: {
-        excludeAffectedRows?: (sqlStmt: string) => boolean
-      }
-    }
-  | {
-      strategy: 'manual'
-      migrate: (
-        oldDb: Uint8Array<ArrayBuffer>,
-      ) => Uint8Array<ArrayBuffer> | Promise<Uint8Array<ArrayBuffer>> | Effect.Effect<Uint8Array<ArrayBuffer>, unknown>
-    }
+export type MigrationOptions = {
+  hooks?: Partial<MigrationHooks>
+  logging?: {
+    excludeAffectedRows?: (sqlStmt: string) => boolean
+  }
+}
 
 export type MigrationHooks = {
   /** Runs on the empty in-memory database with no database schemas applied yet */
   init: MigrationHook
-  /** Runs before applying the migration strategy but after table schemas have been applied and singleton rows have been created */
+  /** Runs after table schemas and singleton rows are created, but before rematerializing state from the eventlog */
   pre: MigrationHook
-  /** Runs after applying the migration strategy before creating export snapshot and closing the database */
+  /** Runs after rematerializing state from the eventlog */
   post: MigrationHook
 }
 
 export type MigrationHook = (db: SqliteDb) => void | Promise<void> | Effect.Effect<void, unknown>
 
-export interface ClientSessionDevtoolsChannel
-  extends WebChannel.WebChannel<Devtools.ClientSession.MessageToApp, Devtools.ClientSession.MessageFromApp> {}
+export interface ClientSessionDevtoolsChannel extends WebChannel.WebChannel<
+  Devtools.ClientSession.MessageToApp,
+  Devtools.ClientSession.MessageFromApp
+> {}
 
 export type ConnectDevtoolsToStore = (
   storeDevtoolsChannel: ClientSessionDevtoolsChannel,
-) => Effect.Effect<void, UnexpectedError, Scope.Scope>
+) => Effect.Effect<void, UnknownError, Scope.Scope>
 
-export type Adapter = (args: AdapterArgs) => Effect.Effect<ClientSession, UnexpectedError, Scope.Scope>
+export type Adapter = (args: AdapterArgs) => Effect.Effect<ClientSession, UnknownError, Scope.Scope>
 
 export interface AdapterArgs {
   schema: LiveStoreSchema
@@ -125,7 +129,7 @@ export interface AdapterArgs {
   debugInstanceId: string
   bootStatusQueue: Queue.Queue<BootStatus>
   shutdown: (
-    exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError | IsOfflineError>,
+    exit: Exit.Exit<IntentionalShutdownCause, UnknownError | MaterializeError | BackendIdMismatchError>,
   ) => Effect.Effect<void>
   connectDevtoolsToStore: ConnectDevtoolsToStore
   /**
@@ -133,5 +137,7 @@ export interface AdapterArgs {
    *
    * @default undefined
    */
-  syncPayload: Schema.JsonValue | undefined
+  syncPayloadSchema: Schema.Decoder<Schema.Json> | undefined
+  /** Encoded representation of the sync payload matching `syncPayloadSchema`. */
+  syncPayloadEncoded: Schema.Json | undefined
 }

package/src/bounded-collections.ts

@@ -16,10 +16,11 @@ export class BoundMap<K, V> {
     this.#map.set(key, value)
     // console.log(this.#map.size, this.#sizeLimit);
     if (this.#map.size > this.#sizeLimit) {
-      const firstKey = this.#map.keys().next().value as K
+      const firstKey = this.#map.keys().next().value
+      if (firstKey === undefined) return
       const deletedValue = this.#map.get(firstKey)!
       this.#map.delete(firstKey)
-      if (this.onEvict) {
+      if (this.onEvict !== undefined) {
         this.onEvict(firstKey, deletedValue)
       }
     }
@@ -47,7 +48,7 @@ export class BoundSet<V> {
   }
 
   #onEvict = (v: V) => {
-    if (this.onEvict) {
+    if (this.onEvict !== undefined) {
       this.onEvict(v)
     }
   }
@@ -85,7 +86,7 @@ export class BoundArray<V> {
     this.#array.push(v)
     if (this.#array.length > this.sizeLimit) {
       const first = this.#array.shift()
-      if (first && this.onEvict) {
+      if (first !== undefined && this.onEvict !== undefined) {
         this.onEvict(first)
       }
     }
@@ -116,6 +117,6 @@ export class BoundArray<V> {
   }
 
   sort = (fn?: (a: V, b: V) => number) => {
-    return this.#array.sort(fn)
+    return this.#array.toSorted(fn)
   }
 }