Skip to main content

File handler

import * as mod from "jsr:@nzip/lofi/recipes/file-handler";

Opt-in helpers for turning file launches or ordinary picker files into bounded, validated import drafts.

installFileLaunchConsumer​

function

function installFileLaunchConsumer<Parsed>(options: InstallFileLaunchConsumerOptions<Parsed>): InstalledLaunchConsumer

Feature-detect launchQueue and turn file launches into validated drafts.

prepareFileImportDrafts​

function

async function prepareFileImportDrafts<Parsed>(inputs: readonly ((File | InstalledAppFileHandle))[], options: PrepareFileImportOptions<Parsed>): Promise<FileImportResult<Parsed>>

Validate picker files or installed-app handles and parse them into drafts.

The function performs no writes. Keep the returned drafts in transient UI state, show a preview, and persist only after an explicit user confirmation.

FileImportAccept​

type

type FileImportAccept = Readonly<Record<string, readonly string[]>>;

Explicit MIME-to-extension allow-list shared by the manifest and importer.

FileImportDraft​

type

type FileImportDraft<Parsed> = {
  readonly file: File;
  readonly name: string;
  readonly type: string;
  readonly size: number;
  readonly parsed: Parsed;
};

One parsed file ready for product-owned preview, but not persistence.

FileImportIssue​

type

type FileImportIssue = 
  | "empty-selection"
  | "too-many-files"
  | "invalid-handle"
  | "unreadable-file"
  | "invalid-name"
  | "unsupported-type"
  | "unsupported-extension"
  | "file-too-large"
  | "selection-too-large"
  | "invalid-content";

Stable rejection that never contains a received file name or content.

FileImportResult​

type

type FileImportResult<Parsed> = { ok: true; drafts: readonly FileImportDraft<Parsed>[] } | { ok: false; issue: FileImportIssue; index?: number };

Accepted import drafts or a value-free rejection.

InstalledAppFileHandle​

type

type InstalledAppFileHandle = {
  readonly kind: "file";
  readonly name: string;
  getFile(): Promise<File>;
};

A minimal read-only file handle delivered by an installed-app launch.

InstallFileLaunchConsumerOptions​

type

type InstallFileLaunchConsumerOptions<Parsed> = PrepareFileImportOptions<Parsed> & { queue?: InstalledAppLaunchQueue; onDrafts(drafts: readonly FileImportDraft<Parsed>[]): void; onRejected?(issue: FileImportIssue, index?: number): void };

Options for consuming installed file launches into preview-only drafts.

PrepareFileImportOptions​

type

type PrepareFileImportOptions<Parsed> = {
  accept: FileImportAccept;
  maxFiles: number;
  maxFileBytes: number;
  maxTotalBytes?: number;
  parse(file: File): Parsed | Promise<Parsed>;
};

Limits and product-owned content parser for preparing import drafts.