FilesConfig

Name: Nabu
Author: Killian Di Vincenzo

Type Stability: stable

Definition

TypeScript

import type { FilesConfig } from '@aionbuilders/nabu';

TypeScript

interface FilesConfig {
  autoRetry?: false | AutoRetryConfig;
  importRemote?: boolean;
  maxFileSize?: number;
  maxInlineSize?: number;
  onAssetReleased?: (ref: string) => void | Promise<void>;
  onBeforePersist?: (file: File, ctx: { onProgress?: (p: number) => void; signal?: AbortSignal }) => Promise<void | { ref: string }>;
  outbox?: Outbox;
  releaseGraceMs?: number;
  resolve?: (ref: string) => string;
  store?: AssetStore;
}

Properties

Properties of FilesConfig
Property	Type	Description
`autoRetry`optional	`false \| AutoRetryConfig`	Retry on open (P-97), only meaningful with a host and a persisted editor: the uploads the outbox lists when the document is opened (interrupted, or failed earlier) are sent again by themselves, in the background, with a growing delay (`initialDelay` 2 s, doubling, `maxDelay` 60 s, `maxAttempts` 8 per session; the browser's `online` event grants a fresh series). A cancelled upload is never retried; failures of the current session are left to `block.retry()`. `false` turns it off.
`importRemote`optional	`boolean`	Opt-in, default `false`. When `true`, a remote image / media (an `http(s)` URL) pasted from the HTML of a web page is fetched and stored in the local store (and sent to `onBeforePersist`, if any) instead of being hot-linked: the block shows the original URL meanwhile (`pending`) and gets its `nabu-asset:` ref when done. A fetch that fails (network, CORS, HTTP error) or a file over `maxFileSize` keeps the original URL.
`maxFileSize`optional	`number`	Largest file (bytes) accepted; default none. A bigger file is REFUSED: the block that would have shown it is created with `status: 'rejected'`, no ref, and a readable `reason` (`too-large`).
`maxInlineSize`optional	`number`	Byte threshold for embedding files in a COPY / export (`application/x-nabu+json`, `serialize('json')`): above it (total, or for one file) the bytes are not embedded. Default 2MB.
`onAssetReleased`optional	`(ref: string) => void \| Promise<void>`	Host mode, called with the host `url` (the `ref` your `onBeforePersist` returned) of a file that THIS document no longer references in any version it keeps: after a compaction (`history: { mode: 'compact' }` / `nabu.compact()`) released it, or when `clearPersistence()` deleted the document. Nabu NEVER deletes anything at the host: you decide (another document may still use the same host file). Awaited; an error is swallowed and reported with `nabu.warn`. Never called in the default `history: 'full'` mode (nothing is released).
`onBeforePersist`optional	`(file: File, ctx: { onProgress?: (p: number) => void; signal?: AbortSignal }) => Promise<void \| { ref: string }>`	Host storage (ADR 014 §3.4). The file is always written to the local store first and the block keeps its `nabu-asset:sha256-…` ref FOREVER; the upload then runs in the background (the block is `pending`, `block.progress` follows `onProgress(0..1)`). Return `{ ref }` (where the host keeps the file): it is recorded as `assetIndex[hash].url` and the block becomes `ready`. Throw to fail (`error`, the local copy is kept, `block.retry()` runs it again). `signal` fires when the upload is cancelled (`block.cancel()`) or when the last block that shows the file is deleted — honour it. The upload is retried from the local copy after a reload (it may therefore run more than once for one file: make it idempotent).
`outbox`optional	`Outbox`	Where the uploads still to do are listed (ADR 014 §3.4), scoped to this document. Default: in memory (`createPersistedEditor`: an `IndexedDBOutbox`, next to the asset store).
`releaseGraceMs`optional	`number`	Default 10 minutes. A release (compaction, `clearPersistence()`) never deletes from the shared store a file whose record is newer than this, nor one whose age is unknown: another tab may have just added it without having saved its references yet. Such a file is skipped and reconsidered at the next compaction / clear. `0` disables the grace period.
`resolve`optional	`(ref: string) => string`	Turn a stored ref into a display URL.
`store`optional	`AssetStore`	Where the BYTES of the files live (ADR 014). Default: a `MemoryAssetStore` (`createPersistedEditor`: an `IndexedDBAssetStore` shared by all the documents of the origin). The document itself only holds `nabu-asset:sha256-<hex>` references and a metadata index (`assetIndex`).

Source: src/lib/files/files.svelte.js:35