TypeScript API / laikacms/storage/web-fs / WebFsDataSource

Class: WebFsDataSource

WebFsDataSource provides low-level operations for interacting with a web File System API directory tree — any object satisfying the WebFsDirectoryHandle contract, whether it points into the origin-private file system or a user-picked on-disk directory; where the handle came from is deliberately none of this module's business. Unlike the flat stores (storage-r2, storage-web) there is no simulated hierarchy: folders are real directories, empty folders exist without .keep markers, and object contents are stored as raw files (readable by any other consumer of the same directory tree).

All operations are scoped under ${namespace} — a real subdirectory chain below the provided root — so repositories sharing one root under different namespaces never observe each other's entries (or unrelated data already in the same tree). File extensions are handled transparently and encoded in the physical file name, mirroring the other storage implementations.

Constructors

Constructor

new WebFsDataSource(
   rootProvider, 
   namespace, 
   availableExtensions?, 
   mode?
): WebFsDataSource;

Parameters

Parameter	Type	Default value
rootProvider	WebFsRootProvider	undefined
namespace	string	undefined
availableExtensions	string[]	[]
mode	WebFsAccessMode	'readwrite'

Returns

WebFsDataSource

Methods

createFolder()

createFolder(key): Promise<LaikaResult<void>>;

Create a real (possibly empty) directory chain — no .keep marker involved.

Parameters

Parameter	Type
key	string

Returns

Promise<LaikaResult<void>>

---

createOrUpdate()

createOrUpdate(
   key, 
   content, 
   extension
): Promise<LaikaResult<{
  key: string;
}>>;

Parameters

Parameter	Type
key	string
content	string
extension	string

Returns

Promise<LaikaResult<{ key: string; }>>

---

deleteAtoms()

deleteAtoms(keys): AsyncGenerator<LaikaResult<string>>;

Delete atoms by their logical key: objects first, then folders. Folders must be empty — recursive deletion is refused (mirrors storage-fs's security stance).

Parameters

Parameter	Type
keys	readonly string[]

Returns

AsyncGenerator<LaikaResult<string>>

---

findExistingObjectExtension()

findExistingObjectExtension(key): Promise<string | null>;

Check if an object exists with any of the available extensions. Returns the extension if found.

Parameters

Parameter	Type
key	string

Returns

Promise<string | null>

---

getFolderMeta()

getFolderMeta(key): Promise<LaikaResult<{
  createdAt: Date;
  updatedAt: Date;
}>>;

Folders are real directories, so existence is a direct handle lookup — no prefix scanning or .keep markers. Timestamps are synthesized: the File System API exposes none for directories.

Parameters

Parameter	Type
key	string

Returns

Promise<LaikaResult<{ createdAt: Date; updatedAt: Date; }>>

---

getObjectContents()

getObjectContents(key): Promise<LaikaResult<{
  content: string;
  extension: string;
  key: string;
}>>;

Parameters

Parameter	Type
key	string

Returns

Promise<LaikaResult<{ content: string; extension: string; key: string; }>>

---

getObjectMeta()

getObjectMeta(key): Promise<LaikaResult<{
  createdAt: Date;
  extension: string;
  key: string;
  updatedAt: Date;
}>>;

The File System API keeps a single timestamp per file (File.lastModified); creation time is not recorded, so createdAt falls back to the last modification — the same degradation storage-fs applies on filesystems without a birth time.

Parameters

Parameter	Type
key	string

Returns

Promise<LaikaResult<{ createdAt: Date; extension: string; key: string; updatedAt: Date; }>>

---

listDirectory()

listDirectory(prefix): Promise<LaikaResult<WebFsEntry[]>>;

List the immediate children of prefix (one level — same semantics as the other storage implementations' directory listings). An existing empty directory yields an empty array; only a genuinely missing directory is a NotFoundError.

Parameters

Parameter	Type
prefix	string

Returns

Promise<LaikaResult<WebFsEntry[]>>