@delali/narsil-react-native 0.0.0-stage → 0.3.1-next.151

package/src/types.ts

@@ -0,0 +1,164 @@
+import type {
+  AnalysisChange,
+  AnyDocument,
+  BatchResult,
+  BM25Params,
+  DocumentImportResult,
+  DurabilityConfig,
+  IndexConfig,
+  IndexInfo,
+  IndexStats,
+  InsertOptions,
+  ListParams,
+  ListResult,
+  MemoryStats,
+  NarsilConfig,
+  NarsilEventMap,
+  PartitionConfig,
+  PartitionStatsResult,
+  PreflightResult,
+  QueryParams,
+  QueryResult,
+  SuggestParams,
+  SuggestResult,
+  SynonymRule,
+  VectorMaintenanceResult,
+  WriteOptions,
+} from '@delali/narsil'
+
+/**
+ * The engine settings, which are the settings of `createNarsil` in
+ * `@delali/narsil`, function settings such as `embeddingAdapters`, `plugins`,
+ * and `idGenerator` included.
+ *
+ * `durability` defaults to a write-ahead log in a `narsil` directory inside
+ * the app's private storage, and `null` keeps the index in memory alone. A
+ * relative `directory` resolves against that private storage.
+ *
+ * @public
+ */
+export type PhoneNarsilConfig = Omit<NarsilConfig, 'durability'> & { durability?: DurabilityConfig | null }
+
+/**
+ * Receives one engine event on the app's JS thread. An `Error` inside the
+ * payload arrives as an `Error` carrying the original `name`, `message`,
+ * `code`, and `details`.
+ *
+ * @public
+ */
+export type PhoneEventHandler<K extends keyof NarsilEventMap> = (payload: NarsilEventMap[K]) => void
+
+/**
+ * A Narsil engine on a phone. Every method resolves with the engine's answer,
+ * so a method that the engine answers synchronously, such as `listIndexes`,
+ * also resolves through a promise here. Each method otherwise behaves as the
+ * method of the same name on the `Narsil` interface of `@delali/narsil`.
+ *
+ * A failure rejects with an `Error` whose `name` is `NarsilError` for an
+ * engine failure, and whose `code` and `details` match the engine's error.
+ * {@link isNarsilError} recognises it.
+ *
+ * @public
+ */
+export interface PhoneNarsil {
+  /** Creates an index from a schema and its settings. */
+  createIndex(name: string, config: IndexConfig): Promise<void>
+  /** Removes an index and the files that it wrote. */
+  dropIndex(name: string): Promise<void>
+  /** Lists every index that this engine holds. */
+  listIndexes(): Promise<IndexInfo[]>
+  /** Returns one index's document count, memory estimate, and schema. */
+  getStats(indexName: string): Promise<IndexStats>
+  /** Returns the figures of each open partition of one index. */
+  getPartitionStats(indexName: string): Promise<PartitionStatsResult[]>
+  /** Fetches one stored document by id, or `undefined` when the index lacks it. */
+  get(indexName: string, docId: string): Promise<AnyDocument | undefined>
+  /** Fetches many stored documents by id, keyed by id. */
+  getMultiple(indexName: string, docIds: string[]): Promise<Map<string, AnyDocument>>
+  /** Reports whether an index holds a document. */
+  has(indexName: string, docId: string): Promise<boolean>
+  /** Counts the documents of one index. */
+  countDocuments(indexName: string): Promise<number>
+  /** Reads one page of stored documents in document-id order. */
+  listDocuments<T = AnyDocument>(indexName: string, params?: ListParams): Promise<ListResult<T>>
+  /** Searches one index by keyword, by vector, or by both. */
+  query<T = AnyDocument>(indexName: string, params: QueryParams): Promise<QueryResult<T>>
+  /** Counts what a query would match without building a single hit. */
+  preflight(indexName: string, params: QueryParams): Promise<PreflightResult>
+  /** Returns the indexed terms that complete a prefix. */
+  suggest(indexName: string, params: SuggestParams): Promise<SuggestResult>
+  /** Rebuilds an index's terms from the documents that it already stores. */
+  rebuildAnalysis(indexName: string): Promise<void>
+  /** Returns a snapshot of one index as the bytes of one `.nrsl` file. */
+  snapshot(indexName: string): Promise<Uint8Array>
+  /**
+   * Writes a snapshot of one index into a file and resolves with its size in
+   * bytes. A relative path resolves against the app's private storage, and
+   * the file replaces any file at that path only once every byte is on disk.
+   */
+  snapshotToFile(indexName: string, path: string): Promise<number>
+  /** Replaces one index with the snapshot in these bytes. */
+  restore(indexName: string, data: Uint8Array): Promise<void>
+  /** Replaces one index with the snapshot in a file, which the engine reads in chunks. */
+  restoreFromFile(indexName: string, path: string): Promise<void>
+  /** Returns every document of one index as the bytes of a document export. */
+  exportDocuments(indexName: string): Promise<Uint8Array>
+  /** Writes a document export of one index into a file and resolves with its size in bytes. */
+  exportDocumentsToFile(indexName: string, path: string): Promise<number>
+  /** Inserts the documents of a document export held in these bytes. */
+  importDocumentExport(indexName: string, data: Uint8Array): Promise<DocumentImportResult>
+  /** Inserts the documents of a document export held in a file. */
+  importDocumentExportFromFile(indexName: string, path: string): Promise<DocumentImportResult>
+  /** Writes an index's current state to the durability directory, so a restart replays less of the log. */
+  checkpoint(indexName: string): Promise<void>
+  /** Removes every document from an index and keeps the index, its schema, and its settings. */
+  clear(indexName: string): Promise<void>
+  /** Spreads an index's documents across a different number of partitions. */
+  rebalance(indexName: string, targetPartitionCount: number): Promise<void>
+  /** Changes how an index grows into new partitions. */
+  updatePartitionConfig(indexName: string, config: Partial<PartitionConfig>): Promise<void>
+  /** Reports what this engine and the app's process use. */
+  getMemoryStats(): Promise<MemoryStats>
+  /** Rebuilds a vector field's graph without the tombstones that removed documents left behind. */
+  compactVectors(indexName: string, fieldName?: string): Promise<void>
+  /** Rebuilds a vector field's graph from scratch, which recovers recall. */
+  optimizeVectors(indexName: string, fieldName?: string): Promise<void>
+  /** Reports the state of each vector field in an index, and what its maintenance would cost. */
+  vectorMaintenanceStatus(indexName: string): Promise<VectorMaintenanceResult[]>
+  /** Opens a closed index. */
+  open(indexName: string): Promise<void>
+  /** Closes an index. */
+  close(indexName: string): Promise<void>
+  /** Inserts one document and resolves with the id that it is stored under. */
+  insert(indexName: string, document: AnyDocument, docId?: string, options?: InsertOptions): Promise<string>
+  /** Inserts many documents in one request. */
+  insertBatch(indexName: string, documents: AnyDocument[], options?: InsertOptions): Promise<BatchResult>
+  /** Removes one document. */
+  remove(indexName: string, docId: string, options?: WriteOptions): Promise<void>
+  /** Removes many documents in one request. */
+  removeBatch(indexName: string, docIds: string[], options?: WriteOptions): Promise<BatchResult>
+  /** Replaces one stored document. */
+  update(indexName: string, docId: string, document: AnyDocument, options?: WriteOptions): Promise<void>
+  /** Replaces many stored documents in one request. */
+  updateBatch(
+    indexName: string,
+    updates: Array<{ docId: string; document: AnyDocument }>,
+    options?: WriteOptions,
+  ): Promise<BatchResult>
+  /** Resolves once every worker copy of an index has applied every earlier write. */
+  waitForWrites(indexName: string): Promise<void>
+  /** Replaces the synonym rules of one index. */
+  updateSynonyms(indexName: string, synonyms: SynonymRule[]): Promise<void>
+  /** Returns the synonym rules of one index. */
+  getSynonyms(indexName: string): Promise<SynonymRule[]>
+  /** Changes how one index analyses text, and re-analyses its documents. */
+  changeAnalysis(indexName: string, change: AnalysisChange): Promise<void>
+  /** Changes the BM25 parameters of one index. */
+  updateBM25(indexName: string, bm25: BM25Params): Promise<void>
+  /** Calls a handler on the app's JS thread for each engine event of one kind. */
+  on<K extends keyof NarsilEventMap>(event: K, handler: PhoneEventHandler<K>): void
+  /** Stops calling a handler that {@link PhoneNarsil.on} registered. */
+  off<K extends keyof NarsilEventMap>(event: K, handler: PhoneEventHandler<K>): void
+  /** Shuts the engine down, after which every other method rejects with `INSTANCE_SHUT_DOWN`. */
+  shutdown(): Promise<void>
+}

