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

package/lib/errors.js

@@ -0,0 +1,59 @@
+import { isTransferredError } from './transferred';
+const NARSIL_ERROR_MARKER = Symbol.for('@delali/narsil.NarsilError');
+const NARSIL_ERROR_NAME = 'NarsilError';
+const NATIVE_DEPENDENCY_MISSING = 'NATIVE_DEPENDENCY_MISSING';
+const NATIVE_DEPENDENCY_MISSING_MESSAGE = 'This app build does not include the Narsil native module, as happens in Expo Go and on 32-bit Android. Install `@delali/narsil-react-native` and `react-native-nitro-modules`, then make a development build with `npx expo run:ios` or `npx expo run:android`, or, in an app without Expo, run `pod install` in the `ios` folder and rebuild the app for each platform.';
+/**
+ * Reports whether a value is an error that the Narsil engine raised, whether
+ * it reached the app from the engine's runtime or from this package.
+ *
+ * @param value - Anything that a rejected promise or a `catch` block holds.
+ * @returns True when the value carries a Narsil error code.
+ *
+ * @public
+ */
+export function isNarsilError(value) {
+    return typeof value === 'object' && value !== null && NARSIL_ERROR_MARKER in value;
+}
+function narsilError(message, code, details) {
+    const error = new Error(message);
+    error.name = NARSIL_ERROR_NAME;
+    Object.defineProperty(error, 'code', { value: code, enumerable: true });
+    Object.defineProperty(error, 'details', { value: details, enumerable: true });
+    Object.defineProperty(error, NARSIL_ERROR_MARKER, { value: true });
+    return error;
+}
+export function nativeDependencyMissing(cause) {
+    return narsilError(NATIVE_DEPENDENCY_MISSING_MESSAGE, NATIVE_DEPENDENCY_MISSING, {
+        cause: cause instanceof Error ? cause.message : String(cause),
+    });
+}
+export function rebuiltError(transferred) {
+    const details = rebuiltValue(transferred.details);
+    if (transferred.name === NARSIL_ERROR_NAME && transferred.code !== undefined) {
+        const record = typeof details === 'object' && details !== null ? details : {};
+        return narsilError(transferred.message, transferred.code, record);
+    }
+    const error = new Error(transferred.message);
+    error.name = transferred.name;
+    if (transferred.code !== undefined)
+        Object.defineProperty(error, 'code', { value: transferred.code, enumerable: true });
+    if (details !== undefined)
+        Object.defineProperty(error, 'details', { value: details, enumerable: true });
+    return error;
+}
+export function rebuiltValue(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (isTransferredError(value))
+        return rebuiltError(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+        return value;
+    if (Array.isArray(value))
+        return value.map(rebuiltValue);
+    const record = {};
+    for (const key of Object.keys(value))
+        record[key] = rebuiltValue(value[key]);
+    return record;
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { createNarsil } from './client';
+export { isNarsilError, type PhoneNarsilError } from './errors';
+export type { PhoneEventHandler, PhoneNarsil, PhoneNarsilConfig } from './types';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { createNarsil } from './client';
+export { isNarsilError } from './errors';

package/lib/methods.d.ts

@@ -0,0 +1,5 @@
+export declare const FORWARDED_METHODS: readonly ["createIndex", "dropIndex", "listIndexes", "getStats", "getPartitionStats", "get", "getMultiple", "has", "countDocuments", "listDocuments", "query", "preflight", "suggest", "rebuildAnalysis", "restore", "importDocumentExport", "checkpoint", "clear", "rebalance", "updatePartitionConfig", "getMemoryStats", "compactVectors", "optimizeVectors", "vectorMaintenanceStatus", "open", "close", "insert", "insertBatch", "remove", "removeBatch", "update", "updateBatch", "waitForWrites", "updateSynonyms", "getSynonyms", "changeAnalysis", "updateBM25"];
+export declare const STREAMED_METHODS: readonly ["snapshot", "exportDocuments", "snapshotToFile", "exportDocumentsToFile", "restoreFromFile", "importDocumentExportFromFile"];
+export type ForwardedMethod = (typeof FORWARDED_METHODS)[number];
+export type StreamedMethod = (typeof STREAMED_METHODS)[number];
+export type EngineMethod = ForwardedMethod | StreamedMethod | 'shutdown';

package/lib/methods.js

@@ -0,0 +1,47 @@
+export const FORWARDED_METHODS = [
+    'createIndex',
+    'dropIndex',
+    'listIndexes',
+    'getStats',
+    'getPartitionStats',
+    'get',
+    'getMultiple',
+    'has',
+    'countDocuments',
+    'listDocuments',
+    'query',
+    'preflight',
+    'suggest',
+    'rebuildAnalysis',
+    'restore',
+    'importDocumentExport',
+    'checkpoint',
+    'clear',
+    'rebalance',
+    'updatePartitionConfig',
+    'getMemoryStats',
+    'compactVectors',
+    'optimizeVectors',
+    'vectorMaintenanceStatus',
+    'open',
+    'close',
+    'insert',
+    'insertBatch',
+    'remove',
+    'removeBatch',
+    'update',
+    'updateBatch',
+    'waitForWrites',
+    'updateSynonyms',
+    'getSynonyms',
+    'changeAnalysis',
+    'updateBM25',
+];
+export const STREAMED_METHODS = [
+    'snapshot',
+    'exportDocuments',
+    'snapshotToFile',
+    'exportDocumentsToFile',
+    'restoreFromFile',
+    'importDocumentExportFromFile',
+];

package/lib/native-objects.d.ts

@@ -0,0 +1,2 @@
+import type { NativeObjects } from './engine/host';
+export declare function loadNativeObjects(): Promise<NativeObjects>;

package/lib/native-objects.js

@@ -0,0 +1,24 @@
+import { nativeDependencyMissing } from './errors';
+let loading = null;
+async function createNativeObjects() {
+    try {
+        const { NitroModules } = await import('react-native-nitro-modules');
+        return {
+            host: NitroModules.createHybridObject('NarsilHost'),
+            files: NitroModules.createHybridObject('NarsilFiles'),
+            core: NitroModules.createHybridObject('NarsilCore'),
+        };
+    }
+    catch (error) {
+        throw nativeDependencyMissing(error);
+    }
+}
+export function loadNativeObjects() {
+    if (loading === null) {
+        loading = createNativeObjects();
+        loading.catch(() => {
+            loading = null;
+        });
+    }
+    return loading;
+}

package/lib/specs/core.nitro.d.ts

@@ -0,0 +1,79 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+export interface MemoryView {
+    buffer: ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+}
+export interface GraphMemory {
+    graphHeader: MemoryView;
+    nodeLevels: MemoryView;
+    level0: MemoryView;
+    upperBase: MemoryView;
+    upper: MemoryView;
+    locks: MemoryView;
+    tombstones: MemoryView;
+    incoming: MemoryView;
+    nearestLinkDue: MemoryView;
+    heldLocks: MemoryView;
+}
+export interface StoreMemory {
+    storeHeader: MemoryView;
+    dimension: number;
+    bits: number;
+    recordsPerBlock: number;
+    vectorsPerBlock: number;
+    vectorStrideBytes: number;
+    codePresent: MemoryView;
+    centroid: MemoryView;
+    magnitudes: MemoryView;
+    present: MemoryView;
+    vectorFile: MemoryView;
+    vectorOffset: MemoryView;
+    vectorFiles: string[];
+    codeBlocks: MemoryView[];
+    vectorBlocks: MemoryView[];
+}
+export interface NativeSearchHits {
+    count: number;
+    ordinals: ArrayBuffer;
+    distances: ArrayBuffer;
+}
+export interface NativeScores {
+    status: number;
+    distances: ArrayBuffer;
+}
+export interface NativeConnectOutcome {
+    status: number;
+    wakes: ArrayBuffer;
+}
+export interface NarsilAttachedGraph extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+}
+export interface NarsilAttachedStore extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    detach(): number;
+}
+export interface NarsilCore extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    abiVersion(): number;
+    workspaceBytes(): number;
+    attachGraph(memory: GraphMemory): NarsilAttachedGraph;
+    attachStore(memory: StoreMemory): NarsilAttachedStore;
+    search(graph: NarsilAttachedGraph, store: NarsilAttachedStore, query: MemoryView, metric: number, candidateCount: number, threadSlot: number, ordinals: MemoryView, distances: MemoryView, accepted: MemoryView, filtered: boolean): number;
+    searchAsync(graph: NarsilAttachedGraph, store: NarsilAttachedStore, query: MemoryView, metric: number, candidateCount: number, threadSlot: number, accepted: MemoryView, filtered: boolean): Promise<NativeSearchHits>;
+    scoreAsync(store: NarsilAttachedStore, query: MemoryView, metric: number, ordinals: MemoryView, count: number, threadSlot: number): Promise<NativeScores>;
+    score(store: NarsilAttachedStore, query: MemoryView, metric: number, ordinals: MemoryView, count: number, distances: MemoryView): number;
+    place(graph: NarsilAttachedGraph, store: NarsilAttachedStore, metric: number, ordinal: number, topLayer: number, graphHeldAlone: number, threadSlot: number, wakes: MemoryView): number;
+    remove(graph: NarsilAttachedGraph, ordinal: number, threadSlot: number, wakes: MemoryView): number;
+    compact(graph: NarsilAttachedGraph, store: NarsilAttachedStore, metric: number, threadSlot: number, wakes: MemoryView): number;
+    connectUnreached(graph: NarsilAttachedGraph, store: NarsilAttachedStore, metric: number, nearby: MemoryView, threadSlot: number, wakes: MemoryView): number;
+    connectUnreachedAsync(graph: NarsilAttachedGraph, store: NarsilAttachedStore, metric: number, nearby: MemoryView, threadSlot: number): Promise<NativeConnectOutcome>;
+    measure(store: NarsilAttachedStore, metric: number, ordinals: MemoryView, count: number, totals: MemoryView): number;
+    quantise(store: NarsilAttachedStore, metric: number, ordinals: MemoryView, count: number): number;
+}

