@tungthedev/streams-server 0.2.0

package/src/manifest.ts

@@ -0,0 +1,249 @@
+import { Result } from "better-result";
+import type {
+  IndexRunRow,
+  IndexStateRow,
+  LexiconIndexRunRow,
+  LexiconIndexStateRow,
+  SearchCompanionPlanRow,
+  SearchSegmentCompanionRow,
+  SecondaryIndexRunRow,
+  SecondaryIndexStateRow,
+  SegmentMetaRow,
+} from "./store/segment_manifest_store";
+import type { StreamReadRow } from "./store/segment_read_store";
+import { encodeOffsetResult } from "./offset";
+import { zstdCompressSync } from "./util/zstd";
+import { dsError } from "./util/ds_error.ts";
+
+function b64(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64");
+}
+
+function compressB64(bytes: Uint8Array): string {
+  return b64(new Uint8Array(zstdCompressSync(bytes)));
+}
+
+function parseSectionsJson(raw: string): string[] {
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value): value is string => typeof value === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+export type ManifestJson = Record<string, any>;
+export type ManifestBuildError = { kind: "invalid_manifest"; message: string };
+
+function invalidManifest<T = never>(message: string): Result<T, ManifestBuildError> {
+  return Result.err({ kind: "invalid_manifest", message });
+}
+
+type BuildManifestArgs = {
+  streamName: string;
+  streamRow: StreamReadRow;
+  publishedLogicalSizeBytes: bigint;
+  profileJson?: Record<string, any> | null;
+  segmentMeta: SegmentMetaRow;
+  uploadedPrefixCount: number;
+  generation: number;
+  indexState?: IndexStateRow | null;
+  indexRuns?: IndexRunRow[];
+  retiredRuns?: IndexRunRow[];
+  secondaryIndexStates?: SecondaryIndexStateRow[];
+  secondaryIndexRuns?: SecondaryIndexRunRow[];
+  retiredSecondaryIndexRuns?: SecondaryIndexRunRow[];
+  lexiconIndexStates?: LexiconIndexStateRow[];
+  lexiconIndexRuns?: LexiconIndexRunRow[];
+  retiredLexiconIndexRuns?: LexiconIndexRunRow[];
+  searchCompanionPlan?: SearchCompanionPlanRow | null;
+  searchSegmentCompanions?: SearchSegmentCompanionRow[];
+};
+
+export function buildManifestResult(args: BuildManifestArgs): Result<ManifestJson, ManifestBuildError> {
+  const {
+    streamName,
+    streamRow,
+    publishedLogicalSizeBytes,
+    profileJson,
+    segmentMeta,
+    uploadedPrefixCount,
+    generation,
+    indexState,
+    indexRuns,
+    retiredRuns,
+  } = args;
+
+  const createdAt = new Date(Number(streamRow.created_at_ms)).toISOString();
+  const expiresAt = streamRow.expires_at_ms == null ? null : new Date(Number(streamRow.expires_at_ms)).toISOString();
+
+  const nextOffset = streamRow.next_offset;
+  const nextOffsetNum = Number(nextOffset);
+  const nextOffsetEncodedRes = encodeOffsetResult(streamRow.epoch, nextOffset);
+  if (Result.isError(nextOffsetEncodedRes)) return invalidManifest(nextOffsetEncodedRes.error.message);
+  const nextOffsetEncoded = nextOffsetEncodedRes.value;
+
+  const maxCount = Math.max(0, segmentMeta.segment_count);
+  const prefix = Math.max(0, Math.min(uploadedPrefixCount, maxCount));
+  const offBytes = segmentMeta.segment_offsets.subarray(0, prefix * 8);
+  const blockBytes = segmentMeta.segment_blocks.subarray(0, prefix * 4);
+  const lastTsBytes = segmentMeta.segment_last_ts.subarray(0, prefix * 8);
+
+  const segOffsetsB64 = compressB64(offBytes);
+  const segBlocksB64 = compressB64(blockBytes);
+  const segLastTsB64 = compressB64(lastTsBytes);
+
+  const activeRuns =
+    indexRuns?.map((r) => ({
+      run_id: r.run_id,
+      level: r.level,
+      start_segment: r.start_segment,
+      end_segment: r.end_segment,
+      object_key: r.object_key,
+      size_bytes: r.size_bytes,
+      filter_len: r.filter_len,
+      record_count: r.record_count,
+    })) ?? [];
+  const retired = retiredRuns?.map((r) => ({
+    run_id: r.run_id,
+    level: r.level,
+      start_segment: r.start_segment,
+      end_segment: r.end_segment,
+      object_key: r.object_key,
+      size_bytes: r.size_bytes,
+      filter_len: r.filter_len,
+      record_count: r.record_count,
+      retired_gen: r.retired_gen ?? undefined,
+    retired_at_unix: r.retired_at_ms != null ? Number(r.retired_at_ms / 1000n) : undefined,
+  })) ?? [];
+  const indexSecret = indexState?.index_secret ? b64(indexState.index_secret) : "";
+  const indexedThrough = indexState?.indexed_through ?? 0;
+  const secondaryIndexes: Record<string, any> = {};
+  const secondaryStates = args.secondaryIndexStates ?? [];
+  const secondaryRuns = args.secondaryIndexRuns ?? [];
+  const retiredSecondaryRuns = args.retiredSecondaryIndexRuns ?? [];
+  for (const state of secondaryStates) {
+    secondaryIndexes[state.index_name] = {
+      index_secret: b64(state.index_secret),
+      config_hash: state.config_hash,
+      indexed_through: state.indexed_through,
+      active_runs: secondaryRuns
+        .filter((run) => run.index_name === state.index_name)
+        .map((run) => ({
+          run_id: run.run_id,
+          level: run.level,
+          start_segment: run.start_segment,
+          end_segment: run.end_segment,
+          object_key: run.object_key,
+          size_bytes: run.size_bytes,
+          filter_len: run.filter_len,
+          record_count: run.record_count,
+        })),
+      retired_runs: retiredSecondaryRuns
+        .filter((run) => run.index_name === state.index_name)
+        .map((run) => ({
+          run_id: run.run_id,
+          level: run.level,
+          start_segment: run.start_segment,
+          end_segment: run.end_segment,
+          object_key: run.object_key,
+          size_bytes: run.size_bytes,
+          filter_len: run.filter_len,
+          record_count: run.record_count,
+          retired_gen: run.retired_gen ?? undefined,
+          retired_at_unix: run.retired_at_ms != null ? Number(run.retired_at_ms / 1000n) : undefined,
+        })),
+      };
+  }
+  const lexiconIndexes = (args.lexiconIndexStates ?? []).map((state) => ({
+    source_kind: state.source_kind,
+    source_name: state.source_name,
+    indexed_through: state.indexed_through,
+    active_runs: (args.lexiconIndexRuns ?? [])
+      .filter((run) => run.source_kind === state.source_kind && run.source_name === state.source_name)
+      .map((run) => ({
+        run_id: run.run_id,
+        level: run.level,
+        start_segment: run.start_segment,
+        end_segment: run.end_segment,
+        object_key: run.object_key,
+        size_bytes: run.size_bytes,
+        record_count: run.record_count,
+      })),
+    retired_runs: (args.retiredLexiconIndexRuns ?? [])
+      .filter((run) => run.source_kind === state.source_kind && run.source_name === state.source_name)
+      .map((run) => ({
+        run_id: run.run_id,
+        level: run.level,
+        start_segment: run.start_segment,
+        end_segment: run.end_segment,
+        object_key: run.object_key,
+        size_bytes: run.size_bytes,
+        record_count: run.record_count,
+        retired_gen: run.retired_gen ?? undefined,
+        retired_at_unix: run.retired_at_ms != null ? Number(run.retired_at_ms / 1000n) : undefined,
+      })),
+  }));
+  const searchCompanionPlan = args.searchCompanionPlan ?? null;
+  const searchCompanionSegments = (args.searchSegmentCompanions ?? [])
+    .filter((segment) => segment.segment_index < prefix)
+    .map((segment) => ({
+      segment_index: segment.segment_index,
+      object_key: segment.object_key,
+      size_bytes: segment.size_bytes,
+      plan_generation: segment.plan_generation,
+      primary_timestamp_min_ms: segment.primary_timestamp_min_ms?.toString() ?? undefined,
+      primary_timestamp_max_ms: segment.primary_timestamp_max_ms?.toString() ?? undefined,
+      sections: parseSectionsJson(segment.sections_json),
+      section_sizes: JSON.parse(segment.section_sizes_json || "{}"),
+    }));
+
+  return Result.ok({
+    name: streamName,
+    created_at: createdAt,
+    expires_at: expiresAt,
+    content_type: streamRow.content_type,
+    profile: streamRow.profile ?? "generic",
+    profile_json: profileJson ?? null,
+    stream_seq: streamRow.stream_seq ?? null,
+    closed: streamRow.closed,
+    closed_producer_id: streamRow.closed_producer_id ?? null,
+    closed_producer_epoch: streamRow.closed_producer_epoch ?? null,
+    closed_producer_seq: streamRow.closed_producer_seq ?? null,
+    ttl_seconds: streamRow.ttl_seconds ?? null,
+    stream_flags: streamRow.stream_flags,
+    generation,
+    epoch: streamRow.epoch,
+    next_offset: nextOffsetNum,
+    next_offset_encoded: nextOffsetEncoded,
+    logical_size_bytes: publishedLogicalSizeBytes.toString(),
+    segment_count: prefix,
+    uploaded_through: prefix,
+    active_file_offset: nextOffsetNum,
+    last_committed_ts: Number(streamRow.last_append_ms * 1_000_000n),
+    zstd_dict: "",
+    segment_offsets: segOffsetsB64,
+    segment_blocks: segBlocksB64,
+    segment_last_ts: segLastTsB64,
+    indexed_through: indexedThrough,
+    index_secret: indexSecret,
+    active_runs: activeRuns,
+    retired_runs: retired,
+    secondary_indexes: secondaryIndexes,
+    lexicon_indexes: lexiconIndexes,
+    search_companions: searchCompanionPlan
+      ? {
+          generation: searchCompanionPlan.generation,
+          plan_hash: searchCompanionPlan.plan_hash,
+          plan_json: JSON.parse(searchCompanionPlan.plan_json),
+          segments: searchCompanionSegments,
+        }
+      : null,
+  });
+}
+
+export function buildManifest(args: BuildManifestArgs): ManifestJson {
+  const res = buildManifestResult(args);
+  if (Result.isError(res)) throw dsError(res.error.message);
+  return res.value;
+}

