@delali/narsil 0.2.2 → 0.2.3-next.32

package/dist/client.mjs

@@ -0,0 +1,843 @@
+// src/errors.ts
+var ErrorCodes = {
+  SCHEMA_INVALID_TYPE: "SCHEMA_INVALID_TYPE",
+  SCHEMA_MISSING_FIELD: "SCHEMA_MISSING_FIELD",
+  SCHEMA_DEPTH_EXCEEDED: "SCHEMA_DEPTH_EXCEEDED",
+  SCHEMA_INVALID_VECTOR_DIMENSION: "SCHEMA_INVALID_VECTOR_DIMENSION",
+  SCHEMA_INVALID_GEOPOINT: "SCHEMA_INVALID_GEOPOINT",
+  DOC_NOT_FOUND: "DOC_NOT_FOUND",
+  DOC_ALREADY_EXISTS: "DOC_ALREADY_EXISTS",
+  DOC_VALIDATION_FAILED: "DOC_VALIDATION_FAILED",
+  INDEX_NOT_FOUND: "INDEX_NOT_FOUND",
+  INDEX_ALREADY_EXISTS: "INDEX_ALREADY_EXISTS",
+  INDEX_ORPHANED: "INDEX_ORPHANED",
+  PARTITION_CORRUPTED: "PARTITION_CORRUPTED",
+  PARTITION_REBALANCING_BACKPRESSURE: "PARTITION_REBALANCING_BACKPRESSURE",
+  WORKER_CRASHED: "WORKER_CRASHED",
+  WORKER_BUSY: "WORKER_BUSY",
+  WORKER_TIMEOUT: "WORKER_TIMEOUT",
+  PERSISTENCE_SAVE_FAILED: "PERSISTENCE_SAVE_FAILED",
+  PERSISTENCE_LOAD_FAILED: "PERSISTENCE_LOAD_FAILED",
+  PERSISTENCE_DELETE_FAILED: "PERSISTENCE_DELETE_FAILED",
+  PERSISTENCE_CRC_MISMATCH: "PERSISTENCE_CRC_MISMATCH",
+  PERSISTENCE_WAL_CORRUPT: "PERSISTENCE_WAL_CORRUPT",
+  PERSISTENCE_FSYNC_FAILED: "PERSISTENCE_FSYNC_FAILED",
+  SEARCH_INVALID_FIELD: "SEARCH_INVALID_FIELD",
+  SEARCH_INVALID_VECTOR_SIZE: "SEARCH_INVALID_VECTOR_SIZE",
+  VECTOR_DIMENSION_MISMATCH: "VECTOR_DIMENSION_MISMATCH",
+  SEARCH_INVALID_FILTER: "SEARCH_INVALID_FILTER",
+  SEARCH_INVALID_MODE: "SEARCH_INVALID_MODE",
+  SEARCH_INVALID_CURSOR: "SEARCH_INVALID_CURSOR",
+  SEARCH_RESULT_WINDOW_EXCEEDED: "SEARCH_RESULT_WINDOW_EXCEEDED",
+  LANGUAGE_NOT_SUPPORTED: "LANGUAGE_NOT_SUPPORTED",
+  ENVELOPE_VERSION_MISMATCH: "ENVELOPE_VERSION_MISMATCH",
+  ENVELOPE_INVALID_MAGIC: "ENVELOPE_INVALID_MAGIC",
+  PARTITION_CAPACITY_EXCEEDED: "PARTITION_CAPACITY_EXCEEDED",
+  EMBEDDING_FAILED: "EMBEDDING_FAILED",
+  EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH",
+  EMBEDDING_NO_SOURCE: "EMBEDDING_NO_SOURCE",
+  EMBEDDING_CONFIG_INVALID: "EMBEDDING_CONFIG_INVALID",
+  DOC_MISSING_REQUIRED_FIELD: "DOC_MISSING_REQUIRED_FIELD",
+  CONFIG_INVALID: "CONFIG_INVALID",
+  QUERY_ROUTING_FAILED: "QUERY_ROUTING_FAILED",
+  QUERY_PARTIAL_FAILURE: "QUERY_PARTIAL_FAILURE",
+  QUERY_NODE_TIMEOUT: "QUERY_NODE_TIMEOUT",
+  QUERY_NO_ACTIVE_REPLICA: "QUERY_NO_ACTIVE_REPLICA",
+  CLUSTER_OPERATION_UNSUPPORTED: "CLUSTER_OPERATION_UNSUPPORTED",
+  ALLOCATION_NO_DATA_NODES: "ALLOCATION_NO_DATA_NODES",
+  ALLOCATION_INVALID_CONFIG: "ALLOCATION_INVALID_CONFIG",
+  ALLOCATION_FAILED: "ALLOCATION_FAILED",
+  CONTROLLER_LEASE_LOST: "CONTROLLER_LEASE_LOST",
+  CONTROLLER_NOT_ACTIVE: "CONTROLLER_NOT_ACTIVE",
+  CONTROLLER_METADATA_INVALID: "CONTROLLER_METADATA_INVALID",
+  NODE_BOOTSTRAP_FAILED: "NODE_BOOTSTRAP_FAILED",
+  NODE_ALREADY_JOINED: "NODE_ALREADY_JOINED",
+  NODE_NOT_JOINED: "NODE_NOT_JOINED",
+  COORDINATOR_DEPENDENCY_MISSING: "COORDINATOR_DEPENDENCY_MISSING",
+  TRANSPORT_DEPENDENCY_MISSING: "TRANSPORT_DEPENDENCY_MISSING",
+  REPLICATION_ENTRY_INVALID: "REPLICATION_ENTRY_INVALID",
+  REPLICATION_INSYNC_REMOVAL_FAILED: "REPLICATION_INSYNC_REMOVAL_FAILED",
+  REPLICATION_ROLLBACK_FAILED: "REPLICATION_ROLLBACK_FAILED",
+  REPLICATION_LOG_FULL: "REPLICATION_LOG_FULL",
+  REPLICATION_ENTRY_CORRUPT: "REPLICATION_ENTRY_CORRUPT",
+  REPLICATION_SNAPSHOT_CORRUPT: "REPLICATION_SNAPSHOT_CORRUPT",
+  REPLICATION_TERM_MISMATCH: "REPLICATION_TERM_MISMATCH",
+  REPLICATION_SYNC_FAILED: "REPLICATION_SYNC_FAILED",
+  PARTITION_NOT_PRIMARY: "PARTITION_NOT_PRIMARY",
+  PARTITION_UNASSIGNED: "PARTITION_UNASSIGNED",
+  INSUFFICIENT_REPLICAS: "INSUFFICIENT_REPLICAS",
+  SNAPSHOT_SYNC_UNAUTHORIZED: "SNAPSHOT_SYNC_UNAUTHORIZED",
+  SNAPSHOT_SYNC_REQUEST_INVALID: "SNAPSHOT_SYNC_REQUEST_INVALID",
+  SNAPSHOT_SYNC_INDEX_NOT_FOUND: "SNAPSHOT_SYNC_INDEX_NOT_FOUND",
+  SNAPSHOT_SYNC_TOO_LARGE: "SNAPSHOT_SYNC_TOO_LARGE",
+  SNAPSHOT_SYNC_CAPACITY_EXHAUSTED: "SNAPSHOT_SYNC_CAPACITY_EXHAUSTED",
+  SNAPSHOT_SYNC_SNAPSHOT_FAILED: "SNAPSHOT_SYNC_SNAPSHOT_FAILED",
+  SNAPSHOT_SYNC_DECODE_FAILED: "SNAPSHOT_SYNC_DECODE_FAILED",
+  SNAPSHOT_SYNC_FRAME_INVALID: "SNAPSHOT_SYNC_FRAME_INVALID",
+  SNAPSHOT_SYNC_HEADER_INVALID: "SNAPSHOT_SYNC_HEADER_INVALID",
+  SNAPSHOT_SYNC_HEADER_MISMATCH: "SNAPSHOT_SYNC_HEADER_MISMATCH",
+  SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER: "SNAPSHOT_SYNC_CHUNK_OUT_OF_ORDER",
+  SNAPSHOT_SYNC_CHUNK_OVERFLOW: "SNAPSHOT_SYNC_CHUNK_OVERFLOW",
+  SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED: "SNAPSHOT_SYNC_CHUNK_SIZE_EXCEEDED",
+  SNAPSHOT_SYNC_CHUNK_MISSING: "SNAPSHOT_SYNC_CHUNK_MISSING",
+  SNAPSHOT_SYNC_END_MISSING: "SNAPSHOT_SYNC_END_MISSING",
+  SNAPSHOT_SYNC_CHECKSUM_MISMATCH: "SNAPSHOT_SYNC_CHECKSUM_MISMATCH",
+  SNAPSHOT_SYNC_PRIMARY_ERROR: "SNAPSHOT_SYNC_PRIMARY_ERROR",
+  SNAPSHOT_SYNC_NO_TARGETS: "SNAPSHOT_SYNC_NO_TARGETS",
+  SNAPSHOT_SYNC_TRANSPORT_FAILED: "SNAPSHOT_SYNC_TRANSPORT_FAILED",
+  SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE: "SNAPSHOT_SYNC_SCHEMA_UNAVAILABLE",
+  SNAPSHOT_SYNC_RESTORE_FAILED: "SNAPSHOT_SYNC_RESTORE_FAILED",
+  SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED: "SNAPSHOT_SYNC_RESTORE_CLEANUP_FAILED",
+  SNAPSHOT_SYNC_TIMEOUT: "SNAPSHOT_SYNC_TIMEOUT",
+  SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE: "SNAPSHOT_SYNC_ALLOCATION_UNAVAILABLE",
+  SNAPSHOT_SYNC_NOT_ASSIGNED: "SNAPSHOT_SYNC_NOT_ASSIGNED",
+  SNAPSHOT_SYNC_ABORTED: "SNAPSHOT_SYNC_ABORTED"
+};
+var ServerErrorCodes = {
+  INVALID_REQUEST: "INVALID_REQUEST",
+  INVALID_JSON: "INVALID_JSON",
+  EMPTY_BODY: "EMPTY_BODY",
+  PAYLOAD_TOO_LARGE: "PAYLOAD_TOO_LARGE",
+  NOT_FOUND: "NOT_FOUND",
+  TASK_NOT_FOUND: "TASK_NOT_FOUND",
+  TASK_NOT_CANCELLABLE: "TASK_NOT_CANCELLABLE",
+  TASK_OWNED_BY_ANOTHER_INSTANCE: "TASK_OWNED_BY_ANOTHER_INSTANCE",
+  TOO_MANY_REQUESTS: "TOO_MANY_REQUESTS",
+  HOOK_ERROR: "HOOK_ERROR",
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+var ClientErrorCodes = {
+  CLIENT_CONNECTION_FAILED: "CLIENT_CONNECTION_FAILED",
+  CLIENT_REQUEST_TIMEOUT: "CLIENT_REQUEST_TIMEOUT",
+  CLIENT_REQUEST_ABORTED: "CLIENT_REQUEST_ABORTED",
+  CLIENT_INVALID_RESPONSE: "CLIENT_INVALID_RESPONSE",
+  CLIENT_TASK_TIMEOUT: "CLIENT_TASK_TIMEOUT",
+  CLIENT_UNEXPECTED_ERROR: "CLIENT_UNEXPECTED_ERROR"
+};
+var NarsilError = class extends Error {
+  /** This says which failure it is. */
+  code;
+  /** This carries the values behind the failure, such as the field, index, or limit involved. It is empty when the code says everything. */
+  details;
+  /**
+   * Builds an error carrying a code the caller can branch on.
+   *
+   * @param code - The failure this error reports, from {@link ErrorCodes} for
+   * an engine failure, {@link ServerErrorCodes} for one the HTTP layer raised,
+   * or {@link ClientErrorCodes} for one that stopped a request from reaching a
+   * server.
+   * @param message - Plain description, for a log or a person.
+   * @param details - Values behind the failure, which reach
+   * {@link NarsilError.details}.
+   */
+  constructor(code, message, details) {
+    super(message);
+    this.name = "NarsilError";
+    this.code = code;
+    this.details = details ?? {};
+  }
+};
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/server/capabilities.ts
+var ASYNC_IMPORT_CAPABILITY = "documents.import.async";
+var TASK_CANCEL_CAPABILITY = "tasks.cancel";
+var TASK_FILTER_CAPABILITY = "tasks.filter";
+var REBUILD_ANALYSIS_CAPABILITY = "indexes.rebuildAnalysis";
+var SERVER_CAPABILITIES = [
+  ASYNC_IMPORT_CAPABILITY,
+  TASK_CANCEL_CAPABILITY,
+  TASK_FILTER_CAPABILITY,
+  REBUILD_ANALYSIS_CAPABILITY
+];
+
+// src/json-encoding.ts
+function toPlainNumbers(key, value) {
+  if (ArrayBuffer.isView(value) && !(value instanceof DataView)) {
+    return Array.from(value);
+  }
+  return value;
+}
+function encodeJson(value) {
+  return JSON.stringify(value, toPlainNumbers);
+}
+
+// src/client/http.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var NO_TIMEOUT = 0;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function unrefTimer(timer) {
+  const unrefable = timer;
+  unrefable.unref?.();
+}
+function startDeadline(timeoutMs, caller) {
+  const controller = new AbortController();
+  let expired = false;
+  const abortWithCaller = () => controller.abort();
+  if (caller?.aborted) controller.abort();
+  else caller?.addEventListener("abort", abortWithCaller);
+  let timer;
+  if (timeoutMs > 0 && !controller.signal.aborted) {
+    timer = setTimeout(() => {
+      expired = true;
+      controller.abort();
+    }, timeoutMs);
+    unrefTimer(timer);
+  }
+  return {
+    signal: controller.signal,
+    expired: () => expired,
+    release: () => {
+      if (timer !== void 0) clearTimeout(timer);
+      caller?.removeEventListener("abort", abortWithCaller);
+    }
+  };
+}
+var ResponseTooLargeError = class extends Error {
+  constructor(limitBytes) {
+    super(`The answer passed the ${limitBytes} byte ceiling this client reads`);
+    this.limitBytes = limitBytes;
+  }
+};
+async function readStreamCapped(stream, limitBytes) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > limitBytes) throw new ResponseTooLargeError(limitBytes);
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+    if (total > limitBytes) await stream.cancel().catch(() => void 0);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+async function readAnswer(response, limitBytes, wantsBytes) {
+  const stream = response.body;
+  if (limitBytes > 0 && stream !== null && stream !== void 0) {
+    const body = await readStreamCapped(stream, limitBytes);
+    return wantsBytes ? { text: "", bytes: body } : { text: new TextDecoder().decode(body), bytes: null };
+  }
+  if (wantsBytes) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (limitBytes > 0 && bytes.byteLength > limitBytes) throw new ResponseTooLargeError(limitBytes);
+    return { text: "", bytes };
+  }
+  const text = await response.text();
+  if (limitBytes > 0 && text.length > limitBytes) throw new ResponseTooLargeError(limitBytes);
+  return { text, bytes: null };
+}
+function invalidResponse(message, details) {
+  return new NarsilError(ClientErrorCodes.CLIENT_INVALID_RESPONSE, message, details);
+}
+function errorFromBody(status, payload, url) {
+  const envelope = isRecord(payload) && isRecord(payload.error) ? payload.error : void 0;
+  if (envelope === void 0 || typeof envelope.code !== "string" || typeof envelope.message !== "string") {
+    return invalidResponse(`The server answered HTTP ${status} without a Narsil error envelope`, { url, status });
+  }
+  const details = isRecord(envelope.details) ? envelope.details : {};
+  return new NarsilError(envelope.code, envelope.message, { ...details, status });
+}
+function isAbsoluteUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function normaliseBase(url) {
+  const trimmed = url.trim();
+  if (trimmed.length === 0) {
+    throw new NarsilError(ErrorCodes.CONFIG_INVALID, 'The client needs a server address, and "url" is empty');
+  }
+  if (!trimmed.startsWith("/") && !isAbsoluteUrl(trimmed)) {
+    throw new NarsilError(
+      ErrorCodes.CONFIG_INVALID,
+      `The client cannot read "${trimmed}" as a server address; pass an absolute URL or a path starting with "/"`,
+      { url: trimmed }
+    );
+  }
+  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
+}
+function withQuery(path, query) {
+  if (query === void 0) return path;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) params.set(key, value);
+  }
+  const encoded = params.toString();
+  return encoded.length === 0 ? path : `${path}?${encoded}`;
+}
+function createTransport(options) {
+  const base = normaliseBase(options.url);
+  const send = options.fetch ?? ((input, init) => fetch(input, init));
+  const baseHeaders = { ...options.headers };
+  if (options.apiKey !== void 0 && options.apiKey.length > 0) {
+    baseHeaders.authorization = `Bearer ${options.apiKey}`;
+  }
+  function resolveTimeout(spec) {
+    const perCall = spec.options?.timeoutMs;
+    if (perCall !== void 0) return perCall;
+    if (options.timeoutMs !== void 0) return options.timeoutMs;
+    return spec.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+  function resolveResponseCeiling(spec) {
+    const perCall = spec.options?.maxResponseBytes;
+    if (perCall !== void 0) return perCall;
+    return options.maxResponseBytes ?? 0;
+  }
+  async function exchange(spec) {
+    const url = `${base}${withQuery(spec.path, spec.query)}`;
+    const headers = { ...baseHeaders, ...spec.options?.headers };
+    if (spec.contentType !== void 0) headers["content-type"] = spec.contentType;
+    const timeoutMs = resolveTimeout(spec);
+    const deadline = startDeadline(timeoutMs, spec.options?.signal);
+    try {
+      const init = { method: spec.method, headers, signal: deadline.signal };
+      if (spec.body !== void 0) init.body = spec.body;
+      const response = await send(url, init);
+      const wantsBytes = spec.binaryAnswer === true && response.ok;
+      const answer = await readAnswer(response, resolveResponseCeiling(spec), wantsBytes);
+      return { status: response.status, ...answer };
+    } catch (err) {
+      if (err instanceof ResponseTooLargeError) {
+        throw invalidResponse(`The server at ${url} answered more than this client reads: ${err.message}`, {
+          url,
+          maxResponseBytes: err.limitBytes
+        });
+      }
+      if (deadline.expired()) {
+        throw new NarsilError(
+          ClientErrorCodes.CLIENT_REQUEST_TIMEOUT,
+          `The server at ${url} did not answer within ${timeoutMs} ms`,
+          { url, timeoutMs }
+        );
+      }
+      if (spec.options?.signal?.aborted === true) {
+        throw new NarsilError(ClientErrorCodes.CLIENT_REQUEST_ABORTED, `The caller cancelled the request to ${url}`, {
+          url
+        });
+      }
+      throw new NarsilError(
+        ClientErrorCodes.CLIENT_CONNECTION_FAILED,
+        `The client could not reach ${url}: ${describeError(err)}`,
+        { url }
+      );
+    } finally {
+      deadline.release();
+    }
+  }
+  function parse(status, text, path) {
+    if (text.length === 0) return void 0;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw invalidResponse(`The server answered HTTP ${status} with a body that is not JSON`, { url: path, status });
+    }
+  }
+  async function json(spec) {
+    const { status, text } = await exchange(spec);
+    const payload = parse(status, text, spec.path);
+    if (status >= 200 && status < 300) return payload;
+    throw errorFromBody(status, payload, spec.path);
+  }
+  return {
+    json,
+    async jsonOrNull(spec, absentCode) {
+      try {
+        return await json(spec);
+      } catch (err) {
+        if (err instanceof NarsilError && err.code === absentCode) return null;
+        throw err;
+      }
+    },
+    async binary(spec) {
+      const { status, text, bytes } = await exchange(spec);
+      if (bytes !== null) return bytes;
+      throw errorFromBody(status, parse(status, text, spec.path), spec.path);
+    },
+    async probe(spec) {
+      const { status } = await exchange(spec);
+      return status;
+    }
+  };
+}
+
+// src/client/paths.ts
+function indexPath(indexName) {
+  return `/indexes/${encodeURIComponent(indexName)}`;
+}
+function documentPath(indexName, docId) {
+  return `${indexPath(indexName)}/documents/${encodeURIComponent(docId)}`;
+}
+function taskPath(taskId) {
+  return `/tasks/${encodeURIComponent(taskId)}`;
+}
+
+// src/client/response-shape.ts
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function malformed(path, expected) {
+  return new NarsilError(ClientErrorCodes.CLIENT_INVALID_RESPONSE, `The answer from ${path} holds no ${expected}`, {
+    url: path
+  });
+}
+function readArray(payload, key, path) {
+  if (!isRecord2(payload) || !Array.isArray(payload[key])) throw malformed(path, `"${key}" array`);
+  return payload[key];
+}
+function readNumber(payload, key, path) {
+  if (!isRecord2(payload) || typeof payload[key] !== "number") throw malformed(path, `"${key}" number`);
+  return payload[key];
+}
+function readBoolean(payload, key, path) {
+  if (!isRecord2(payload) || typeof payload[key] !== "boolean") throw malformed(path, `"${key}" flag`);
+  return payload[key];
+}
+function readString(payload, key, path) {
+  if (!isRecord2(payload) || typeof payload[key] !== "string") throw malformed(path, `"${key}" string`);
+  return payload[key];
+}
+function readObject(payload, key, path) {
+  if (!isRecord2(payload) || !isRecord2(payload[key])) throw malformed(path, `"${key}" object`);
+  return payload[key];
+}
+function readBody(payload, path) {
+  if (!isRecord2(payload)) throw malformed(path, "JSON object");
+  return payload;
+}
+
+// src/client/admin.ts
+function createAdminOperations(transport) {
+  async function postJson(path, body, options) {
+    const payload = await transport.json({
+      method: "POST",
+      path,
+      body: encodeJson(body),
+      contentType: "application/json",
+      options
+    });
+    return readBody(payload, path);
+  }
+  return {
+    async checkpoint(indexName, options) {
+      await transport.json({ method: "POST", path: `${indexPath(indexName)}/_checkpoint`, options });
+    },
+    snapshot(indexName, options) {
+      return transport.binary({
+        method: "GET",
+        path: `${indexPath(indexName)}/snapshot`,
+        binaryAnswer: true,
+        defaultTimeoutMs: NO_TIMEOUT,
+        options
+      });
+    },
+    async restore(indexName, data, options) {
+      const path = `${indexPath(indexName)}/restore`;
+      const payload = await transport.json({
+        method: "POST",
+        path,
+        body: data,
+        contentType: "application/octet-stream",
+        defaultTimeoutMs: NO_TIMEOUT,
+        options
+      });
+      return readBody(payload, path);
+    },
+    async vectorMaintenanceStatus(indexName, options) {
+      const path = `${indexPath(indexName)}/vector-maintenance`;
+      const payload = await transport.json({ method: "GET", path, options });
+      return readArray(payload, "fields", path);
+    },
+    async compactVectors(indexName, fieldName, options) {
+      await postJson(
+        `${indexPath(indexName)}/vectors/_compact`,
+        fieldName === void 0 ? {} : { field: fieldName },
+        options
+      );
+    },
+    optimizeVectors(indexName, fieldName, options) {
+      return postJson(
+        `${indexPath(indexName)}/vectors/_optimize`,
+        fieldName === void 0 ? {} : { field: fieldName },
+        options
+      );
+    },
+    rebalance(indexName, targetPartitionCount, options) {
+      return postJson(`${indexPath(indexName)}/_rebalance`, { targetPartitionCount }, options);
+    },
+    async updatePartitionConfig(indexName, partitionConfig, options) {
+      await postJson(`${indexPath(indexName)}/partition-config`, partitionConfig, options);
+    },
+    async rebuildAnalysis(indexName, options) {
+      const path = `${indexPath(indexName)}/_rebuild-analysis`;
+      return readBody(await transport.json({ method: "POST", path, options }), path);
+    },
+    async getMemoryStats(options) {
+      const path = "/stats/memory";
+      return readBody(await transport.json({ method: "GET", path, options }), path);
+    }
+  };
+}
+
+// src/client/bulk.ts
+function toNdjson(source) {
+  if (typeof source === "string") return source;
+  if (Array.isArray(source)) return source.map((document) => encodeJson(document)).join("\n");
+  return source;
+}
+function toBatchResult(payload, path) {
+  const failed = readArray(payload, "failed", path);
+  return {
+    succeeded: readArray(payload, "succeeded", path),
+    failed: failed.map((entry) => {
+      const record = readBody(entry, path);
+      const docId = typeof record.docId === "string" ? record.docId : "";
+      const error = readBody(record.error, path);
+      const code = typeof error.code === "string" ? error.code : ServerErrorCodes.INTERNAL_ERROR;
+      const message = typeof error.message === "string" ? error.message : "The server refused the document";
+      const details = typeof error.details === "object" && error.details !== null ? error.details : void 0;
+      return { docId, error: new NarsilError(code, message, details) };
+    })
+  };
+}
+function createBulkOperations(transport) {
+  function batch(indexName, body, options) {
+    const path = `${indexPath(indexName)}/documents/_batch`;
+    return transport.json({ method: "POST", path, body: encodeJson(body), contentType: "application/json", options }).then((payload) => toBatchResult(payload, path));
+  }
+  function importBody(indexName, source, asynchronous, options) {
+    return {
+      method: "POST",
+      path: `${indexPath(indexName)}/documents/_import`,
+      ...asynchronous ? { query: { async: "true" } } : {},
+      body: toNdjson(source),
+      contentType: "application/x-ndjson",
+      defaultTimeoutMs: NO_TIMEOUT,
+      options
+    };
+  }
+  return {
+    insertBatch(indexName, documents, insertOptions, options) {
+      return batch(
+        indexName,
+        { action: "insert", documents, ...insertOptions === void 0 ? {} : { options: insertOptions } },
+        options
+      );
+    },
+    updateBatch(indexName, updates, options) {
+      return batch(indexName, { action: "update", updates }, options);
+    },
+    removeBatch(indexName, docIds, options) {
+      return batch(indexName, { action: "delete", docIds }, options);
+    },
+    async getMultiple(indexName, docIds, options) {
+      const path = `${indexPath(indexName)}/documents/_multi-get`;
+      const payload = await transport.json({
+        method: "POST",
+        path,
+        body: encodeJson({ docIds }),
+        contentType: "application/json",
+        options
+      });
+      const documents = readObject(payload, "documents", path);
+      return new Map(Object.entries(documents));
+    },
+    async listDocuments(indexName, params, options) {
+      const path = `${indexPath(indexName)}/documents/_list`;
+      const payload = await transport.json({
+        method: "POST",
+        path,
+        body: encodeJson(params ?? {}),
+        contentType: "application/json",
+        options
+      });
+      return readBody(payload, path);
+    },
+    async importDocuments(indexName, source, options) {
+      const spec = importBody(indexName, source, false, options);
+      return readBody(await transport.json(spec), spec.path);
+    },
+    async startImport(indexName, source, options) {
+      const spec = importBody(indexName, source, true, options);
+      return readBody(await transport.json(spec), spec.path);
+    }
+  };
+}
+
+// src/client/documents.ts
+function createDocumentOperations(transport) {
+  return {
+    async insert(indexName, document, docId, insertOptions, options) {
+      const path = `${indexPath(indexName)}/documents`;
+      const payload = await transport.json({
+        method: "POST",
+        path,
+        body: encodeJson({
+          document,
+          ...docId === void 0 ? {} : { id: docId },
+          ...insertOptions === void 0 ? {} : { options: insertOptions }
+        }),
+        contentType: "application/json",
+        options
+      });
+      return readString(payload, "id", path);
+    },
+    async get(indexName, docId, options) {
+      const path = documentPath(indexName, docId);
+      const payload = await transport.jsonOrNull({ method: "GET", path, options }, ErrorCodes.DOC_NOT_FOUND);
+      if (payload === null) return void 0;
+      return readObject(payload, "document", path);
+    },
+    async has(indexName, docId, options) {
+      const path = `${documentPath(indexName, docId)}/_exists`;
+      return readBoolean(await transport.json({ method: "GET", path, options }), "exists", path);
+    },
+    async put(indexName, docId, document, options) {
+      const path = documentPath(indexName, docId);
+      const payload = await transport.json({
+        method: "PUT",
+        path,
+        body: encodeJson({ document }),
+        contentType: "application/json",
+        options
+      });
+      return { id: readString(payload, "id", path), created: readBoolean(payload, "created", path) };
+    },
+    async update(indexName, docId, document, options) {
+      await transport.json({
+        method: "PATCH",
+        path: documentPath(indexName, docId),
+        body: encodeJson({ document }),
+        contentType: "application/json",
+        options
+      });
+    },
+    async remove(indexName, docId, options) {
+      await transport.json({ method: "DELETE", path: documentPath(indexName, docId), options });
+    },
+    async countDocuments(indexName, options) {
+      const path = `${indexPath(indexName)}/count`;
+      return readNumber(await transport.json({ method: "GET", path, options }), "count", path);
+    }
+  };
+}
+
+// src/client/indexes.ts
+function createIndexOperations(transport) {
+  return {
+    async createIndex(name, config, options) {
+      await transport.json({
+        method: "POST",
+        path: "/indexes",
+        body: encodeJson({ name, config }),
+        contentType: "application/json",
+        options
+      });
+    },
+    async listIndexes(options) {
+      const path = "/indexes";
+      return readArray(await transport.json({ method: "GET", path, options }), "indexes", path);
+    },
+    async dropIndex(name, options) {
+      await transport.json({ method: "DELETE", path: indexPath(name), options });
+    },
+    async getStats(indexName, options) {
+      const path = `${indexPath(indexName)}/stats`;
+      return readBody(await transport.json({ method: "GET", path, options }), path);
+    },
+    async getPartitionStats(indexName, options) {
+      const path = `${indexPath(indexName)}/partitions`;
+      const payload = await transport.json({ method: "GET", path, options });
+      return readArray(payload, "partitions", path);
+    },
+    async clear(indexName, options) {
+      await transport.json({ method: "POST", path: `${indexPath(indexName)}/_clear`, options });
+    }
+  };
+}
+
+// src/client/search.ts
+function createSearchOperations(transport) {
+  async function post(path, params, options) {
+    const payload = await transport.json({
+      method: "POST",
+      path,
+      body: encodeJson(params),
+      contentType: "application/json",
+      options
+    });
+    return readBody(payload, path);
+  }
+  return {
+    query(indexName, params, options) {
+      return post(`${indexPath(indexName)}/search`, params, options);
+    },
+    preflight(indexName, params, options) {
+      return post(`${indexPath(indexName)}/search/preflight`, params, options);
+    },
+    suggest(indexName, params, options) {
+      return post(`${indexPath(indexName)}/suggest`, params, options);
+    }
+  };
+}
+
+// src/client/server-info.ts
+function createServerOperations(transport) {
+  let announced = null;
+  async function readCapabilities(options) {
+    const path = "/capabilities";
+    const payload = await transport.jsonOrNull({ method: "GET", path, options }, ServerErrorCodes.NOT_FOUND);
+    if (payload === null) return /* @__PURE__ */ new Set();
+    return new Set(readArray(payload, "capabilities", path));
+  }
+  function load(options) {
+    if (announced === null) {
+      announced = readCapabilities(options).catch((err) => {
+        announced = null;
+        throw err;
+      });
+    }
+    return announced;
+  }
+  return {
+    async version(options) {
+      const path = "/version";
+      return readBody(await transport.json({ method: "GET", path, options }), path);
+    },
+    async capabilities(options) {
+      return [...await load(options)];
+    },
+    async supports(capability, options) {
+      return (await load(options)).has(capability);
+    },
+    async isAlive(options) {
+      return await transport.probe({ method: "GET", path: "/livez", options }) === 200;
+    },
+    async isReady(options) {
+      return await transport.probe({ method: "GET", path: "/readyz", options }) === 200;
+    }
+  };
+}
+
+// src/client/tasks.ts
+var DEFAULT_POLL_INTERVAL_MS = 250;
+function isTerminal(record) {
+  return record.status === "succeeded" || record.status === "failed" || record.status === "cancelled";
+}
+function progressKey(record) {
+  const progress = record.progress;
+  if (progress === void 0) return record.status;
+  return `${record.status}:${progress.bytesProcessed}:${progress.indexed}:${progress.failed}`;
+}
+function sleep(milliseconds, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", stop);
+      resolve();
+    }, milliseconds);
+    function stop() {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal?.addEventListener("abort", stop, { once: true });
+  });
+}
+function listQuery(query) {
+  return {
+    indexName: query?.indexName,
+    type: query?.type === void 0 || query.type.length === 0 ? void 0 : query.type.join(","),
+    status: query?.status === void 0 || query.status.length === 0 ? void 0 : query.status.join(","),
+    from: query?.from === void 0 ? void 0 : String(query.from),
+    limit: query?.limit === void 0 ? void 0 : String(query.limit)
+  };
+}
+function createTaskOperations(transport) {
+  const operations = {
+    async getTask(taskId, options) {
+      const path = taskPath(taskId);
+      const payload = await transport.jsonOrNull({ method: "GET", path, options }, ServerErrorCodes.TASK_NOT_FOUND);
+      return payload === null ? null : readBody(payload, path);
+    },
+    async listTasks(query, options) {
+      const path = "/tasks";
+      const payload = await transport.json({ method: "GET", path, query: listQuery(query), options });
+      return readBody(payload, path);
+    },
+    async cancelTask(taskId, options) {
+      const path = `${taskPath(taskId)}/_cancel`;
+      return readBody(await transport.json({ method: "POST", path, options }), path);
+    },
+    async waitForTask(taskId, options) {
+      const interval = options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+      const waitTimeoutMs = options?.waitTimeoutMs ?? 0;
+      const startedAt = Date.now();
+      let reported = null;
+      for (; ; ) {
+        if (options?.signal?.aborted === true) {
+          throw new NarsilError(
+            ClientErrorCodes.CLIENT_REQUEST_ABORTED,
+            `The caller stopped waiting for task "${taskId}"`,
+            { taskId }
+          );
+        }
+        const record = await operations.getTask(taskId, options);
+        if (record === null) {
+          throw new NarsilError(
+            ServerErrorCodes.TASK_NOT_FOUND,
+            `The server no longer holds task "${taskId}", so its outcome is unknown`,
+            { taskId }
+          );
+        }
+        const key = progressKey(record);
+        if (key !== reported) {
+          reported = key;
+          options?.onProgress?.(record);
+        }
+        if (isTerminal(record)) return record;
+        if (waitTimeoutMs > 0 && Date.now() - startedAt >= waitTimeoutMs) {
+          throw new NarsilError(
+            ClientErrorCodes.CLIENT_TASK_TIMEOUT,
+            `Task "${taskId}" was still ${record.status} after ${waitTimeoutMs} ms, and it keeps running`,
+            { taskId, waitTimeoutMs, status: record.status }
+          );
+        }
+        await sleep(interval, options?.signal);
+      }
+    }
+  };
+  return operations;
+}
+
+// src/client/client.ts
+function createNarsilClient(options) {
+  const transport = createTransport(options);
+  return {
+    ...createIndexOperations(transport),
+    ...createDocumentOperations(transport),
+    ...createBulkOperations(transport),
+    ...createSearchOperations(transport),
+    ...createTaskOperations(transport),
+    ...createAdminOperations(transport),
+    ...createServerOperations(transport)
+  };
+}
+
+export { ASYNC_IMPORT_CAPABILITY, ClientErrorCodes, ErrorCodes, NarsilError, REBUILD_ANALYSIS_CAPABILITY, SERVER_CAPABILITIES, ServerErrorCodes, TASK_CANCEL_CAPABILITY, TASK_FILTER_CAPABILITY, createNarsilClient };