package/src/worklets/app-turns.ts

@@ -0,0 +1,48 @@
+import { APP_TIMER_WAIT_BEFORE_RUN_LOOP_HOP_MS } from '../constants'
+
+type Hop = (run: () => void) => void
+
+function hopThroughRuntimeScheduler(): Hop | null {
+  const runtimeScheduler: unknown = Reflect.get(globalThis, 'nativeRuntimeScheduler')
+  if (typeof runtimeScheduler !== 'object' || runtimeScheduler === null) return null
+  const schedule: unknown = Reflect.get(runtimeScheduler, 'unstable_scheduleCallback')
+  const priority: unknown = Reflect.get(runtimeScheduler, 'unstable_NormalPriority')
+  if (typeof schedule !== 'function' || typeof priority !== 'number') return null
+  let appTimerArmedAt: number | null = null
+  let runsAfterAppTimer: Array<() => void> = []
+
+  function appTimerFired(): void {
+    appTimerArmedAt = null
+    const runs = runsAfterAppTimer
+    runsAfterAppTimer = []
+    for (const run of runs) run()
+  }
+
+  return run => {
+    const now = performance.now()
+    if (appTimerArmedAt === null) {
+      appTimerArmedAt = now
+      setTimeout(appTimerFired, 0)
+    } else if (now - appTimerArmedAt >= APP_TIMER_WAIT_BEFORE_RUN_LOOP_HOP_MS) {
+      runsAfterAppTimer.push(run)
+      return
+    }
+    Reflect.apply(schedule, runtimeScheduler, [
+      priority,
+      () => {
+        run()
+      },
+    ])
+  }
+}
+
+function hopThroughTimer(run: () => void): void {
+  setTimeout(run, 0)
+}
+
+let hop: Hop | null = null
+
+export function afterAppTurn(run: () => void): void {
+  hop ??= hopThroughRuntimeScheduler() ?? hopThroughTimer
+  hop(run)
+}

