SDK: files and storage

View as Markdown

The methods are on app.files, app.trash and app.jobs (see app and connection); this page has the types they take and return. Paths are relative to a location with / as separator; an app never sees a path on the host.

Generated from the TSDoc comments of @pithyx/sdk 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.

Interfaces

ShareLocation

A share from files.shares, the only location the versions and the recycle bin take: a storage request is a folder inside a share, without snapshots or a bin of its own.

Properties

share: string;

The id of a share from files.shares.

FileEntry

One entry of a folder.

Properties

name

name: string;

Name within its folder.

kind

kind: FileKind;

What the entry is.

size

size: number;

Bytes for files, 0 for folders.

modified

modified: string;

Last change of the content, ISO 8601 UTC.

ShareInfo

A share the user can use, with the user’s own access.

Properties

id

id: string;

Stable id, used as { share: id }.

name

name: string;

Name shown to users.

access

access: 'read' | 'readWrite';

The user’s access: read, or readWrite to change files.

unavailable?

optional unavailable?: "poolMissing" | "poolUnavailable" | "notMounted";

Set while the share’s files cannot be reached: poolMissing (its disks are not connected), poolUnavailable (its pool stopped because disks are missing) or notMounted. Calls on it fail with fs.share.unavailable until the share is back, which sharesChanged announces.

kind?

optional kind?: "home" | "userHome";

Set for a home instead of a shared folder: home is the user’s own (named home), userHome another user’s home (named after its folder), which only the core apps of administrators see. Left out for a shared folder.

FolderPage

One page of a folder.

Properties

path

path: string;

The folder, relative to its location (“” for the root).

folderId

folderId: string;

Stable id of the folder, also after a rename.

total

total: number;

Entries in the folder when the page was read.

entries

entries: FileEntry[];

This page, in the requested order.

nextCursor

nextCursor: string | null;

Pass as cursor for the next page; null on the last page. The cursor stays valid while the folder changes.

FileSelection

A selection in one folder.

Properties

location

location: FileLocation;

Where the folder is: a share, or a storage request of the manifest.

folder

folder: string;

The folder the names are in.

items

items: FileItems;

The entries of the folder that are meant.

FileOperation

A copy, move or delete that runs as a job.

Properties

kind

kind: 'copy' | 'move' | 'delete';

What to do. A move within one file system is a rename; across file systems it copies, then deletes.

source

source: FileSelection;

The entries to work on, all in one folder.

target?

optional target?: object;

The folder to copy or move into. Required for copy and move, not allowed for delete.

location

location: FileLocation;

Where the target folder is: a share, or a storage request of the manifest.

path

path: string;

The target folder, relative to its location.

onConflict?

optional onConflict?: ConflictPolicy;

For copy and move; fail when left out.

permanent?

optional permanent?: boolean;

For delete: remove for good instead of moving to the share’s recycle bin. Set it only when the user explicitly asked for it.

JobInfo

A long operation of the user, and its progress.

Properties

id

id: number;

Id for jobs.cancel and in jobChanged events.

kind

kind: string;

For example files.copy, files.trash, files.restore.

state

state: JobState;

Where the job is.

progress

progress: object;

Entries and bytes done and in total; totals grow while a job still counts what it works on.

itemsDone

itemsDone: number;

Entries finished.

itemsTotal

itemsTotal: number;

Entries counted so far.

bytesDone

bytesDone: number;

Bytes copied or moved.

bytesTotal

bytesTotal: number;

Bytes counted so far.

current

current: string | null;

The entry being worked on, relative to its location.

problem

problem: Problem | null;

Why the job failed, with the stable code and its params.

result

result:
  | {
  done: number;
  skipped: string[];
}
  | null;

When it finished: entries done and paths left out (conflicts with skip, symlinks, which are never copied).

Union Members

Type Literal

{
  done: number;
  skipped: string[];
}

done

done: number;

Entries the job finished.

skipped

skipped: string[];

Paths it left out.

null

TrashEntry

An item in a share’s recycle bin.

Properties

id

id: number;

Id for restoring or deleting it for good.

name

name: string;

Its name when it was deleted.

originalPath

originalPath: string;

Where it was, relative to the share; restoring puts it back there.

kind

kind: FileKind;

What it was.

size

size: number;

Bytes, for a folder everything inside it.

deletedAt

deletedAt: string;

When it was deleted, ISO 8601 UTC.

deletedBy

deletedBy: string | null;

User name of who deleted it, if that user still exists.

expiresAt

expiresAt: string | null;

When it is deleted for good, or null when the share keeps items until the bin is emptied.

TrashPage

One page of a recycle bin, newest first.

Properties

items

items: TrashEntry[];

This page of the bin.

nextCursor

nextCursor: string | null;

Pass as cursor for the next page; null on the last page.

retentionDays

retentionDays: number;

Days the share keeps deleted items; 0 keeps them until the bin is emptied.

FileVersion

An earlier version of a file or folder, from a snapshot of the share’s dataset.

Properties

snapshot

snapshot: string;

The snapshot it is in; pass it to files.restoreVersion.

createdAt

createdAt: string;

