@infino-ai/infino 0.1.9 → 0.2.1

package/infino/index.d.ts

@@ -7,6 +7,9 @@ export declare const BUILDER_ID: string;
 export type Metric = "cosine" | "l2sq" | "negdot";
 /** Boolean mode for multi-term FTS queries. */
 export type BoolMode = "or" | "and";
+/** BM25 statistics scope: per-superfile IDF (default) or corpus-wide
+ * `"global"` IDF across superfiles. */
+export type Bm25Stats = "per_superfile" | "global";
 /** A row from a query/search when not materializing to Arrow. */
 export type RowRecord = Record<string, unknown>;
 /** A plain `{ column: type }` schema descriptor for `createTable`. */
@@ -15,7 +18,15 @@ export type SchemaDescriptor = Record<string, string | {
 }>;
 /** Accepted shapes for `Table.append`. */
 export type AppendData = RowRecord[] | arrow.Table | arrow.RecordBatch | Buffer | Uint8Array;
-/** Storage and cache config the `connect` URI can't carry. All optional. */
+/**
+ * Storage and cache config the `connect` URI can't carry. All optional.
+ *
+ * Which options apply depends on the backend: `apiKey` is for a hosted
+ * (Infino Cloud) connection, while the storage/cache options — `storageOptions`,
+ * `cacheDir`, `cacheBudgetBytes`, `coldFetchMode`, `validate` — apply to **local
+ * connections only**; Infino Cloud manages storage, so it ignores them.
+ * `connectionMemoryBudgetBytes` applies to both.
+ */
 export interface ConnectOptions {
     /**
      * Credentials/tuning for the URI-selected backend, keyed by `object_store`
@@ -43,6 +54,12 @@ export interface ConnectOptions {
      * on bad credentials instead of on the first table operation.
      */
     validate?: boolean;
+    /**
+     * API key for a hosted (`https://<host>/<database>`) connection, sent as a
+     * bearer credential. Ignored by local backends. Falls back to the
+     * `INFINO_API_KEY` environment variable when omitted.
+     */
+    apiKey?: string;
 }
 /** Row counts returned by `update` / `delete`. */
 export interface MutationStats {
@@ -80,6 +97,8 @@ export interface OptimizeOptions {
 }
 export interface Bm25SearchOptions {
     mode?: BoolMode;
+    /** BM25 statistics scope: `"per_superfile"` (default) or `"global"`. */
+    stats?: Bm25Stats;
     /** Columns to return, e.g. `["_id", "score"]`; omit for full rows. */
     projection?: string[];
     arrow?: boolean;
@@ -130,8 +149,10 @@ export interface CountOptions {
 export interface QueryOptions {
     arrow?: boolean;
 }
+/** A table handle. Obtain one from {@link Connection.createTable} or {@link Connection.openTable}. */
 export declare class Table {
     private inner;
+    /** @hidden */
     constructor(inner: any);
     /** The table's Arrow schema. */
     schema(): arrow.Schema;
@@ -182,16 +203,28 @@ export declare class Table {
     /** Delete rows matching a SQL predicate (e.g. `"status = 'spam'"`).
      * Requires durable storage (not `memory://`). */
     delete(predicate: string): MutationStats;
-    /** Merge small / underfilled superfiles into larger ones (omit `settings`
-     * for engine defaults). */
+    /**
+     * Merge small / underfilled superfiles into larger ones (omit `settings`
+     * for engine defaults).
+     *
+     * **Local connections only.** On Infino Cloud, compaction is managed for you,
+     * so calling this on a hosted (`https://…`) connection throws.
+     */
     optimize(settings?: OptimizeOptions): void;
-    /** Delete orphaned storage objects left by compaction or interrupted writes.
+    /**
+     * Delete orphaned storage objects left by compaction or interrupted writes.
      * Only objects older than `graceSecs` (a safety window against racing
-     * readers/writers) are removed. Requires durable storage (not `memory://`). */
+     * readers/writers) are removed. Requires durable storage (not `memory://`).
+     *
+     * **Local connections only.** On Infino Cloud, cleanup is managed for you, so
+     * calling this on a hosted connection throws.
+     */
     gc(graceSecs: number): GcReport;
 }
+/** A catalog connection. Create one with {@link connect}. */
 export declare class Connection {
     private inner;
+    /** @hidden */
     constructor(inner: any);
     /**
      * Provision the database this connection targets. On the hosted service this
@@ -210,5 +243,24 @@ export declare class Connection {
     }): arrow.Table;
     querySql(sql: string, opts?: QueryOptions): RowRecord[];
 }
-/** Open (or create) a catalog rooted at `uri`. */
+/**
+ * Open a connection to Infino. The `uri` selects the backend:
+ *
+ * - a local path (`"./data"`) or `"memory://"` — embedded, in-process;
+ * - an object-store URI (`"s3://…"`, `"gs://…"`, `"az://…"`) — embedded over
+ *   your own bucket;
+ * - `"https://<host>/<database>"` — Infino Cloud, the hosted service.
+ *
+ * For a hosted (`https://`) target, authenticate with an API key: pass
+ * {@link ConnectOptions.apiKey}, or set the `INFINO_API_KEY` environment
+ * variable. Storage and cache tuning the URI can't carry also goes in
+ * `options` (see {@link ConnectOptions}).
+ *
+ * ```ts
+ * // local
+ * const db = connect("./data");
+ * // Infino Cloud
+ * const cloud = connect("https://api.platform.infino.ai/my-app", { apiKey: "inf_…" });
+ * ```
+ */
 export declare function connect(uri: string, options?: ConnectOptions): Connection;

package/infino/index.js

@@ -190,8 +190,10 @@ function decode(buf, asArrow) {
     });
 }
 // --- friendly handles ---
+/** A table handle. Obtain one from {@link Connection.createTable} or {@link Connection.openTable}. */
 class Table {
     inner;
+    /** @hidden */
     constructor(inner) {
         this.inner = inner;
     }
@@ -208,7 +210,7 @@ class Table {
         this.inner.append(dataToIpc(data, () => this.schema()));
     }
     bm25Search(column, query, k, opts = {}) {
-        const buf = this.inner.bm25Search(column, query, k, opts.mode, opts.projection);
+        const buf = this.inner.bm25Search(column, query, k, opts.mode, opts.stats, opts.projection);
         return decode(buf, opts.arrow);
     }
     vectorSearch(column, query, k, opts = {}) {
@@ -245,21 +247,33 @@ class Table {
     delete(predicate) {
         return this.inner.delete(predicate);
     }
-    /** Merge small / underfilled superfiles into larger ones (omit `settings`
-     * for engine defaults). */
+    /**
+     * Merge small / underfilled superfiles into larger ones (omit `settings`
+     * for engine defaults).
+     *
+     * **Local connections only.** On Infino Cloud, compaction is managed for you,
+     * so calling this on a hosted (`https://…`) connection throws.
+     */
     optimize(settings) {
         this.inner.optimize(settings);
     }
-    /** Delete orphaned storage objects left by compaction or interrupted writes.
+    /**
+     * Delete orphaned storage objects left by compaction or interrupted writes.
      * Only objects older than `graceSecs` (a safety window against racing
-     * readers/writers) are removed. Requires durable storage (not `memory://`). */
+     * readers/writers) are removed. Requires durable storage (not `memory://`).
+     *
+     * **Local connections only.** On Infino Cloud, cleanup is managed for you, so
+     * calling this on a hosted connection throws.
+     */
     gc(graceSecs) {
         return this.inner.gc(graceSecs);
     }
 }
 exports.Table = Table;
+/** A catalog connection. Create one with {@link connect}. */
 class Connection {
     inner;
+    /** @hidden */
     constructor(inner) {
         this.inner = inner;
     }
@@ -289,7 +303,26 @@ class Connection {
     }
 }
 exports.Connection = Connection;
-/** Open (or create) a catalog rooted at `uri`. */
+/**
+ * Open a connection to Infino. The `uri` selects the backend:
+ *
+ * - a local path (`"./data"`) or `"memory://"` — embedded, in-process;
+ * - an object-store URI (`"s3://…"`, `"gs://…"`, `"az://…"`) — embedded over
+ *   your own bucket;
+ * - `"https://<host>/<database>"` — Infino Cloud, the hosted service.
+ *
+ * For a hosted (`https://`) target, authenticate with an API key: pass
+ * {@link ConnectOptions.apiKey}, or set the `INFINO_API_KEY` environment
+ * variable. Storage and cache tuning the URI can't carry also goes in
+ * `options` (see {@link ConnectOptions}).
+ *
+ * ```ts
+ * // local
+ * const db = connect("./data");
+ * // Infino Cloud
+ * const cloud = connect("https://api.platform.infino.ai/my-app", { apiKey: "inf_…" });
+ * ```
+ */
 function connect(uri, options) {
     return new Connection((0, native_js_1.connect)(uri, options));
 }

package/infino/native.d.ts

@@ -165,7 +165,7 @@ export declare class Table {
    * `score` is a similarity (higher is better) — opposite direction
    * from `vectorSearch`'s distance. Fuse with `hybridSearch`.
    */
-  bm25Search(column: string, query: string, k: number, mode?: string | undefined | null, projection?: Array<string> | undefined | null): Buffer
+  bm25Search(column: string, query: string, k: number, mode?: string | undefined | null, stats?: string | undefined | null, projection?: Array<string> | undefined | null): Buffer
   /**
    * Vector kNN over one vector column. `query` is a `Float32Array`
    * (crosses by reference — no copy). Returns matching rows as an Arrow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infino-ai/infino",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "Fast search on object storage — SQL, full-text, and vector search.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -82,12 +82,12 @@
     "apache-arrow": "^17"
   },
   "optionalDependencies": {
-    "infx-darwin-x64": "0.1.9",
-    "infx-darwin-arm64": "0.1.9",
-    "infx-linux-x64-gnu": "0.1.9",
-    "infx-linux-arm64-gnu": "0.1.9",
-    "infx-linux-x64-musl": "0.1.9",
-    "infx-linux-arm64-musl": "0.1.9"
+    "infx-darwin-x64": "0.2.1",
+    "infx-darwin-arm64": "0.2.1",
+    "infx-linux-x64-gnu": "0.2.1",
+    "infx-linux-arm64-gnu": "0.2.1",
+    "infx-linux-x64-musl": "0.2.1",
+    "infx-linux-arm64-musl": "0.2.1"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.0",