package/src/memory.ts

@@ -0,0 +1,334 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+
+const HOST_MEMORY_GUARD_FRACTION = 0.7;
+const HOST_MEMORY_HEADROOM_FRACTION = 0.15;
+const HOST_MEMORY_HEADROOM_MIN_BYTES = 512 * 1024 * 1024;
+const HOST_MEMORY_HEADROOM_MAX_BYTES = 2 * 1024 * 1024 * 1024;
+
+export function deriveMemoryPressureLimitBytes(requestedLimitBytes: number, hostTotalBytes = os.totalmem()): number {
+  const requested = Math.max(0, Math.floor(requestedLimitBytes));
+  if (requested <= 0) return 0;
+  if (!Number.isFinite(hostTotalBytes) || hostTotalBytes <= 0) return requested;
+  const safeHostCap = Math.max(256 * 1024 * 1024, Math.floor(hostTotalBytes * HOST_MEMORY_GUARD_FRACTION));
+  return Math.min(requested, safeHostCap);
+}
+
+export function deriveMemoryPressureHeadroomBytes(limitBytes: number, hostTotalBytes = os.totalmem()): number {
+  const limit = Math.max(0, Math.floor(limitBytes));
+  if (limit <= 0) return 0;
+  if (!Number.isFinite(hostTotalBytes) || hostTotalBytes <= 0) {
+    return Math.min(limit, HOST_MEMORY_HEADROOM_MIN_BYTES);
+  }
+  const headroomFromHost = Math.floor(hostTotalBytes * HOST_MEMORY_HEADROOM_FRACTION);
+  const headroom = Math.max(HOST_MEMORY_HEADROOM_MIN_BYTES, headroomFromHost);
+  return Math.min(limit, Math.min(HOST_MEMORY_HEADROOM_MAX_BYTES, headroom));
+}
+
+export class MemoryPressureMonitor {
+  private readonly limitBytes: number;
+  private readonly resumeBytes: number;
+  private readonly hostHeadroomBytes: number;
+  private readonly hostResumeHeadroomBytes: number;
+  private readonly intervalMs: number;
+  private readonly onSample?: (rssBytes: number, overLimit: boolean, limitBytes: number) => void;
+  private readonly heapSnapshotPath?: string;
+  private readonly heapSnapshotMinIntervalMs: number;
+  private timer: any | null = null;
+  private overLimit = false;
+  private maxRssBytes = 0;
+  private lastRssBytes = 0;
+  private lastGcMs = 0;
+  private forcedGcCount = 0;
+  private forcedGcReclaimedBytesTotal = 0;
+  private lastForcedGcAtMs = 0;
+  private lastForcedGcBeforeBytes = 0;
+  private lastForcedGcAfterBytes = 0;
+  private lastForcedGcReclaimedBytes = 0;
+  private lastSnapshotMs = 0;
+  private heapSnapshotsWritten = 0;
+  private lastDarwinPhysicalBytes = 0;
+  private lastDarwinPhysicalAtMs = 0;
+
+  constructor(
+    limitBytes: number,
+    opts: {
+      resumeFraction?: number;
+      intervalMs?: number;
+      onSample?: (rssBytes: number, overLimit: boolean, limitBytes: number) => void;
+      heapSnapshotPath?: string;
+      heapSnapshotMinIntervalMs?: number;
+    } = {}
+  ) {
+    const requestedLimitBytes = Math.max(0, Math.floor(limitBytes));
+    this.limitBytes = deriveMemoryPressureLimitBytes(requestedLimitBytes);
+    const initialRssBytes = process.memoryUsage().rss;
+    this.lastRssBytes = initialRssBytes;
+    this.maxRssBytes = initialRssBytes;
+    if (requestedLimitBytes > 0 && this.limitBytes < requestedLimitBytes) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[memory] clamped limit from ${formatBytes(requestedLimitBytes)} to ${formatBytes(this.limitBytes)} based on host memory`
+      );
+    }
+    // Resume as soon as RSS drops back below the limit by default (no hysteresis),
+    // so the server doesn't "deadlock" itself under a stable high-water mark.
+    const resumeFraction = Math.min(1.0, Math.max(0.5, opts.resumeFraction ?? 1.0));
+    this.resumeBytes = Math.floor(this.limitBytes * resumeFraction);
+    this.hostHeadroomBytes = deriveMemoryPressureHeadroomBytes(this.limitBytes);
+    this.hostResumeHeadroomBytes = Math.floor(this.hostHeadroomBytes * 1.25);
+    this.intervalMs = Math.max(50, opts.intervalMs ?? 1000);
+    this.onSample = opts.onSample;
+    this.heapSnapshotPath = opts.heapSnapshotPath;
+    this.heapSnapshotMinIntervalMs = Math.max(1000, opts.heapSnapshotMinIntervalMs ?? 60_000);
+  }
+
+  start(): void {
+    if (this.timer) return;
+    if (this.limitBytes <= 0) return;
+    this.sample();
+    this.timer = setInterval(() => this.sample(), this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  private sample(): void {
+    const rss = process.memoryUsage().rss;
+    const effectiveBytes = this.effectiveBytesForGuard(rss);
+    const hostAvailableBytes = readHostAvailableMemoryBytes();
+    this.lastRssBytes = rss;
+    if (rss > this.maxRssBytes) this.maxRssBytes = rss;
+    const hostLowMemory = this.hostHeadroomBytes > 0 && hostAvailableBytes <= this.hostHeadroomBytes;
+    const overLimit = this.limitBytes > 0 && (effectiveBytes > this.limitBytes || hostLowMemory);
+    if (this.onSample) {
+      try {
+        this.onSample(rss, overLimit, this.limitBytes);
+      } catch {
+        // ignore
+      }
+    }
+    if (this.limitBytes <= 0) return;
+    if (overLimit) {
+      this.maybeGc(hostLowMemory ? "host memory headroom" : "memory sample");
+      this.maybeHeapSnapshot(hostLowMemory ? "host memory headroom" : "memory sample");
+    }
+    if (this.overLimit) {
+      if (effectiveBytes <= this.resumeBytes && hostAvailableBytes > this.hostResumeHeadroomBytes) this.overLimit = false;
+    } else if (effectiveBytes > this.limitBytes) {
+      this.overLimit = true;
+    } else if (hostLowMemory) {
+      this.overLimit = true;
+    }
+  }
+
+  private effectiveBytesForGuard(rssBytes: number): number {
+    if (this.limitBytes <= 0 || rssBytes <= this.limitBytes) return rssBytes;
+    if (process.platform !== "darwin") return rssBytes;
+    const now = Date.now();
+    if (this.lastDarwinPhysicalAtMs !== 0 && now - this.lastDarwinPhysicalAtMs < 5_000) {
+      return this.lastDarwinPhysicalBytes > 0 ? this.lastDarwinPhysicalBytes : this.limitBytes;
+    }
+    this.lastDarwinPhysicalAtMs = now;
+    const physicalBytes = readDarwinTopMemBytes(process.pid);
+    if (physicalBytes != null) {
+      this.lastDarwinPhysicalBytes = physicalBytes;
+      return physicalBytes;
+    }
+    if (this.lastDarwinPhysicalBytes > 0) return this.lastDarwinPhysicalBytes;
+    this.lastDarwinPhysicalBytes = this.limitBytes;
+    return this.lastDarwinPhysicalBytes;
+  }
+
+  isOverLimit(): boolean {
+    return this.overLimit;
+  }
+
+  getMaxRssBytes(): number {
+    return this.maxRssBytes;
+  }
+
+  snapshotMaxRssBytes(reset = true): number {
+    const max = this.maxRssBytes;
+    if (reset) this.maxRssBytes = this.lastRssBytes;
+    return max;
+  }
+
+  getLastRssBytes(): number {
+    return this.lastRssBytes;
+  }
+
+  getLimitBytes(): number {
+    return this.limitBytes;
+  }
+
+  getGcStats(): {
+    forced_gc_count: number;
+    forced_gc_reclaimed_bytes_total: number;
+    last_forced_gc_at_ms: number | null;
+    last_forced_gc_before_bytes: number | null;
+    last_forced_gc_after_bytes: number | null;
+    last_forced_gc_reclaimed_bytes: number | null;
+    heap_snapshots_written: number;
+    last_heap_snapshot_at_ms: number | null;
+  } {
+    return {
+      forced_gc_count: this.forcedGcCount,
+      forced_gc_reclaimed_bytes_total: this.forcedGcReclaimedBytesTotal,
+      last_forced_gc_at_ms: this.lastForcedGcAtMs > 0 ? this.lastForcedGcAtMs : null,
+      last_forced_gc_before_bytes: this.lastForcedGcAtMs > 0 ? this.lastForcedGcBeforeBytes : null,
+      last_forced_gc_after_bytes: this.lastForcedGcAtMs > 0 ? this.lastForcedGcAfterBytes : null,
+      last_forced_gc_reclaimed_bytes: this.lastForcedGcAtMs > 0 ? this.lastForcedGcReclaimedBytes : null,
+      heap_snapshots_written: this.heapSnapshotsWritten,
+      last_heap_snapshot_at_ms: this.lastSnapshotMs > 0 ? this.lastSnapshotMs : null,
+    };
+  }
+
+  maybeGc(reason: string): void {
+    const gcFn = (globalThis as any)?.Bun?.gc;
+    if (typeof gcFn !== "function") return;
+    const now = Date.now();
+    if (now - this.lastGcMs < 10_000) return;
+    this.lastGcMs = now;
+    const before = process.memoryUsage().rss;
+    try {
+      gcFn(true);
+    } catch {
+      try {
+        gcFn();
+      } catch {
+        return;
+      }
+    }
+    const after = process.memoryUsage().rss;
+    const reclaimed = Math.max(0, before - after);
+    this.forcedGcCount += 1;
+    this.forcedGcReclaimedBytesTotal += reclaimed;
+    this.lastForcedGcAtMs = now;
+    this.lastForcedGcBeforeBytes = before;
+    this.lastForcedGcAfterBytes = after;
+    this.lastForcedGcReclaimedBytes = reclaimed;
+    // eslint-disable-next-line no-console
+    console.warn(`[gc] forced GC (${reason}) rss ${formatBytes(before)} -> ${formatBytes(after)}`);
+  }
+
+  maybeHeapSnapshot(reason: string): void {
+    if (!this.heapSnapshotPath) return;
+    const now = Date.now();
+    if (now - this.lastSnapshotMs < this.heapSnapshotMinIntervalMs) return;
+    this.lastSnapshotMs = now;
+    void this.writeHeapSnapshot(reason);
+  }
+
+  private async writeHeapSnapshot(reason: string): Promise<void> {
+    try {
+      const v8 = await import("v8");
+      if (typeof v8.writeHeapSnapshot !== "function") return;
+      const fs = await import("node:fs");
+      try {
+        fs.unlinkSync(this.heapSnapshotPath!);
+      } catch {
+        // ignore
+      }
+      const before = process.memoryUsage().rss;
+      v8.writeHeapSnapshot(this.heapSnapshotPath);
+      const after = process.memoryUsage().rss;
+      this.heapSnapshotsWritten += 1;
+      // eslint-disable-next-line no-console
+      console.warn(`[heap] snapshot (${reason}) rss ${formatBytes(before)} -> ${formatBytes(after)} path=${this.heapSnapshotPath}`);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(`[heap] snapshot failed (${reason}): ${String(err)}`);
+    }
+  }
+}
+
+export function parseDarwinTopMemBytes(output: string, pid: number): number | null {
+  const line = output
+    .split(/\r?\n/)
+    .map((entry) => entry.trim())
+    .find((entry) => new RegExp(`^${pid}\\s+`).test(entry));
+  if (!line) return null;
+  const match = line.match(new RegExp(`^${pid}\\s+([0-9]+(?:\\.[0-9]+)?)([BKMGTP])\\+?\\b`, "i"));
+  if (!match) return null;
+  const value = Number(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const unit = match[2]!.toUpperCase();
+  const power =
+    unit === "B"
+      ? 0
+      : unit === "K"
+        ? 1
+        : unit === "M"
+          ? 2
+          : unit === "G"
+            ? 3
+            : unit === "T"
+              ? 4
+              : unit === "P"
+                ? 5
+                : -1;
+  if (power < 0) return null;
+  return Math.round(value * 1024 ** power);
+}
+
+export function darwinTopMemArgs(pid: number): string[] {
+  return ["-l", "1", "-pid", String(pid), "-stats", "pid,mem"];
+}
+
+export function parseLinuxMemAvailableBytes(meminfo: string): number | null {
+  for (const line of meminfo.split(/\r?\n/)) {
+    const match = line.match(/^MemAvailable:\s+([0-9]+)\s+kB$/i);
+    if (!match) continue;
+    const kb = Number(match[1]);
+    if (!Number.isFinite(kb) || kb < 0) return null;
+    return kb * 1024;
+  }
+  return null;
+}
+
+function readLinuxMemAvailableBytes(): number | null {
+  try {
+    const meminfo = readFileSync("/proc/meminfo", "utf8");
+    return parseLinuxMemAvailableBytes(meminfo);
+  } catch {
+    return null;
+  }
+}
+
+function readHostAvailableMemoryBytes(): number {
+  if (process.platform === "linux") {
+    const available = readLinuxMemAvailableBytes();
+    if (available != null) return available;
+  }
+  return os.freemem();
+}
+
+function readDarwinTopMemBytes(pid: number): number | null {
+  try {
+    const output = execFileSync("/usr/bin/top", darwinTopMemArgs(pid), {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5_000,
+      maxBuffer: 256 * 1024,
+    });
+    return parseDarwinTopMemBytes(output, pid);
+  } catch {
+    return null;
+  }
+}
+
+export function formatBytes(bytes: number): string {
+  const units = ["b", "kb", "mb", "gb"];
+  let value = bytes;
+  let idx = 0;
+  while (value >= 1024 && idx < units.length - 1) {
+    value /= 1024;
+    idx += 1;
+  }
+  const digits = idx === 0 ? 0 : 1;
+  return `${value.toFixed(digits)}${units[idx]}`;
+}