When the snapshot was taken, ISO 8601 UTC.

kind

kind: FileKind;

File or folder.

size

size: number;

Bytes for files, 0 for folders.

modified

modified: string;

Last change of the content in that version, ISO 8601 UTC.

FolderChange

Changes of a watched folder since the last event.

Properties

watch

watch: string;

The id files.watch returned.

changed

changed: FileEntry[];

Entries that appeared or changed, with their current metadata.

removed

removed: string[];

Names that are gone.

resync

resync: boolean;

Changes were lost (the kernel queue overflowed): list the folder again.

gone

gone: boolean;

The folder itself was deleted or moved away; no more events come for this watch.

UploadProgress

Progress of an upload started with an upload id.

Properties

upload

upload: string;

The id given to files.upload.

loaded

loaded: number;

Bytes sent so far.

total

total: number;

Size of the file in bytes.

StorageRequest

A place for files the app needs, declared by name and shown to the administrator with its name, for example “Photo library”. At install an administrator maps it to a folder in a shared folder (and can change that later). The app only ever sees the name and paths inside it: the window reaches it through the SDK file API as { storage: id }, the backend services listed in services find it as the Compose volume named id. Users reach it with their own rights on the mapped folder, never with more than access.

Properties

id

id: string;

Unique within the app.

name

name: LocalizedName;

description?

optional description?: LocalizedText;

access

access: 'read' | 'readWrite';

The most the app may do with the mapped folder: read or readWrite. Users never get more than their own rights on the folder, and with read every backend service mounts it read-only.

required

required: boolean;

The app cannot start until this storage is mapped.

services?

optional services?: string[];

Backend services that mount this storage. Needs a backend.

Min Items

FileHandler

Files the app can open. The desktop offers the app in “Open with” only for these types and sends it only such files (launch, openFile). An extension belongs to one handler only.

Properties

extensions

extensions: string[];

Lowercase extensions without the leading dot, for example png or tar.gz.

Min Items

Max Items

mimeTypes?

optional mimeTypes?: string[];

MIME types, for example image/png.

Min Items

Max Items

isDefault?

optional isDefault?: boolean;

Whether the app is the default for these files when it is the only handler.

FileRef

A file the user handed to the app (opened with it, or picked in a desktop dialog). The app never learns where the file is: ref is an opaque handle, valid for this user and app, that only the SDK file API accepts.

Properties

ref

ref: string;

Opaque handle; only the SDK file API accepts it.

name

name: string;

File name with extension, for display.

type?

optional type?: string;

MIME type, when known.

size

size: number;

Size in bytes.

modified

modified: string;

Last change, ISO 8601 UTC.

writable

writable: boolean;

Whether the app may write it (files.write and the user’s rights on it).

StorageInfo

A storage request of the manifest and where it stands.

Properties

id

id: string;

The id of the request in the manifest; reach it as { storage: id }.

state

state: StorageState;

Whether the storage can be used now.

access

access: 'read' | 'readWrite' | null;

What the mapping allows (never more than the manifest requests), or null while it is unmapped.

Type Aliases

FileKind

type FileKind = 'file' | 'folder' | 'symlink' | 'other';

What an entry is. Symlinks are listed as themselves and never followed in listings.

FileLocation

type FileLocation =
  | {
      storage: string;
    }
  | ShareLocation;

Where paths start: a named storage from the manifest, or a share by its id (needs files.shares). Paths inside are relative, with / as separator, and never leave it; . and .. are refused.

Union Members

Type Literal

{
  storage: string;
}

storage

storage: string;

The id of a storage request in the manifest.

ShareLocation

SortKey

type SortKey = 'name' | 'size' | 'modified';

Order of a folder listing. Name order is natural (“file2” before “file10”) and ignores case.

SortOrder

type SortOrder = 'asc' | 'desc';

Ascending or descending; folders count as the smallest size.

FileItems

type FileItems =
  | {
      names: string[];
    }
  | {
      all: true;
      except: string[];
    };

Entries of one folder that an operation works on. all with except names a whole folder without listing it, so selecting everything in a folder of 100,000 entries never sends 100,000 names.

Union Members

Type Literal

{
  names: string[];
}

names

names: string[];

The names of the entries, 1 to 1000.

Type Literal

{
  all: true;
  except: string[];
}

all

all: true;

Every entry of the folder.

except

except: string[];

Names to leave out, at most 1000.

ConflictPolicy

type ConflictPolicy = 'fail' | 'skip' | 'overwrite' | 'rename';

What happens when the target already has an entry of the same name: fail stops the job with fs.entry.exists, skip leaves the entry out, overwrite replaces files and merges folders, rename picks a free name such as “Report (2).pdf”.

JobState

type JobState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted';

Where a job is: waiting, running, or finished in one of four ways (interrupted by a daemon restart).

StorageState

type StorageState = 'ready' | 'unmapped' | 'locked' | 'unavailable';

The state of a storage the manifest requests: ready (mapped to a folder that can be reached), unmapped (no administrator assigned a folder yet), locked (its pool is encrypted and locked) or unavailable (its pool or folder is missing).