package/src/worklets/client.ts

@@ -0,0 +1,165 @@
+import type { NarsilEventMap } from '@delali/narsil'
+import { isWorkletFunction, type WorkletRuntime } from 'react-native-worklets'
+import { rebuiltError, rebuiltValue } from '../errors'
+import { type EngineMethod, FORWARDED_METHODS, STREAMED_METHODS } from '../methods'
+import { loadNativeObjects } from '../native-objects'
+import type { CallOutcome } from '../transferred'
+import type { PhoneNarsil } from '../types'
+import { jsonOfPart } from './json-part'
+import {
+  boxNativeObjects,
+  sendCall,
+  sendCallPart,
+  sendCallPartText,
+  sendDropCallParts,
+  sendListen,
+  sendOpen,
+  startEngineRuntime,
+} from './runtime'
+import { enqueueCall } from './transfer-queue'
+import type { EngineSetup, WorkletNarsilConfig } from './types'
+
+type EventName = keyof NarsilEventMap
+type AnyHandler = (payload: never) => void
+
+interface PendingCall {
+  resolve(value: unknown): void
+  reject(error: unknown): void
+}
+
+const pendingCalls = new Map<number, PendingCall>()
+const handlersByInstance = new Map<number, Map<EventName, Set<AnyHandler>>>()
+let nextCallId = 1
+
+function settleCall(callId: number, outcome: CallOutcome): void {
+  const pending = pendingCalls.get(callId)
+  if (pending === undefined) return
+  pendingCalls.delete(callId)
+  if (outcome.ok) pending.resolve(outcome.value)
+  else pending.reject(rebuiltError(outcome.error))
+}
+
+function deliverEvent(instanceId: number, event: string, payload: unknown): void {
+  const handlers = handlersByInstance.get(instanceId)?.get(event as EventName)
+  if (handlers === undefined) return
+  const rebuilt = rebuiltValue(payload) as never
+  for (const handler of [...handlers]) {
+    try {
+      handler(rebuilt)
+    } catch (error) {
+      setTimeout(() => {
+        throw error
+      }, 0)
+    }
+  }
+}
+
+function request(send: (callId: number) => void): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const callId = nextCallId++
+    pendingCalls.set(callId, { resolve, reject })
+    try {
+      send(callId)
+    } catch (error) {
+      pendingCalls.delete(callId)
+      reject(error)
+    }
+  })
+}
+
+function phoneNarsil(runtime: WorkletRuntime, instanceId: number): PhoneNarsil {
+  const handlers = new Map<EventName, Set<AnyHandler>>()
+  handlersByInstance.set(instanceId, handlers)
+
+  function call(method: EngineMethod, args: unknown[]): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const callId = nextCallId++
+      pendingCalls.set(callId, { resolve, reject })
+      enqueueCall(args, {
+        sendPart: (argIndex, items) => {
+          const text = jsonOfPart(items)
+          if (text === null) sendCallPart(runtime, callId, argIndex, items)
+          else sendCallPartText(runtime, callId, argIndex, text)
+        },
+        sendCall: (values, partedArgs) => sendCall(runtime, callId, settleCall, instanceId, method, values, partedArgs),
+        dropParts: () => sendDropCallParts(runtime, callId),
+        fail: error => {
+          pendingCalls.delete(callId)
+          reject(error)
+        },
+      })
+    })
+  }
+
+  const client: Record<string, unknown> = {}
+  for (const method of [...FORWARDED_METHODS, ...STREAMED_METHODS]) {
+    client[method] = (...args: unknown[]) => call(method, args)
+  }
+
+  client.on = (event: EventName, handler: AnyHandler) => {
+    let registered = handlers.get(event)
+    if (registered === undefined) {
+      registered = new Set()
+      handlers.set(event, registered)
+    }
+    const first = registered.size === 0
+    registered.add(handler)
+    if (first) sendListen(runtime, instanceId, event, deliverEvent, true)
+  }
+
+  client.off = (event: EventName, handler: AnyHandler) => {
+    const registered = handlers.get(event)
+    if (registered === undefined || !registered.delete(handler)) return
+    if (registered.size > 0) return
+    handlers.delete(event)
+    sendListen(runtime, instanceId, event, deliverEvent, false)
+  }
+
+  client.shutdown = async () => {
+    try {
+      await call('shutdown', [])
+    } finally {
+      handlers.clear()
+      handlersByInstance.delete(instanceId)
+    }
+  }
+
+  return client as unknown as PhoneNarsil
+}
+
+/**
+ * Starts a Narsil engine on its own Worklets runtime and resolves with a
+ * client whose methods send each request to that runtime, so the engine's
+ * JavaScript work leaves the app's JS thread free. Every engine that this
+ * function starts shares one runtime, and each engine keeps its own indexes.
+ * The app needs `react-native-worklets` with Bundle Mode turned on. The
+ * client copies each batch that an insert sends across to the engine's
+ * runtime before the engine indexes it, as JSON text when the batch holds
+ * plain data. On a physical iPhone and a physical Android phone, inserts took
+ * 6% to 57% longer than on the app's own JS runtime, depending on the number
+ * of documents and on durability, and an import from a file, which sends only
+ * the file's path across, took up to 11% longer. In return, the longest pause
+ * that a 10 ms timer on the app's JS thread saw during an insert of 50,000
+ * documents fell from 111 ms to 30 ms on the Android phone and from 144 ms to
+ * 74 ms on the iPhone.
+ *
+ * @param config - The engine settings that cross to the engine's runtime as
+ * data. `durability` defaults to a write-ahead log in the `narsil` directory
+ * of the app's private storage.
+ * @param setup - A worklet that returns the settings that hold functions,
+ * such as embedding adapters, plugins, or an id generator.
+ * @returns The client, once the engine has started on its runtime.
+ * @throws A `NarsilError` with `NATIVE_DEPENDENCY_MISSING` when the app's
+ * build lacks the native module, as in Expo Go.
+ *
+ * @public
+ */
+export async function createNarsil(config: WorkletNarsilConfig = {}, setup?: EngineSetup): Promise<PhoneNarsil> {
+  if (setup !== undefined && !isWorkletFunction(setup)) {
+    throw new TypeError("The setup function must be a worklet, so start its body with the 'worklet' directive")
+  }
+  const natives = await loadNativeObjects()
+  const runtime = startEngineRuntime(await boxNativeObjects(natives))
+  const instanceId = await request(callId => sendOpen(runtime, callId, settleCall, config, setup))
+  return phoneNarsil(runtime, instanceId as number)
+}

