@delali/narsil 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1099 @@
+import { createDirectExecutor, fanOutQuery, tokenize, validateSchema, getLanguage } from './chunk-5HXMVMSM.mjs';
+export { getLanguage, registerLanguage } from './chunk-5HXMVMSM.mjs';
+import './chunk-WYC635GI.mjs';
+import { NarsilError, ErrorCodes } from './chunk-JKIBUPAY.mjs';
+export { ErrorCodes, NarsilError } from './chunk-JKIBUPAY.mjs';
+import { generateId } from './chunk-N37VMC62.mjs';
+
+// src/highlighting/highlighter.ts
+function buildTokenCharOffsets(text, originalTokens) {
+  const offsets = [];
+  let searchFrom = 0;
+  for (const token of originalTokens) {
+    const idx = text.indexOf(token, searchFrom);
+    if (idx === -1) continue;
+    offsets.push({ start: idx, end: idx + token.length });
+    searchFrom = idx + token.length;
+  }
+  return offsets;
+}
+function mergeOverlapping(ranges) {
+  if (ranges.length === 0) return [];
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  const merged = [sorted[0]];
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = merged[merged.length - 1];
+    const curr = sorted[i];
+    if (curr.start <= prev.end) {
+      prev.end = Math.max(prev.end, curr.end);
+    } else {
+      merged.push(curr);
+    }
+  }
+  return merged;
+}
+function findDensestWindow(positions, text, windowSize) {
+  if (positions.length === 0) {
+    return { start: 0, end: Math.min(windowSize, text.length) };
+  }
+  let bestStart = 0;
+  let bestCount = 0;
+  for (const pos of positions) {
+    const windowStart = Math.max(0, pos.start - Math.floor(windowSize / 2));
+    const windowEnd = Math.min(text.length, windowStart + windowSize);
+    const adjustedStart = Math.max(0, windowEnd - windowSize);
+    let count = 0;
+    for (const p of positions) {
+      if (p.start >= adjustedStart && p.end <= windowEnd) {
+        count++;
+      }
+    }
+    if (count > bestCount) {
+      bestCount = count;
+      bestStart = adjustedStart;
+    }
+  }
+  return { start: bestStart, end: Math.min(text.length, bestStart + windowSize) };
+}
+function applySnippetTruncation(taggedText, originalText, positions, maxLen, preTag, postTag) {
+  if (maxLen <= 0 || originalText.length <= maxLen) {
+    return { snippet: taggedText, adjustedPositions: positions };
+  }
+  const window = findDensestWindow(positions, originalText, maxLen);
+  const snippetRaw = originalText.substring(window.start, window.end);
+  const adjustedPositions = [];
+  for (const pos of positions) {
+    if (pos.start >= window.start && pos.end <= window.end) {
+      adjustedPositions.push({
+        start: pos.start - window.start,
+        end: pos.end - window.start
+      });
+    }
+  }
+  let snippet = snippetRaw;
+  const sortedDesc = [...adjustedPositions].sort((a, b) => b.start - a.start);
+  for (const pos of sortedDesc) {
+    snippet = snippet.substring(0, pos.start) + preTag + snippet.substring(pos.start, pos.end) + postTag + snippet.substring(pos.end);
+  }
+  const needsLeadingEllipsis = window.start > 0;
+  const needsTrailingEllipsis = window.end < originalText.length;
+  if (needsLeadingEllipsis) snippet = `...${snippet}`;
+  if (needsTrailingEllipsis) snippet = `${snippet}...`;
+  return { snippet, adjustedPositions };
+}
+function highlightField(text, queryTokens, language, options) {
+  const preTag = options?.preTag ?? "<mark>";
+  const postTag = options?.postTag ?? "</mark>";
+  const maxSnippetLength = options?.maxSnippetLength ?? 200;
+  if (text.length === 0) {
+    return { snippet: text, positions: [] };
+  }
+  const fieldResult = tokenize(text, language, { stem: false, removeStopWords: false });
+  if (fieldResult.tokens.length === 0) {
+    return { snippet: text, positions: [] };
+  }
+  const lowercaseText = text.normalize("NFC").toLowerCase();
+  const charOffsets = buildTokenCharOffsets(lowercaseText, fieldResult.originalTokens);
+  const stemmedQueryTokens = queryTokens.map((qt) => {
+    if (language.stemmer) {
+      return language.stemmer(qt.token.toLowerCase());
+    }
+    return qt.token.toLowerCase();
+  });
+  const matchedRanges = [];
+  for (let i = 0; i < fieldResult.tokens.length; i++) {
+    if (i >= charOffsets.length) break;
+    const fieldToken = fieldResult.tokens[i].token;
+    const stemmedField = language.stemmer ? language.stemmer(fieldToken) : fieldToken;
+    for (const stemmedQuery of stemmedQueryTokens) {
+      if (stemmedField === stemmedQuery) {
+        matchedRanges.push({ start: charOffsets[i].start, end: charOffsets[i].end });
+        break;
+      }
+    }
+  }
+  const mergedPositions = mergeOverlapping(matchedRanges);
+  if (mergedPositions.length === 0) {
+    if (maxSnippetLength > 0 && text.length > maxSnippetLength) {
+      const truncated = text.substring(0, maxSnippetLength);
+      return { snippet: `${truncated}...`, positions: [] };
+    }
+    return { snippet: text, positions: [] };
+  }
+  if (maxSnippetLength > 0 && text.length > maxSnippetLength) {
+    const { snippet, adjustedPositions } = applySnippetTruncation(
+      text,
+      text,
+      mergedPositions,
+      maxSnippetLength,
+      preTag,
+      postTag
+    );
+    return { snippet, positions: adjustedPositions };
+  }
+  let result = text;
+  const sortedDesc = [...mergedPositions].sort((a, b) => b.start - a.start);
+  for (const pos of sortedDesc) {
+    result = result.substring(0, pos.start) + preTag + result.substring(pos.start, pos.end) + postTag + result.substring(pos.end);
+  }
+  return { snippet: result, positions: mergedPositions };
+}
+
+// src/persistence/flush-manager.ts
+var DEFAULT_INTERVAL = 5e3;
+var DEFAULT_MUTATION_THRESHOLD = 1e3;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_BASE_RETRY_DELAY = 100;
+function createFlushManager(config, getPartitionData, getInstanceId) {
+  const {
+    persistence,
+    invalidation,
+    interval = DEFAULT_INTERVAL,
+    mutationThreshold = DEFAULT_MUTATION_THRESHOLD,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    baseRetryDelay = DEFAULT_BASE_RETRY_DELAY,
+    onError
+  } = config;
+  const dirtyPartitions = /* @__PURE__ */ new Map();
+  let mutationCount = 0;
+  let flushTimerId = null;
+  let isShuttingDown = false;
+  let flushPromise = null;
+  function startTimer() {
+    if (flushTimerId !== null || isShuttingDown) {
+      return;
+    }
+    flushTimerId = setInterval(() => {
+      flush();
+    }, interval);
+  }
+  function addToDirtySet(indexName, partitionId) {
+    let partitions = dirtyPartitions.get(indexName);
+    if (partitions === void 0) {
+      partitions = /* @__PURE__ */ new Set();
+      dirtyPartitions.set(indexName, partitions);
+    }
+    partitions.add(partitionId);
+  }
+  function snapshotAndClearDirty() {
+    const snapshot = /* @__PURE__ */ new Map();
+    for (const [indexName, partitions] of dirtyPartitions) {
+      snapshot.set(indexName, new Set(partitions));
+    }
+    dirtyPartitions.clear();
+    return snapshot;
+  }
+  async function saveWithRetry(indexName, partitionId) {
+    const key = `${indexName}/${partitionId}`;
+    const data = getPartitionData(indexName, partitionId);
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        await persistence.save(key, data);
+        return true;
+      } catch (err) {
+        const isLastAttempt = attempt === maxRetries - 1;
+        if (isLastAttempt) {
+          onError?.(indexName, partitionId, err, true);
+          return false;
+        }
+        const cappedAttempt = Math.min(attempt, 20);
+        const delay = baseRetryDelay * 2 ** cappedAttempt * (0.5 + Math.random() * 0.5);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    return false;
+  }
+  async function performFlush() {
+    const snapshot = snapshotAndClearDirty();
+    for (const [indexName, partitions] of snapshot) {
+      const succeededPartitions = [];
+      for (const partitionId of partitions) {
+        const saved = await saveWithRetry(indexName, partitionId);
+        if (saved) {
+          succeededPartitions.push(partitionId);
+        } else {
+          addToDirtySet(indexName, partitionId);
+        }
+      }
+      if (succeededPartitions.length > 0) {
+        await invalidation.publish({
+          type: "partition",
+          indexName,
+          partitions: succeededPartitions,
+          timestamp: Date.now(),
+          sourceInstanceId: getInstanceId()
+        });
+      }
+    }
+    mutationCount = 0;
+  }
+  function flush() {
+    if (flushPromise !== null) {
+      return flushPromise;
+    }
+    flushPromise = performFlush().finally(() => {
+      flushPromise = null;
+    });
+    return flushPromise;
+  }
+  function markDirty(indexName, partitionId) {
+    if (isShuttingDown) return;
+    addToDirtySet(indexName, partitionId);
+    mutationCount++;
+    if (mutationCount >= mutationThreshold) {
+      flush();
+    }
+    startTimer();
+  }
+  async function shutdown() {
+    isShuttingDown = true;
+    if (flushTimerId !== null) {
+      clearInterval(flushTimerId);
+      flushTimerId = null;
+    }
+    await flush();
+  }
+  return {
+    markDirty,
+    flush,
+    shutdown
+  };
+}
+
+// src/plugins/registry.ts
+function isThenable(value) {
+  return value !== null && typeof value === "object" && typeof value.then === "function";
+}
+async function continueAsync(pending, hooks, startIndex, context) {
+  await pending;
+  for (let i = startIndex; i < hooks.length; i++) {
+    await hooks[i](context);
+  }
+}
+function createPluginRegistry() {
+  const plugins = [];
+  return {
+    register(plugin) {
+      plugins.push(plugin);
+    },
+    runHook(hookName, context) {
+      const hooks = [];
+      for (const plugin of plugins) {
+        const hook = plugin[hookName];
+        if (typeof hook === "function") {
+          hooks.push(hook.bind(plugin));
+        }
+      }
+      if (hooks.length === 0) return;
+      for (let i = 0; i < hooks.length; i++) {
+        const result = hooks[i](context);
+        if (isThenable(result)) {
+          return continueAsync(result, hooks, i + 1, context);
+        }
+      }
+    }
+  };
+}
+
+// src/search/grouping.ts
+function getNestedValue(obj, path) {
+  const segments = path.split(".");
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    if (!Object.hasOwn(current, segment)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function applyGrouping(hits, group, getDocument) {
+  if (!group.fields || group.fields.length === 0) {
+    return [{ values: {}, hits }];
+  }
+  const groupMap = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    const doc = getDocument(hit.id);
+    const fieldValues = [];
+    const valuesRecord = {};
+    for (const field of group.fields) {
+      const value = doc ? getNestedValue(doc, field) : void 0;
+      fieldValues.push(value);
+      valuesRecord[field] = value;
+    }
+    const compositeKey = JSON.stringify(fieldValues);
+    const existing = groupMap.get(compositeKey);
+    if (existing) {
+      existing.hits.push(hit);
+    } else {
+      groupMap.set(compositeKey, { values: valuesRecord, hits: [hit] });
+    }
+  }
+  const groups = [];
+  for (const entry of groupMap.values()) {
+    let groupHits = entry.hits;
+    if (group.maxPerGroup !== void 0 && group.maxPerGroup > 0) {
+      groupHits = groupHits.slice(0, group.maxPerGroup);
+    }
+    const result = { values: entry.values, hits: groupHits };
+    if (group.reduce) {
+      try {
+        let accumulator = group.reduce.initialValue();
+        for (const hit of groupHits) {
+          const doc = getDocument(hit.id);
+          if (doc) {
+            accumulator = group.reduce.reducer(accumulator, doc, hit.score);
+          }
+        }
+        ;
+        result.reduced = accumulator;
+      } catch (err) {
+        result.reducerError = err instanceof Error ? err.message : String(err);
+      }
+    }
+    groups.push(result);
+  }
+  groups.sort((a, b) => {
+    const aScore = a.hits.length > 0 ? a.hits[0].score : 0;
+    const bScore = b.hits.length > 0 ? b.hits[0].score : 0;
+    return bScore - aScore;
+  });
+  return groups;
+}
+
+// src/search/pagination.ts
+function encodeCursor(state) {
+  const json = JSON.stringify(state);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json).toString("base64");
+  }
+  return btoa(json);
+}
+function decodeCursor(encoded) {
+  let json;
+  try {
+    if (typeof Buffer !== "undefined") {
+      json = Buffer.from(encoded, "base64").toString("utf-8");
+    } else {
+      json = atob(encoded);
+    }
+  } catch {
+    throw new NarsilError(ErrorCodes.SEARCH_INVALID_CURSOR, "Failed to decode cursor: invalid base64 encoding", {
+      cursor: encoded
+    });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    throw new NarsilError(ErrorCodes.SEARCH_INVALID_CURSOR, "Failed to decode cursor: invalid JSON", {
+      cursor: encoded
+    });
+  }
+  if (!Array.isArray(parsed)) {
+    throw new NarsilError(ErrorCodes.SEARCH_INVALID_CURSOR, "Invalid cursor structure: expected an array", {
+      cursor: encoded
+    });
+  }
+  for (let i = 0; i < parsed.length; i++) {
+    const entry = parsed[i];
+    if (typeof entry !== "object" || entry === null) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_CURSOR,
+        `Invalid cursor entry at index ${i}: expected an object`,
+        {
+          cursor: encoded,
+          index: i
+        }
+      );
+    }
+    const { s, d, p } = entry;
+    if (typeof s !== "number" || !Number.isFinite(s)) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_CURSOR,
+        `Invalid cursor entry at index ${i}: "s" must be a finite number`,
+        { cursor: encoded, index: i }
+      );
+    }
+    if (typeof d !== "string") {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_CURSOR,
+        `Invalid cursor entry at index ${i}: "d" must be a string`,
+        { cursor: encoded, index: i }
+      );
+    }
+    if (typeof p !== "number" || !Number.isInteger(p) || p < 0) {
+      throw new NarsilError(
+        ErrorCodes.SEARCH_INVALID_CURSOR,
+        `Invalid cursor entry at index ${i}: "p" must be a non-negative integer`,
+        { cursor: encoded, index: i }
+      );
+    }
+  }
+  return parsed;
+}
+function applyPagination(results, limit, offset, cursor) {
+  if (limit <= 0) {
+    return { paginated: [] };
+  }
+  let startIndex = 0;
+  if (cursor) {
+    const cursorState = decodeCursor(cursor);
+    const anchor = cursorState[0];
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      if (result.score < anchor.s || result.score === anchor.s && result.id > anchor.d) {
+        startIndex = i;
+        break;
+      }
+      if (i === results.length - 1) {
+        startIndex = results.length;
+      }
+    }
+  }
+  const afterOffset = startIndex + offset;
+  const sliced = results.slice(afterOffset, afterOffset + limit);
+  let nextCursor;
+  const hasMore = afterOffset + limit < results.length;
+  if (hasMore && sliced.length > 0) {
+    const lastResult = sliced[sliced.length - 1];
+    const cursorState = [{ s: lastResult.score, d: lastResult.id, p: 0 }];
+    nextCursor = encodeCursor(cursorState);
+  }
+  return { paginated: sliced, nextCursor };
+}
+
+// src/search/pinning.ts
+function applyPinning(hits, pinned, resolveDoc) {
+  const result = hits.slice();
+  const pinnedDocIds = new Set(pinned.map((p) => p.docId));
+  for (let i = result.length - 1; i >= 0; i--) {
+    if (pinnedDocIds.has(result[i].id)) {
+      result.splice(i, 1);
+    }
+  }
+  const sorted = pinned.slice().sort((a, b) => a.position - b.position);
+  for (const entry of sorted) {
+    const doc = resolveDoc(entry.docId);
+    if (!doc) continue;
+    const pos = Math.max(0, Math.min(entry.position, result.length));
+    result.splice(pos, 0, doc);
+  }
+  return result;
+}
+
+// src/search/sorting.ts
+function getNestedValue2(obj, path) {
+  const segments = path.split(".");
+  let current = obj;
+  for (const segment of segments) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    if (!Object.hasOwn(current, segment)) {
+      return void 0;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+function applySorting(hits, sort, getDocument) {
+  const sortFields = Object.entries(sort);
+  if (sortFields.length === 0) return hits;
+  const collator = new Intl.Collator(void 0, { sensitivity: "base" });
+  const valueCache = /* @__PURE__ */ new Map();
+  for (const hit of hits) {
+    const doc = getDocument(hit.id);
+    if (!doc) {
+      valueCache.set(
+        hit.id,
+        sortFields.map(() => void 0)
+      );
+      continue;
+    }
+    const values = sortFields.map(([field]) => getNestedValue2(doc, field));
+    valueCache.set(hit.id, values);
+  }
+  const sorted = hits.slice();
+  sorted.sort((a, b) => {
+    const aValues = valueCache.get(a.id) ?? [];
+    const bValues = valueCache.get(b.id) ?? [];
+    for (let i = 0; i < sortFields.length; i++) {
+      const direction = sortFields[i][1];
+      const aVal = aValues[i];
+      const bVal = bValues[i];
+      const aIsNullish = aVal === void 0 || aVal === null;
+      const bIsNullish = bVal === void 0 || bVal === null;
+      if (aIsNullish && bIsNullish) continue;
+      if (aIsNullish) return 1;
+      if (bIsNullish) return -1;
+      let comparison = 0;
+      if (typeof aVal === "string" && typeof bVal === "string") {
+        comparison = collator.compare(aVal, bVal);
+      } else if (typeof aVal === "number" && typeof bVal === "number") {
+        const aIsNaN = Number.isNaN(aVal);
+        const bIsNaN = Number.isNaN(bVal);
+        if (aIsNaN && bIsNaN) continue;
+        if (aIsNaN) return 1;
+        if (bIsNaN) return -1;
+        comparison = aVal - bVal;
+      } else if (typeof aVal === "boolean" && typeof bVal === "boolean") {
+        comparison = aVal === bVal ? 0 : aVal ? 1 : -1;
+      }
+      if (comparison !== 0) {
+        return direction === "desc" ? -comparison : comparison;
+      }
+    }
+    return 0;
+  });
+  return sorted;
+}
+
+// src/workers/promoter.ts
+var DEFAULT_PER_INDEX_THRESHOLD = 1e4;
+var DEFAULT_TOTAL_THRESHOLD = 5e4;
+function createExecutionPromoter(config) {
+  const perIndexThreshold = config?.perIndexThreshold ?? DEFAULT_PER_INDEX_THRESHOLD;
+  const totalThreshold = config?.totalThreshold ?? DEFAULT_TOTAL_THRESHOLD;
+  let promoted = false;
+  function check(indexes) {
+    if (promoted) {
+      return { shouldPromote: false, reason: "" };
+    }
+    let totalDocuments = 0;
+    for (const [indexName, stats] of indexes) {
+      if (stats.documentCount >= perIndexThreshold) {
+        return {
+          shouldPromote: true,
+          reason: `Index "${indexName}" has ${stats.documentCount} documents, exceeding the per-index threshold of ${perIndexThreshold}`
+        };
+      }
+      totalDocuments += stats.documentCount;
+    }
+    if (totalDocuments >= totalThreshold) {
+      return {
+        shouldPromote: true,
+        reason: `Total document count of ${totalDocuments} exceeds the total threshold of ${totalThreshold}`
+      };
+    }
+    return { shouldPromote: false, reason: "" };
+  }
+  function markPromoted() {
+    promoted = true;
+  }
+  function isPromoted() {
+    return promoted;
+  }
+  return { check, markPromoted, isPromoted };
+}
+
+// src/narsil.ts
+var INDEX_NAME_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+var MAX_INDEX_NAME_LENGTH = 256;
+var MAX_DOC_ID_LENGTH = 512;
+var BATCH_CHUNK_SIZE = 1e3;
+var MAX_LIMIT = 1e4;
+var MAX_OFFSET = 1e5;
+var DEFAULT_LIMIT = 10;
+var DEFAULT_OFFSET = 0;
+function now() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function validateIndexName(name) {
+  if (!name || name.length === 0) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "Index name must not be empty", { indexName: name });
+  }
+  if (name.length > MAX_INDEX_NAME_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name must not exceed ${MAX_INDEX_NAME_LENGTH} characters`,
+      { indexName: name, length: name.length }
+    );
+  }
+  if (!INDEX_NAME_PATTERN.test(name)) {
+    throw new NarsilError(
+      ErrorCodes.INDEX_NOT_FOUND,
+      `Index name "${name}" contains invalid characters; use alphanumeric, dots, hyphens, and underscores only`,
+      { indexName: name }
+    );
+  }
+  if (name.includes("..")) {
+    throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index name "${name}" must not contain ".."`, { indexName: name });
+  }
+}
+function validateDocId(docId) {
+  if (!docId || docId.length === 0) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not be empty", { docId });
+  }
+  if (docId.length > MAX_DOC_ID_LENGTH) {
+    throw new NarsilError(
+      ErrorCodes.DOC_VALIDATION_FAILED,
+      `Document ID must not exceed ${MAX_DOC_ID_LENGTH} characters`,
+      { docId, length: docId.length }
+    );
+  }
+  if (docId.includes("\0")) {
+    throw new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, "Document ID must not contain null bytes", { docId });
+  }
+}
+function clampLimit(limit) {
+  if (limit === void 0) return DEFAULT_LIMIT;
+  return Math.max(0, Math.min(limit, MAX_LIMIT));
+}
+function clampOffset(offset) {
+  if (offset === void 0) return DEFAULT_OFFSET;
+  return Math.max(0, Math.min(offset, MAX_OFFSET));
+}
+async function createNarsil(config) {
+  const executor = createDirectExecutor();
+  const promoter = createExecutionPromoter({
+    perIndexThreshold: config?.workers?.promotionThreshold,
+    totalThreshold: config?.workers?.totalPromotionThreshold
+  });
+  const pluginRegistry = createPluginRegistry();
+  if (config?.plugins) {
+    for (const plugin of config.plugins) {
+      pluginRegistry.register(plugin);
+    }
+  }
+  let flushManager = null;
+  if (config?.persistence) {
+    const noopInvalidation = config.invalidation ?? {
+      publish: async () => {
+      },
+      subscribe: async () => {
+      },
+      shutdown: async () => {
+      }
+    };
+    flushManager = createFlushManager(
+      {
+        persistence: config.persistence,
+        invalidation: noopInvalidation,
+        interval: config.flush?.interval,
+        mutationThreshold: config.flush?.mutationThreshold
+      },
+      () => new Uint8Array(0),
+      () => "instance-0"
+    );
+  }
+  const idGenerator = config?.idGenerator ?? generateId;
+  const indexRegistry = /* @__PURE__ */ new Map();
+  const eventHandlers = /* @__PURE__ */ new Map();
+  let isShutdown = false;
+  function guardShutdown() {
+    if (isShutdown) {
+      throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, "This Narsil instance has been shut down");
+    }
+  }
+  function requireIndex(indexName) {
+    const entry = indexRegistry.get(indexName);
+    if (!entry) {
+      throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index "${indexName}" does not exist`, { indexName });
+    }
+    return entry;
+  }
+  const narsil = {
+    async createIndex(name, indexConfig) {
+      guardShutdown();
+      validateIndexName(name);
+      if (indexRegistry.has(name)) {
+        throw new NarsilError(ErrorCodes.INDEX_ALREADY_EXISTS, `Index "${name}" already exists`, { indexName: name });
+      }
+      validateSchema(indexConfig.schema);
+      const language = getLanguage(indexConfig.language ?? "english");
+      executor.createIndex(name, indexConfig, language);
+      indexRegistry.set(name, { config: indexConfig, language });
+      await pluginRegistry.runHook("onIndexCreate", { indexName: name, config: indexConfig });
+    },
+    async dropIndex(name) {
+      guardShutdown();
+      const entry = requireIndex(name);
+      executor.dropIndex(name);
+      indexRegistry.delete(name);
+      await pluginRegistry.runHook("onIndexDrop", {
+        indexName: name,
+        config: entry.config
+      });
+    },
+    listIndexes() {
+      const infos = [];
+      for (const [name, entry] of indexRegistry) {
+        const manager = executor.getManager(name);
+        infos.push({
+          name,
+          documentCount: manager?.countDocuments() ?? 0,
+          partitionCount: manager?.partitionCount ?? 0,
+          language: entry.language.name
+        });
+      }
+      return infos;
+    },
+    getStats(indexName) {
+      guardShutdown();
+      const entry = requireIndex(indexName);
+      const manager = executor.getManager(indexName);
+      return {
+        documentCount: manager?.countDocuments() ?? 0,
+        partitionCount: manager?.partitionCount ?? 0,
+        memoryBytes: 0,
+        indexSizeBytes: 0,
+        language: entry.language.name,
+        schema: entry.config.schema
+      };
+    },
+    async insert(indexName, document, docId) {
+      guardShutdown();
+      requireIndex(indexName);
+      const resolvedDocId = docId ?? idGenerator();
+      validateDocId(resolvedDocId);
+      await pluginRegistry.runHook("beforeInsert", {
+        indexName,
+        docId: resolvedDocId,
+        document
+      });
+      await executor.execute({
+        type: "insert",
+        indexName,
+        docId: resolvedDocId,
+        document,
+        requestId: resolvedDocId
+      });
+      try {
+        await pluginRegistry.runHook("afterInsert", {
+          indexName,
+          docId: resolvedDocId,
+          document
+        });
+      } catch (err) {
+        console.warn("afterInsert plugin hook error:", err);
+      }
+      flushManager?.markDirty(indexName, 0);
+      const indexMap = /* @__PURE__ */ new Map();
+      for (const [name] of indexRegistry) {
+        const mgr = executor.getManager(name);
+        indexMap.set(name, { documentCount: mgr?.countDocuments() ?? 0 });
+      }
+      promoter.check(indexMap);
+      return resolvedDocId;
+    },
+    async insertBatch(indexName, documents) {
+      guardShutdown();
+      requireIndex(indexName);
+      const succeeded = [];
+      const failed = [];
+      for (let chunkStart = 0; chunkStart < documents.length; chunkStart += BATCH_CHUNK_SIZE) {
+        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, documents.length);
+        for (let i = chunkStart; i < chunkEnd; i++) {
+          const docId = idGenerator();
+          try {
+            await narsil.insert(indexName, documents[i], docId);
+            succeeded.push(docId);
+          } catch (err) {
+            failed.push({
+              docId,
+              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_VALIDATION_FAILED, String(err))
+            });
+          }
+        }
+        if (chunkEnd < documents.length) {
+          await new Promise((r) => setTimeout(r, 0));
+        }
+      }
+      return { succeeded, failed };
+    },
+    async remove(indexName, docId) {
+      guardShutdown();
+      requireIndex(indexName);
+      validateDocId(docId);
+      await pluginRegistry.runHook("beforeRemove", { indexName, docId });
+      await executor.execute({
+        type: "remove",
+        indexName,
+        docId,
+        requestId: docId
+      });
+      try {
+        await pluginRegistry.runHook("afterRemove", { indexName, docId });
+      } catch (err) {
+        console.warn("afterRemove plugin hook error:", err);
+      }
+      flushManager?.markDirty(indexName, 0);
+    },
+    async removeBatch(indexName, docIds) {
+      guardShutdown();
+      requireIndex(indexName);
+      const succeeded = [];
+      const failed = [];
+      for (let chunkStart = 0; chunkStart < docIds.length; chunkStart += BATCH_CHUNK_SIZE) {
+        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, docIds.length);
+        for (let i = chunkStart; i < chunkEnd; i++) {
+          try {
+            await narsil.remove(indexName, docIds[i]);
+            succeeded.push(docIds[i]);
+          } catch (err) {
+            failed.push({
+              docId: docIds[i],
+              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
+            });
+          }
+        }
+        if (chunkEnd < docIds.length) {
+          await new Promise((r) => setTimeout(r, 0));
+        }
+      }
+      return { succeeded, failed };
+    },
+    async update(indexName, docId, document) {
+      guardShutdown();
+      requireIndex(indexName);
+      validateDocId(docId);
+      const manager = executor.getManager(indexName);
+      const oldDocument = manager?.get(docId);
+      await pluginRegistry.runHook("beforeUpdate", {
+        indexName,
+        docId,
+        oldDocument: oldDocument ?? {},
+        newDocument: document
+      });
+      await executor.execute({
+        type: "update",
+        indexName,
+        docId,
+        document,
+        requestId: docId
+      });
+      try {
+        await pluginRegistry.runHook("afterUpdate", {
+          indexName,
+          docId,
+          oldDocument: oldDocument ?? {},
+          newDocument: document
+        });
+      } catch (err) {
+        console.warn("afterUpdate plugin hook error:", err);
+      }
+      flushManager?.markDirty(indexName, 0);
+    },
+    async updateBatch(indexName, updates) {
+      guardShutdown();
+      requireIndex(indexName);
+      const succeeded = [];
+      const failed = [];
+      for (let chunkStart = 0; chunkStart < updates.length; chunkStart += BATCH_CHUNK_SIZE) {
+        const chunkEnd = Math.min(chunkStart + BATCH_CHUNK_SIZE, updates.length);
+        for (let i = chunkStart; i < chunkEnd; i++) {
+          try {
+            await narsil.update(indexName, updates[i].docId, updates[i].document);
+            succeeded.push(updates[i].docId);
+          } catch (err) {
+            failed.push({
+              docId: updates[i].docId,
+              error: err instanceof NarsilError ? err : new NarsilError(ErrorCodes.DOC_NOT_FOUND, String(err))
+            });
+          }
+        }
+        if (chunkEnd < updates.length) {
+          await new Promise((r) => setTimeout(r, 0));
+        }
+      }
+      return { succeeded, failed };
+    },
+    async get(indexName, docId) {
+      guardShutdown();
+      requireIndex(indexName);
+      return executor.execute({ type: "get", indexName, docId, requestId: docId });
+    },
+    async getMultiple(indexName, docIds) {
+      guardShutdown();
+      requireIndex(indexName);
+      const result = /* @__PURE__ */ new Map();
+      for (const docId of docIds) {
+        const doc = await narsil.get(indexName, docId);
+        if (doc !== void 0) {
+          result.set(docId, doc);
+        }
+      }
+      return result;
+    },
+    async has(indexName, docId) {
+      guardShutdown();
+      requireIndex(indexName);
+      return executor.execute({ type: "has", indexName, docId, requestId: docId });
+    },
+    async countDocuments(indexName) {
+      guardShutdown();
+      requireIndex(indexName);
+      return executor.execute({ type: "count", indexName, requestId: indexName });
+    },
+    async query(indexName, params) {
+      guardShutdown();
+      const entry = requireIndex(indexName);
+      const startTime = now();
+      const limit = clampLimit(params.limit);
+      const offset = clampOffset(params.offset);
+      await pluginRegistry.runHook("beforeSearch", { indexName, params });
+      const manager = executor.getManager(indexName);
+      if (!manager) {
+        throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index "${indexName}" manager not found`, { indexName });
+      }
+      const searchOptions = {
+        bm25Params: entry.config.bm25,
+        stopWords: entry.config.stopWords,
+        customTokenizer: entry.config.tokenizer
+      };
+      const fanOutResult = fanOutQuery(
+        manager,
+        params,
+        entry.language,
+        entry.config.schema,
+        {
+          scoringMode: params.scoring ?? entry.config.defaultScoring ?? "local"
+        },
+        searchOptions
+      );
+      let hits = fanOutResult.scored.map((scored) => ({
+        id: scored.docId,
+        score: scored.score,
+        document: manager.get(scored.docId) ?? {},
+        scoreComponents: {
+          termFrequencies: scored.termFrequencies,
+          fieldLengths: scored.fieldLengths,
+          idf: scored.idf
+        }
+      }));
+      if (params.highlight) {
+        const queryTokenResult = tokenize(params.term ?? "", entry.language, {
+          stem: true,
+          removeStopWords: true,
+          customTokenizer: entry.config.tokenizer,
+          stopWordOverride: entry.config.stopWords
+        });
+        for (const hit of hits) {
+          const highlights = {};
+          for (const field of params.highlight.fields) {
+            const doc = hit.document;
+            const fieldValue = doc[field];
+            if (typeof fieldValue === "string") {
+              highlights[field] = highlightField(fieldValue, queryTokenResult.tokens, entry.language, {
+                preTag: params.highlight.preTag,
+                postTag: params.highlight.postTag,
+                maxSnippetLength: params.highlight.maxSnippetLength
+              });
+            }
+          }
+          hit.highlights = highlights;
+        }
+      }
+      if (params.sort) {
+        hits = applySorting(hits, params.sort, (docId) => manager.get(docId));
+      }
+      let groups;
+      if (params.group) {
+        groups = applyGrouping(hits, params.group, (docId) => manager.get(docId));
+      }
+      if (params.pinned) {
+        hits = applyPinning(hits, params.pinned, (docId) => {
+          const doc = manager.get(docId);
+          if (!doc) return void 0;
+          return { id: docId, score: 0, document: doc };
+        });
+      }
+      const { paginated, nextCursor } = applyPagination(hits, limit, offset, params.searchAfter);
+      const elapsed = now() - startTime;
+      const result = {
+        hits: paginated,
+        count: fanOutResult.totalMatched,
+        elapsed,
+        cursor: nextCursor,
+        facets: fanOutResult.facets,
+        groups
+      };
+      try {
+        await pluginRegistry.runHook("afterSearch", {
+          indexName,
+          params,
+          results: result
+        });
+      } catch (err) {
+        console.warn("afterSearch plugin hook error:", err);
+      }
+      return result;
+    },
+    async preflight(indexName, params) {
+      guardShutdown();
+      const entry = requireIndex(indexName);
+      const startTime = now();
+      const manager = executor.getManager(indexName);
+      if (!manager) {
+        throw new NarsilError(ErrorCodes.INDEX_NOT_FOUND, `Index "${indexName}" manager not found`, { indexName });
+      }
+      const searchOptions = {
+        bm25Params: entry.config.bm25,
+        stopWords: entry.config.stopWords,
+        customTokenizer: entry.config.tokenizer
+      };
+      const fanOutResult = fanOutQuery(
+        manager,
+        params,
+        entry.language,
+        entry.config.schema,
+        {
+          scoringMode: params.scoring ?? entry.config.defaultScoring ?? "local"
+        },
+        searchOptions
+      );
+      const elapsed = now() - startTime;
+      return { count: fanOutResult.totalMatched, elapsed };
+    },
+    async clear(indexName) {
+      guardShutdown();
+      requireIndex(indexName);
+      await executor.execute({ type: "clear", indexName, requestId: indexName });
+    },
+    getMemoryStats() {
+      return { totalBytes: 0, workers: [] };
+    },
+    on(event, handler) {
+      const key = event;
+      let handlers = eventHandlers.get(key);
+      if (!handlers) {
+        handlers = /* @__PURE__ */ new Set();
+        eventHandlers.set(key, handlers);
+      }
+      handlers.add(handler);
+    },
+    off(event, handler) {
+      const key = event;
+      const handlers = eventHandlers.get(key);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          eventHandlers.delete(key);
+        }
+      }
+    },
+    async shutdown() {
+      if (isShutdown) return;
+      isShutdown = true;
+      if (flushManager) {
+        await flushManager.shutdown();
+      }
+      await executor.shutdown();
+      eventHandlers.clear();
+      indexRegistry.clear();
+    }
+  };
+  return narsil;
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+
+export { VERSION, createNarsil };