@slatedb/uniffi 0.12.0 → 0.13.0

package/slatedb.d.ts

@@ -126,6 +126,23 @@ export interface WriteOptions {
   "await_durable": boolean;
 }
 
+/**
+ * Options for configuring Foyer DB cache.
+ */
+export interface FoyerCacheOptions {
+  "max_capacity": bigint | number;
+  "shards": bigint | number;
+}
+
+/**
+ * Options for configuring Moka DB cache.
+ */
+export interface MokaCacheOptions {
+  "max_capacity": bigint | number;
+  "time_to_live": bigint | number | undefined;
+  "time_to_idle": bigint | number | undefined;
+}
+
 /**
  * A single log event forwarded to a foreign callback.
  */
@@ -222,6 +239,99 @@ export interface MetricLabel {
   "value": string;
 }
 
+/**
+ * Checkpoint metadata stored in a manifest.
+ */
+export interface Checkpoint {
+  /**
+   * Checkpoint UUID string.
+   */
+  "id": string;
+  /**
+   * Referenced manifest ID.
+   */
+  "manifest_id": bigint | number;
+  /**
+   * Expiration time as Unix UTC seconds, if present.
+   */
+  "expire_time_secs": bigint | number | undefined;
+  /**
+   * Creation time as Unix UTC seconds.
+   */
+  "create_time_secs": bigint | number;
+  /**
+   * Optional checkpoint name.
+   */
+  "name": string | undefined;
+}
+
+/**
+ * Canonical compaction record.
+ */
+export interface Compaction {
+  /**
+   * Compaction ULID string.
+   */
+  "id": string;
+  /**
+   * Compaction spec.
+   */
+  "spec": CompactionSpec;
+  /**
+   * Bytes processed so far.
+   */
+  "bytes_processed": bigint | number;
+  /**
+   * Current compaction status.
+   */
+  "status": CompactionStatus;
+  /**
+   * Output SSTs produced so far.
+   */
+  "output_ssts": Array<SsTableHandle>;
+  /**
+   * Whether the compaction is active.
+   */
+  "active": boolean;
+}
+
+/**
+ * Immutable compaction specification.
+ */
+export interface CompactionSpec {
+  /**
+   * Ordered compaction sources.
+   */
+  "sources": Array<SourceId>;
+  /**
+   * Destination sorted run ID. `None` for drain-segment specs, which
+   * produce no new sorted run.
+   */
+  "destination": number | undefined;
+  /**
+   * Whether any input source is an L0 SST view.
+   */
+  "has_l0_sources": boolean;
+  /**
+   * Whether any input source is a sorted run.
+   */
+  "has_sr_sources": boolean;
+}
+
+/**
+ * Read-only compactor state view.
+ */
+export interface CompactorStateView {
+  /**
+   * Latest compactions file, if present.
+   */
+  "compactions": VersionedCompactions | undefined;
+  /**
+   * Latest manifest file.
+   */
+  "manifest": VersionedManifest;
+}
+
 /**
  * Snapshot of the current database lifecycle and durability state.
  */
@@ -236,6 +346,28 @@ export interface DbStatus {
   "close_reason": CloseReason | undefined;
 }
 
+/**
+ * External DB reference recorded in a manifest.
+ */
+export interface ExternalDb {
+  /**
+   * External database path.
+   */
+  "path": string;
+  /**
+   * Source checkpoint UUID string.
+   */
+  "source_checkpoint_id": string;
+  /**
+   * Final checkpoint UUID string, if present.
+   */
+  "final_checkpoint_id": string | undefined;
+  /**
+   * SST IDs referenced from the external DB.
+   */
+  "sst_ids": Array<SsTableId>;
+}
+
 /**
  * A half-open or closed byte-key range used by scan APIs.
  */
@@ -314,6 +446,202 @@ export interface RowEntry {
   "expire_ts": bigint | number | undefined;
 }
 