package/lib/specs/core.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/specs/files.nitro.d.ts

@@ -0,0 +1,36 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+export interface FileStatus {
+    size: number;
+    isDirectory: boolean;
+    isFile: boolean;
+    device: string;
+    inode: string;
+    modifiedMs: number;
+}
+export interface DirectoryEntry {
+    name: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+export interface NarsilFiles extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    open(path: string, flags: string): number;
+    close(descriptor: number): void;
+    read(descriptor: number, target: ArrayBuffer, byteOffset: number, byteLength: number, position: number): number;
+    write(descriptor: number, source: ArrayBuffer, byteOffset: number, byteLength: number, position: number): number;
+    sync(descriptor: number): void;
+    readAsync(descriptor: number, byteLength: number, position: number): Promise<ArrayBuffer>;
+    writeAsync(descriptor: number, source: ArrayBuffer, byteOffset: number, byteLength: number, position: number): Promise<number>;
+    syncAsync(descriptor: number): Promise<void>;
+    truncate(descriptor: number, byteLength: number): void;
+    descriptorStatus(descriptor: number): FileStatus;
+    pathStatus(path: string): FileStatus;
+    makeDirectory(path: string): void;
+    readDirectory(path: string): DirectoryEntry[];
+    rename(from: string, to: string): void;
+    unlink(path: string): void;
+    removeDirectory(path: string): void;
+    link(existingPath: string, newPath: string): void;
+}