package/src/worklets/index.ts

@@ -0,0 +1,4 @@
+export { isNarsilError, type PhoneNarsilError } from '../errors'
+export type { PhoneEventHandler, PhoneNarsil } from '../types'
+export { createNarsil } from './client'
+export type { EngineSetup, WorkletNarsilConfig } from './types'

package/src/worklets/instances.ts

@@ -0,0 +1,231 @@
+import {
+  createNarsil,
+  ErrorCodes,
+  type Narsil,
+  type NarsilConfig,
+  NarsilError,
+  type NarsilEventMap,
+} from '@delali/narsil'
+import { scheduleOnRN } from 'react-native-worklets'
+import { installedHost } from '../engine/install'
+import { callStreamed, withPhoneDurability } from '../engine/streamed'
+import { transferable, transferredError } from '../engine/transfer'
+import { type EngineMethod, FORWARDED_METHODS, STREAMED_METHODS, type StreamedMethod } from '../methods'
+import type { CallOutcome } from '../transferred'
+import type { EngineSetup, WorkletNarsilConfig } from './types'
+
+type Settle = (callId: number, outcome: CallOutcome) => void
+type DeliverEvent = (instanceId: number, event: EventName, payload: unknown) => void
+type EventName = keyof NarsilEventMap
+
+interface OpenInstance {
+  narsil: Narsil
+  listeners: Map<EventName, (payload: unknown) => void>
+}
+
+interface EngineStart {
+  failed: boolean
+  error: unknown
+}
+
+const FORWARDED = new Set<string>(FORWARDED_METHODS)
+const STREAMED = new Set<string>(STREAMED_METHODS)
+const UNDELIVERABLE_OUTCOME: CallOutcome = {
+  ok: false,
+  error: {
+    transferredError: true,
+    name: 'Error',
+    message: "The engine's runtime could not send this call's outcome back to the app",
+    code: undefined,
+    details: undefined,
+  },
+}
+const instances = new Map<number, OpenInstance>()
+const stagedParts = new Map<number, Map<number, unknown[]>>()
+const failedCalls = new Map<number, unknown>()
+const engineStart: EngineStart = { failed: false, error: undefined }
+let nextInstanceId = 1
+
+function instanceOf(instanceId: number): OpenInstance {
+  const instance = instances.get(instanceId)
+  if (instance === undefined) {
+    throw new NarsilError(ErrorCodes.INSTANCE_SHUT_DOWN, 'This Narsil instance has been shut down')
+  }
+  return instance
+}
+
+function failureOf(error: unknown): CallOutcome {
+  return { ok: false, error: transferredError(error) }
+}
+
+function deliver(settle: Settle, callId: number, outcome: () => CallOutcome): void {
+  try {
+    scheduleOnRN(settle, callId, outcome())
+    return
+  } catch (error) {
+    try {
+      scheduleOnRN(settle, callId, failureOf(error))
+      return
+    } catch {}
+  }
+  try {
+    scheduleOnRN(settle, callId, UNDELIVERABLE_OUTCOME)
+  } catch {}
+}
+
+function report(settle: Settle, callId: number, work: () => Promise<unknown>): void {
+  let pending: Promise<unknown>
+  try {
+    pending = work()
+  } catch (error) {
+    deliver(settle, callId, () => failureOf(error))
+    return
+  }
+  pending.then(
+    value => deliver(settle, callId, () => ({ ok: true, value: transferable(value) })),
+    error => deliver(settle, callId, () => failureOf(error)),
+  )
+}
+
+export function recordEngineStartFailure(error: unknown): void {
+  engineStart.failed = true
+  engineStart.error = error
+}
+
+async function openInstance(config: WorkletNarsilConfig, setup: EngineSetup | undefined): Promise<number> {
+  if (engineStart.failed) throw engineStart.error
+  const fromSetup = setup === undefined ? {} : await setup()
+  const merged: NarsilConfig = { ...withPhoneDurability(config, fromSetup.durability !== undefined), ...fromSetup }
+  const narsil = await createNarsil(merged)
+  const instanceId = nextInstanceId++
+  instances.set(instanceId, { narsil, listeners: new Map() })
+  return instanceId
+}
+
+async function shutdown(instanceId: number): Promise<void> {
+  const instance = instances.get(instanceId)
+  if (instance === undefined) return
+  instances.delete(instanceId)
+  for (const [event, listener] of instance.listeners) instance.narsil.off(event, listener)
+  instance.listeners.clear()
+  await instance.narsil.shutdown()
+}
+
+function dispatch(instanceId: number, method: EngineMethod, args: readonly unknown[]): Promise<unknown> {
+  if (method === 'shutdown') return shutdown(instanceId)
+  const { narsil } = instanceOf(instanceId)
+  if (FORWARDED.has(method)) {
+    const target = narsil[method as keyof Narsil] as (...values: unknown[]) => unknown
+    return Promise.resolve(target.apply(narsil, [...args]))
+  }
+  if (!STREAMED.has(method)) throw new TypeError(`The Narsil engine has no method called ${String(method)}`)
+  return callStreamed(narsil, installedHost(), method as StreamedMethod, args)
+}
+
+export function openOnEngine(
+  callId: number,
+  settle: Settle,
+  config: WorkletNarsilConfig,
+  setup: EngineSetup | undefined,
+): void {
+  report(settle, callId, () => openInstance(config, setup))
+}
+
+function failCall(callId: number, error: unknown): void {
+  stagedParts.delete(callId)
+  failedCalls.set(callId, error)
+}
+
+function stageItems(callId: number, argIndex: number, items: unknown): void {
+  if (!Array.isArray(items)) throw new TypeError('A part of a call reached the engine without its items')
+  let parts = stagedParts.get(callId)
+  if (parts === undefined) {
+    parts = new Map()
+    stagedParts.set(callId, parts)
+  }
+  let staged = parts.get(argIndex)
+  if (staged === undefined) {
+    staged = []
+    parts.set(argIndex, staged)
+  }
+  for (const item of items) staged.push(item)
+}
+
+export function stageCallPart(callId: number, argIndex: number, items: readonly unknown[]): void {
+  if (failedCalls.has(callId)) return
+  try {
+    stageItems(callId, argIndex, items)
+  } catch (error) {
+    failCall(callId, error)
+  }
+}
+
+export function stageCallPartText(callId: number, argIndex: number, text: string): void {
+  if (failedCalls.has(callId)) return
+  try {
+    stageItems(callId, argIndex, JSON.parse(text))
+  } catch (error) {
+    failCall(callId, error)
+  }
+}
+
+export function dropCallParts(callId: number): void {
+  stagedParts.delete(callId)
+  failedCalls.delete(callId)
+}
+
+function withStagedParts(callId: number, args: readonly unknown[], partedArgs: readonly number[]): unknown[] {
+  const parts = stagedParts.get(callId)
+  const failure = failedCalls.get(callId)
+  stagedParts.delete(callId)
+  if (failedCalls.delete(callId)) throw failure
+  const values = [...args]
+  for (const argIndex of partedArgs) values[argIndex] = parts?.get(argIndex) ?? []
+  return values
+}
+
+export function callOnEngine(
+  callId: number,
+  settle: Settle,
+  instanceId: number,
+  method: EngineMethod,
+  args: readonly unknown[],
+  partedArgs: readonly number[],
+): void {
+  report(settle, callId, () =>
+    dispatch(instanceId, method, partedArgs.length === 0 ? args : withStagedParts(callId, args, partedArgs)),
+  )
+}
+
+function forwardEvent(forward: DeliverEvent, instanceId: number, event: EventName, payload: unknown): void {
+  try {
+    scheduleOnRN(forward, instanceId, event, transferable(payload))
+  } catch {}
+}
+
+function changeListener(instanceId: number, event: EventName, forward: DeliverEvent, listening: boolean): void {
+  const instance = instances.get(instanceId)
+  if (instance === undefined) return
+  const existing = instance.listeners.get(event)
+  if (!listening) {
+    if (existing === undefined) return
+    instance.listeners.delete(event)
+    instance.narsil.off(event, existing)
+    return
+  }
+  if (existing !== undefined) return
+  const listener = (payload: unknown) => forwardEvent(forward, instanceId, event, payload)
+  instance.listeners.set(event, listener)
+  try {
+    instance.narsil.on(event, listener)
+  } catch (error) {
+    instance.listeners.delete(event)
+    throw error
+  }
+}
+
+export function listenOnEngine(instanceId: number, event: EventName, forward: DeliverEvent, listening: boolean): void {
+  try {
+    changeListener(instanceId, event, forward, listening)
+  } catch {}
+}