+/**
+ * A sorted run made up of one or more SST views.
+ */
+export interface SortedRun {
+  /**
+   * Sorted run ID.
+   */
+  "id": number;
+  /**
+   * SST views in this run.
+   */
+  "sst_views": Array<SsTableView>;
+  /**
+   * Estimated total size in bytes.
+   */
+  "estimated_size_bytes": bigint | number;
+}
+
+/**
+ * A handle to a physical SSTable.
+ */
+export interface SsTableHandle {
+  /**
+   * SST ID.
+   */
+  "id": SsTableId;
+  /**
+   * SST metadata.
+   */
+  "info": SsTableInfo;
+  /**
+   * Estimated on-disk size in bytes.
+   */
+  "estimated_size_bytes": bigint | number;
+}
+
+/**
+ * SSTable metadata.
+ */
+export interface SsTableInfo {
+  /**
+   * First entry in the SSTable, if any.
+   */
+  "first_entry": Uint8Array | undefined;
+  /**
+   * Last entry in the SSTable, if any.
+   */
+  "last_entry": Uint8Array | undefined;
+  /**
+   * Index block offset in bytes.
+   */
+  "index_offset": bigint | number;
+  /**
+   * Index block length in bytes.
+   */
+  "index_len": bigint | number;
+  /**
+   * Filter block offset in bytes.
+   */
+  "filter_offset": bigint | number;
+  /**
+   * Filter block length in bytes.
+   */
+  "filter_len": bigint | number;
+  /**
+   * Compression codec, if any.
+   */
+  "compression_codec": CompressionCodec | undefined;
+  /**
+   * Physical SSTable type.
+   */
+  "sst_type": SstType;
+  /**
+   * Stats block offset in bytes.
+   */
+  "stats_offset": bigint | number;
+  /**
+   * Stats block length in bytes.
+   */
+  "stats_len": bigint | number;
+  /**
+   * Filter block format.
+   */
+  "filter_format": FilterFormat;
+}
+
+/**
+ * Projected SST view used by manifests and sorted runs.
+ */
+export interface SsTableView {
+  /**
+   * View ULID string.
+   */
+  "id": string;
+  /**
+   * Underlying SST handle.
+   */
+  "sst": SsTableHandle;
+  /**
+   * Optional projected visible key range.
+   */
+  "visible_range": KeyRange | undefined;
+  /**
+   * Estimated on-disk size in bytes.
+   */
+  "estimated_size_bytes": bigint | number;
+}
+
+/**
+ * A compactions snapshot paired with its version ID.
+ */
+export interface VersionedCompactions {
+  /**
+   * Compactions file version ID.
+   */
+  "id": bigint | number;
+  /**
+   * Compactor epoch recorded in this file.
+   */
+  "compactor_epoch": bigint | number;
+  /**
+   * Recent compactions tracked in this file.
+   */
+  "recent_compactions": Array<Compaction>;
+}
+
+/**
+ * A manifest snapshot paired with its version ID.
+ */
+export interface VersionedManifest {
+  /**
+   * Manifest version ID.
+   */
+  "id": bigint | number;
+  /**
+   * Writer epoch stored in the manifest.
+   */
+  "writer_epoch": bigint | number;
+  /**
+   * Compactor epoch stored in the manifest.
+   */
+  "compactor_epoch": bigint | number;
+  /**
+   * Referenced external databases.
+   */
+  "external_dbs": Array<ExternalDb>;
+  /**
+   * Whether initialization has completed.
+   */
+  "initialized": boolean;
+  /**
+   * Last compacted L0 SST view ID, if any.
+   */
+  "last_compacted_l0_sst_view_id": string | undefined;
+  /**
+   * Last compacted L0 SST ID, if any.
+   */
+  "last_compacted_l0_sst_id": string | undefined;
+  /**
+   * Current L0 SST views.
+   */
+  "l0": Array<SsTableView>;
+  /**
+   * Current compacted sorted runs.
+   */
+  "compacted": Array<SortedRun>;
+  /**
+   * Next WAL SST ID to assign.
+   */
+  "next_wal_sst_id": bigint | number;
+  /**
+   * WAL replay watermark.
+   */
+  "replay_after_wal_id": bigint | number;
+  /**
+   * Last persisted L0 clock tick.
+   */
+  "last_l0_clock_tick": bigint | number;
+  /**
+   * Last persisted L0 sequence number.
+   */
+  "last_l0_seq": bigint | number;
+  /**
+   * Minimum sequence number still visible to recent snapshots.
+   */
+  "recent_snapshot_min_seq": bigint | number;
+  /**
+   * Tracked checkpoints.
+   */
+  "checkpoints": Array<Checkpoint>;
+  /**
+   * Dedicated WAL object store URI, if any.
+   */
+  "wal_object_store_uri": string | undefined;
+}
+
 /**
  * Metadata returned by a successful write.
  */