package/lib/specs/files.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/specs/host.nitro.d.ts

@@ -0,0 +1,24 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+export interface ProcessMemory {
+    residentBytes: number;
+    availableBytes: number;
+}
+export interface NarsilHost extends HybridObject<{
+    ios: 'c++';
+    android: 'c++';
+}> {
+    reserveMemory(bytes: number): ArrayBuffer;
+    allocateMemory(bytes: number): ArrayBuffer;
+    ownsMemory(buffer: ArrayBuffer): boolean;
+    atomic(operation: number, elementKind: number, buffer: ArrayBuffer, byteIndex: number, value: number, replacement: number): number;
+    fillRandom(target: ArrayBuffer, byteOffset: number, byteLength: number): void;
+    processId(): number;
+    processStartedAtMs(): number;
+    processIsAlive(processId: number): boolean;
+    processMemory(): ProcessMemory;
+    appStorageDirectory(): string;
+    deflateRaw(source: ArrayBuffer, byteOffset: number, byteLength: number): ArrayBuffer;
+    inflateRaw(source: ArrayBuffer, byteOffset: number, byteLength: number, rawByteLength: number): ArrayBuffer;
+    gzip(source: ArrayBuffer, byteOffset: number, byteLength: number): ArrayBuffer;
+    gunzip(source: ArrayBuffer, byteOffset: number, byteLength: number, maxByteLength: number): ArrayBuffer;
+}

package/lib/specs/host.nitro.js

@@ -0,0 +1 @@
+export {};

package/lib/transferred.d.ts

@@ -0,0 +1,15 @@
+export interface TransferredError {
+    transferredError: true;
+    name: string;
+    message: string;
+    code: string | undefined;
+    details: unknown;
+}
+export type CallOutcome = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: TransferredError;
+};
+export declare function isTransferredError(value: unknown): value is TransferredError;

package/lib/transferred.js

@@ -0,0 +1,6 @@
+export function isTransferredError(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.transferredError === true &&
+        typeof value.message === 'string');
+}

package/lib/types.d.ts

@@ -0,0 +1,136 @@
+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/lib/types.js

@@ -0,0 +1 @@
+export {};

package/lib/worklets/app-turns.d.ts

@@ -0,0 +1 @@
+export declare function afterAppTurn(run: () => void): void;

package/lib/worklets/app-turns.js

@@ -0,0 +1,44 @@
+import { APP_TIMER_WAIT_BEFORE_RUN_LOOP_HOP_MS } from '../constants';
+function hopThroughRuntimeScheduler() {
+    const runtimeScheduler = Reflect.get(globalThis, 'nativeRuntimeScheduler');
+    if (typeof runtimeScheduler !== 'object' || runtimeScheduler === null)
+        return null;
+    const schedule = Reflect.get(runtimeScheduler, 'unstable_scheduleCallback');
+    const priority = Reflect.get(runtimeScheduler, 'unstable_NormalPriority');
+    if (typeof schedule !== 'function' || typeof priority !== 'number')
+        return null;
+    let appTimerArmedAt = null;
+    let runsAfterAppTimer = [];
+    function appTimerFired() {
+        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) {
+    setTimeout(run, 0);
+}
+let hop = null;
+export function afterAppTurn(run) {
+    hop ??= hopThroughRuntimeScheduler() ?? hopThroughTimer;
+    hop(run);
+}

package/lib/worklets/client.d.ts

@@ -0,0 +1,30 @@
+import type { PhoneNarsil } from '../types';
+import type { EngineSetup, WorkletNarsilConfig } from './types';
+/**
+ * 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 declare function createNarsil(config?: WorkletNarsilConfig, setup?: EngineSetup): Promise<PhoneNarsil>;