package/src/worklets/json-part.ts

@@ -0,0 +1,38 @@
+import { WORKLET_JSON_PART_MAX_DEPTH } from '../constants'
+
+function encodesExactly(value: unknown, depth: number): boolean {
+  switch (typeof value) {
+    case 'string':
+    case 'boolean':
+      return true
+    case 'number':
+      return Number.isFinite(value) && !Object.is(value, -0)
+    case 'object':
+      break
+    default:
+      return false
+  }
+  if (value === null) return true
+  if (depth >= WORKLET_JSON_PART_MAX_DEPTH) return false
+  const prototype = Object.getPrototypeOf(value)
+  if (prototype === Array.prototype) {
+    const items = value as readonly unknown[]
+    for (let index = 0; index < items.length; index++) {
+      if (!(index in items) || !encodesExactly(items[index], depth + 1)) return false
+    }
+    return true
+  }
+  if (prototype !== Object.prototype && prototype !== null) return false
+  const record = value as Record<string, unknown>
+  for (const key of Object.keys(record)) {
+    if (!encodesExactly(record[key], depth + 1)) return false
+  }
+  return true
+}
+
+export function jsonOfPart(items: readonly unknown[]): string | null {
+  for (const item of items) {
+    if (!encodesExactly(item, 1)) return null
+  }
+  return JSON.stringify(items)
+}