@@ -514,6 +842,46 @@ export declare const LogLevel: Readonly<{
  */
 export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
 
+/**
+ * Compaction lifecycle state.
+ */
+export declare const CompactionStatus: Readonly<{
+  "Submitted": "Submitted";
+  "Running": "Running";
+  "Completed": "Completed";
+  "Failed": "Failed";
+}>;
+/**
+ * Compaction lifecycle state.
+ */
+export type CompactionStatus = (typeof CompactionStatus)[keyof typeof CompactionStatus];
+
+/**
+ * Compression codec used for an SSTable.
+ */
+export declare const CompressionCodec: Readonly<{
+  "Snappy": "Snappy";
+  "Zlib": "Zlib";
+  "Lz4": "Lz4";
+  "Zstd": "Zstd";
+}>;
+/**
+ * Compression codec used for an SSTable.
+ */
+export type CompressionCodec = (typeof CompressionCodec)[keyof typeof CompressionCodec];
+
+/**
+ * Filter block format stored in SST metadata.
+ */
+export declare const FilterFormat: Readonly<{
+  "Legacy": "Legacy";
+  "Composite": "Composite";
+}>;
+/**
+ * Filter block format stored in SST metadata.
+ */
+export type FilterFormat = (typeof FilterFormat)[keyof typeof FilterFormat];
+
 /**
  * Kind of row entry stored in WAL iteration results.
  */
@@ -536,6 +904,18 @@ export declare const RowEntryKind: Readonly<{
  */
 export type RowEntryKind = (typeof RowEntryKind)[keyof typeof RowEntryKind];
 
+/**
+ * Physical SSTable type.
+ */
+export declare const SstType: Readonly<{
+  "Compacted": "Compacted";
+  "Wal": "Wal";
+}>;
+/**
+ * Physical SSTable type.
+ */
+export type SstType = (typeof SstType)[keyof typeof SstType];
+
 /**
  * Use the database default TTL.
  */
@@ -650,6 +1030,131 @@ export declare const MetricValue: Readonly<{
   Histogram(_: HistogramMetricValue): MetricValueHistogram;
 }>;
 
+/**
+ * Warm all filters on the SST, if any exist.
+ */
+export interface CacheTargetFilters {
+  tag: "Filters";
+}
+
+/**
+ * Warm the SST index.
+ */
+export interface CacheTargetIndex {
+  tag: "Index";
+}
+
+/**
+ * Warm the SST stats block, if one exists.
+ */
+export interface CacheTargetStats {
+  tag: "Stats";
+}
+
+/**
+ * Warm the SST data blocks that overlap `range`. Also warms the index,
+ * since block planning depends on it.
+ */
+export interface CacheTargetData {
+  tag: "Data";
+  "range": KeyRange;
+}
+
+/**
+ * Cache content that [`crate::Db::warm_sst`] should populate.
+ */
+export type CacheTarget = CacheTargetFilters | CacheTargetIndex | CacheTargetStats | CacheTargetData;
+/**
+ * Cache content that [`crate::Db::warm_sst`] should populate.
+ */
+export declare const CacheTarget: Readonly<{
+  /**
+   * Warm all filters on the SST, if any exist.
+   */
+  Filters(): CacheTargetFilters;
+  /**
+   * Warm the SST index.
+   */
+  Index(): CacheTargetIndex;
+  /**
+   * Warm the SST stats block, if one exists.
+   */
+  Stats(): CacheTargetStats;
+  /**
+   * Warm the SST data blocks that overlap `range`. Also warms the index,
+   * since block planning depends on it.
+   */
+  Data(range: KeyRange): CacheTargetData;
+}>;
+
+/**
+ * Existing sorted run ID.
+ */
+export interface SourceIdSortedRun {
+  tag: "SortedRun";
+  "": number;
+}
+
+/**
+ * L0 SST view ULID string.
+ */
+export interface SourceIdSstView {
+  tag: "SstView";
+  "": string;
+}
+
+/**
+ * Compaction input source identifier.
+ */
+export type SourceId = SourceIdSortedRun | SourceIdSstView;
+/**
+ * Compaction input source identifier.
+ */
+export declare const SourceId: Readonly<{
+  /**
+   * Existing sorted run ID.
+   */
+  SortedRun(_: number): SourceIdSortedRun;
+  /**
+   * L0 SST view ULID string.
+   */
+  SstView(_: string): SourceIdSstView;
+}>;
+
+/**
+ * WAL SST identified by numeric WAL ID.
+ */
+export interface SsTableIdWal {
+  tag: "Wal";
+  "": bigint | number;
+}
+
+/**
+ * Compacted SST identified by ULID string.
+ */
+export interface SsTableIdCompacted {
+  tag: "Compacted";
+  "": string;
+}
+
+/**
+ * SSTable identifier.
+ */
+export type SsTableId = SsTableIdWal | SsTableIdCompacted;
+/**
+ * SSTable identifier.
+ */
+export declare const SsTableId: Readonly<{
+  /**
+   * WAL SST identified by numeric WAL ID.
+   */
+  Wal(_: bigint | number): SsTableIdWal;
+  /**
+   * Compacted SST identified by ULID string.
+   */
+  Compacted(_: string): SsTableIdCompacted;
+}>;
+
 /**
  * Error type returned by the UniFFI bindings.
  */
@@ -828,6 +1333,73 @@ export interface UpDownCounter {
  */
 export declare function init_logging(level: LogLevel, callback: LogCallback | undefined): void;
 
+/**
+ * Administrative read/query handle for SlateDB.
+ */
+export declare class Admin extends UniffiObjectBase {
+  protected constructor();
+  /**
+   * Looks up a sequence number for the provided Unix UTC timestamp seconds.
+   */
+  get_sequence_for_timestamp(timestamp_secs: bigint | number, round_up: boolean): Promise<bigint | number | undefined>;
+  /**
+   * Looks up a timestamp for the provided sequence number.
+   */
+  get_timestamp_for_sequence(seq: bigint | number, round_up: boolean): Promise<bigint | number | undefined>;
+  /**
+   * Lists checkpoints, optionally filtering by exact name.
+   */
+  list_checkpoints(name_filter: string | undefined): Promise<Array<Checkpoint>>;
+  /**
+   * Lists compactions files inside the half-open ID range `[from, to)`.
+   */
+  list_compactions(from: bigint | number | undefined, to: bigint | number | undefined): Promise<Array<VersionedCompactions>>;
+  /**
+   * Lists manifests inside the half-open ID range `[from, to)`.
+   */
+  list_manifests(from: bigint | number | undefined, to: bigint | number | undefined): Promise<Array<VersionedManifest>>;
+  /**
+   * Reads a compaction by ULID string from a specific or latest compactions file.
+   */
+  read_compaction(compaction_id: string, compactions_id: bigint | number | undefined): Promise<Compaction | undefined>;
+  /**
+   * Reads a specific compactions file by ID, or the latest when `id` is `None`.
+   */
+  read_compactions(id: bigint | number | undefined): Promise<VersionedCompactions | undefined>;
+  /**
+   * Reads the latest compactor state view.
+   */
+  read_compactor_state_view(): Promise<CompactorStateView>;
+  /**
+   * Reads a specific manifest by ID, or the latest when `id` is `None`.
+   */
+  read_manifest(id: bigint | number | undefined): Promise<VersionedManifest | undefined>;
+}
+
+/**
+ * Builder for opening an administrative [`crate::Admin`] handle.
+ *
+ * Builders are single-use: calling [`AdminBuilder::build`] consumes the builder.
+ */
+export declare class AdminBuilder extends UniffiObjectBase {
+  /**
+   * Creates a new admin builder for `path` in `object_store`.
+   */
+  constructor(path: string, object_store: ObjectStore);
+  /**
+   * Builds the admin handle and consumes this builder.
+   */
+  build(): Admin;
+  /**
+   * Sets the seed used for SlateDB's internal random number generation.
+   */
+  with_seed(seed: bigint | number): void;
+  /**
+   * Uses a separate object store for WAL-backed administrative operations.
+   */
+  with_wal_object_store(wal_object_store: ObjectStore): void;
+}
+
 /**
  * Builder for opening a writable [`crate::Db`].
  *
@@ -842,6 +1414,10 @@ export declare class DbBuilder extends UniffiObjectBase {
    * Opens the database and consumes this builder.
    */
   build(): Promise<Db>;
+  /**
+   * Sets DB cache.
+   */
+  with_db_cache(db_cache: DbCache): void;
   /**
    * Disables the SST block and metadata cache.
    */
@@ -925,6 +1501,12 @@ export declare class Db extends UniffiObjectBase {
    * Deletes `key` using custom write options.
    */
   delete_with_options(key: Uint8Array, options: WriteOptions): Promise<WriteHandle>;
+  /**
+   * Best-effort eviction of block-cache entries for one SST.
+   *
+   * If no block cache is configured, returns `Ok(())`.
+   */
+  evict_cached_sst(sst_id: SsTableId): Promise<void>;
   /**
    * Flushes the default storage layer.
    */
@@ -996,6 +1578,14 @@ export declare class Db extends UniffiObjectBase {
    * Returns the latest database status snapshot.
    */
   status(): DbStatus;
+  /**
+   * Warms selected cache content for one SST.
+   *
+   * Returns `Err` on the first failing target. If no block cache is
+   * configured, or if the SST is not reachable from the current manifest,
+   * the call is a no-op that returns `Ok(())`.
+   */
+  warm_sst(sst_id: SsTableId, targets: Array<CacheTarget>): Promise<void>;
   /**
    * Applies all operations in `batch` atomically.
    *
@@ -1010,15 +1600,48 @@ export declare class Db extends UniffiObjectBase {
   write_with_options(batch: WriteBatch, options: WriteOptions): Promise<WriteHandle>;
 }
 
+/**
+ * Database cache used to store blocks in memory.
+ */
+export declare class DbCache extends UniffiObjectBase {
+  protected constructor();
+  /**
+   * Creates a new Foyer based DB cache.
+   */
+  static new_foyer_cache(options: FoyerCacheOptions): DbCache;
+  /**
+   * Creates a new Moka based DB cache.
+   */
+  static new_moka_cache(options: MokaCacheOptions): DbCache;
+  /**
+   * Creates a new split cache with separate block and metadata capacities.
+   */
+  static new_split_cache(block_cache: DbCache, meta_cache: DbCache): DbCache;
+}
+
 /**
  * Read-only database handle opened by [`crate::DbReaderBuilder`].
  */
 export declare class DbReader extends UniffiObjectBase {
   protected constructor();
+  /**
+   * Best-effort eviction of block-cache entries for one SST.
+   *
+   * If no block cache is configured, returns `Ok(())`.
+   */
+  evict_cached_sst(sst_id: SsTableId): Promise<void>;
   /**
    * Reads the current value for `key`.
    */
   get(key: Uint8Array): Promise<Uint8Array | undefined>;
+  /**
+   * Reads the current row version for `key`, including metadata.
+   */
+  get_key_value(key: Uint8Array): Promise<KeyValue | undefined>;
+  /**
+   * Reads the current row version for `key` using custom read options.
+   */
+  get_key_value_with_options(key: Uint8Array, options: ReadOptions): Promise<KeyValue | undefined>;
   /**
    * Reads the current value for `key` using custom read options.
    */
@@ -1047,6 +1670,14 @@ export declare class DbReader extends UniffiObjectBase {
    * Returns the latest reader status snapshot.
    */
   status(): DbStatus;
+  /**
+   * Warms selected cache content for one SST.
+   *
+   * Returns `Err` on the first failing target. If no block cache is
+   * configured, or if the SST is not reachable from the current manifest,
+   * the call is a no-op that returns `Ok(())`.
+   */
+  warm_sst(sst_id: SsTableId, targets: Array<CacheTarget>): Promise<void>;
 }
 
 /**