### Start Local Docs Preview

Source: https://remotestorage.io/rs.js/docs/contributing/docs.html

Run this command to start a live preview of the documentation with automatic reloading upon changes.

```sh
npm run docs:dev
```

--------------------------------

### Install Dependencies

Source: https://remotestorage.io/rs.js/docs/contributing/building.html

Installs all necessary npm packages for development and building.

```shell
$ npm install
```

--------------------------------

### Run All Tests and Linting

Source: https://remotestorage.io/rs.js/docs/contributing/testing.html

Execute the complete test suite and code linting using npm. Ensure you have installed dependencies with `npm install` first.

```sh
$ npm run test
```

--------------------------------

### RSModule Example

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/interfaces/RSModule.html

Defines a remoteStorage module named 'examples' with a builder function that exposes an 'addItem' method. The 'addItem' method generates a random path and stores an object as a private item.

```javascript
{
  name: 'examples',
  builder: function(privateClient, publicClient) {
    return {
      exports: {
        addItem(item): function() {
          // Generate a random ID/path
          const path = [...Array(10)].map(() => String.fromCharCode(Math.floor(Math.random() * 95) + 32)).join('');
          // Store the object, and ensure it conforms to the JSON Schema
          // type `example-item`
          privateClient.storeObject('example-item', path, item);
        }
      }
    }
  }
}
```

--------------------------------

### RSModule Example

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/interfaces/RSModule.html

An example demonstrating how to define an RSModule with a name and a builder function. The builder function sets up exports for storing objects.

```APIDOC
## Interface: RSModule 

Represents a data module

### Example 
```js
{
  name: 'examples',
  builder: function(privateClient, publicClient) {
    return {
      exports: {
        addItem(item): function() {
          // Generate a random ID/path
          const path = [...Array(10)].map(() => String.fromCharCode(Math.floor(Math.random() * 95) + 32)).join('');
          // Store the object, and ensure it conforms to the JSON Schema
          // type `example-item`
          privateClient.storeObject('example-item', path, item);
        }
      }
    }
  }
}
```

### Properties 

#### builder 
> **builder** : (`privateClient`, `publicClient`) => `object`

A module builder function, which defines the actual module

##### Parameters 

###### privateClient 
`BaseClient`

###### publicClient 
`BaseClient`

#### Returns 
`object`

##### exports 
> **exports** : `object`

###### Index Signature 
[`key`: `string`]: `any`

* * *

#### name 
> **name** : `string`

The module's name, which is also the category (i.e. base folder) for document URLs on the remote storage
```

--------------------------------

### Get File Content

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Fetches raw file data from a given path. This example demonstrates how to display an image by creating a Blob and setting it as the src for an image element.

```javascript
client.getFile('path/to/some/image').then(file => {
  const blob = new Blob([file.data], { type: file.contentType });
  const targetElement = document.findElementById('my-image-element');
  targetElement.src = window.URL.createObjectURL(blob);
});
```

--------------------------------

### Example 'window' event data

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

This is an example of the event data structure received when a value is changed locally via a BaseClient method, provided 'changeEvents.window' is enabled.

```javascript
{
  path: '/public/design/color.txt',
  relativePath: 'color.txt',
  origin: 'window',
  oldValue: 'white',
  newValue: 'blue',
  oldContentType: 'text/plain',
  newContentType: 'text/plain'
}
```

--------------------------------

### Add remotestoragejs with bun

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Install the library as a development dependency using bun.

```sh
$ bun add -D remotestoragejs
```

--------------------------------

### Example Directory Listing Object

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Illustrates the structure of a directory listing object returned by getListing. Keys ending in '/' denote folders, while others represent files with metadata.

```json
{
  "@context": "http://remotestorage.io/spec/folder-description",
  "items": {
    "thumbnails/": true,
    "screenshot-20170902-1913.png": {
      "ETag": "6749fcb9eef3f9e46bb537ed020aeece",
      "Content-Length": 53698,
      "Content-Type": "image/png;charset=binary"
    },
    "screenshot-20170823-0142.png": {
      "ETag": "92ab84792ef3f9e46bb537edac9bc3a1",
      "Content-Length": 412401,
      "Content-Type": "image/png;charset=binary"
    }
  }
}
```

--------------------------------

### Local Change Event Example

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

An example of a 'change' event with the 'local' origin, typically fired during page load to populate views with existing data.

```javascript
{
  path: '/public/design/color.txt',
  relativePath: 'color.txt',
  origin: 'local',
  oldValue: undefined,
  newValue: 'white',
  oldContentType: undefined,
  newContentType: 'text/plain'
}
```

--------------------------------

### Add remotestoragejs with pnpm

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Install the library as a development dependency using pnpm.

```sh
$ pnpm add -D remotestoragejs
```

--------------------------------

### Add remotestoragejs with npm

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Install the library as a development dependency using npm.

```sh
$ npm add -D remotestoragejs
```

--------------------------------

### addEventListener()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Installs an event handler for a given event name. Typically called via the `on()` method.

```APIDOC
## Methods

### addEventListener()

> **addEventListener**(`eventName`, `handler`): `void`

Defined in: eventhandling.ts:29
Install an event handler for the given event name
Usually called via `on()`

#### Parameters

##### eventName
`string`

##### handler
`EventHandler`

#### Returns

`void`
```

--------------------------------

### Add remotestoragejs with yarn

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Install the library as a development dependency using yarn.

```sh
$ yarn add -D remotestoragejs
```

--------------------------------

### RemoteStorage.addEventListener

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Installs an event handler for a given event name. Usually called via `on()`.

```APIDOC
## Method: addEventListener

### Description
Install an event handler for the given event name. Usually called via `on()`.

### Signature
`addEventListener(eventName: string, handler: EventHandler): void`

### Parameters
*   **eventName** (`string`) - The name of the event to listen for.
*   **handler** (`EventHandler`) - The function to execute when the event is triggered.

### Returns
`void`
```

--------------------------------

### Listen for RemoteStorage Events

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Attach event handlers to the RemoteStorage instance using the `on` function. This example shows how to listen for the 'connected' event.

```javascript
remoteStorage.on('connected', function() {
  // Storage account has been connected, let’s roll!
});
```

--------------------------------

### Start RemoteStorage Synchronization

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Manually initiate synchronization to download and upload changes. This is useful for user-initiated sync actions, like pressing a sync button, especially in environments with frequent offline/online shifts.

```typescript
remoteStorage.startSync();
```

--------------------------------

### Commit Message Example with Issue Fix

Source: https://remotestorage.io/rs.js/docs/contributing/github-flow.html

Example of a commit message that includes a description of the change and references an issue that will be closed upon merging. Use keywords like 'fixes', 'closes', or 'resolves' followed by the issue number.

```git
Fix widget flickering when opening bubble (fixes #423)
```

--------------------------------

### Example 'conflict' event data

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

This is an example of the event data structure received when a local change conflicts with a remote change during the sync process. It includes the local and remote values, as well as the last known common ancestor values.

```javascript
{
  path: '/public/design/color.txt',
  relativePath: 'color.txt',
  origin: 'conflict',
  oldValue: 'blue',
  newValue: 'red',
  oldContentType: 'text/plain',
  newContentType: 'text/plain',
  // Most recent known common ancestor body of local and remote
  lastCommonValue: 'white',
  // Most recent known common ancestor contentType of local and remote
  lastCommonContentType: 'text/plain'
}
```

--------------------------------

### Get Directory Listing

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Fetches a list of child nodes (files and folders) within a specified path. The listing is returned as a JSON object.

```javascript
client.getListing().then(listing => console.log(listing));
```

--------------------------------

### Get All Objects in a Subdirectory

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Retrieves all objects within a specified subdirectory. Iterates through the returned objects and logs their paths and values.

```javascript
client.getAll('example-subdirectory/').then(objects => {
  for (var path in objects) {
    console.log(path, objects[path]);
  }
});
```

--------------------------------

### Get Foreground Sync Interval

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Retrieve the configured sync interval for when the application is in the foreground. Returns the interval in milliseconds.

```typescript
remoteStorage.getSyncInterval();
// 10000
```

--------------------------------

### Create a client and list items

Source: https://remotestorage.io/rs.js/docs/getting-started/read-and-write-data.html

Use `remoteStorage.scope()` to create a client for a specific path. Then, use `client.getListing()` to list all items within that scope.

```javascript
const client = remoteStorage.scope('/foo/');

// List all items in the "foo/" category/folder
client.getListing('').then(listing => console.log(listing));
```

--------------------------------

### startSync()

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Initiates synchronization with remote storage, downloading and uploading cached changes. Primarily useful for manual sync actions.

```APIDOC
## startSync()

### Description
Start synchronization with remote storage, downloading and uploading any changes within the cached paths.
Please consider: local changes will attempt sync immediately, and remote changes should also be synced timely when using library defaults. So this is mostly useful for letting users sync manually, when pressing a sync button for example. This might feel safer to them sometimes, esp. when shifting between offline and online a lot.

### Returns
`Promise<void>` - A Promise which resolves when the sync has finished
```

--------------------------------

### Load All Items with getAll() and Update via Events

Source: https://remotestorage.io/rs.js/docs/getting-started/loading-data.html

This method allows you to render all items at once by loading them with `getAll()` on startup. Subsequently, use only `remote` change events to handle additions, updates, and removals. Ensure the event listener is registered after loading items with `getAll()` to avoid race conditions.

```javascript
const items = await client.getAll("/my-sub-folder");

for (const path in items) {
  renderItem(path, items[path]);
}

client.on('change', event => {
  if (event.newValue) {
    renderItem(path, items[path]);
  }
});
```

--------------------------------

### Initialize RemoteStorage Instance

Source: https://remotestorage.io/rs.js/docs/getting-started/initialize-and-configure.html

Create a new instance of RemoteStorage. This is the first step to using the library.

```javascript
const remoteStorage = new RemoteStorage();
```

--------------------------------

### removeEventListener()

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Removes a previously installed event handler.

```APIDOC
## removeEventListener(eventName, handler)

### Description
Remove a previously installed event handler

### Parameters
#### eventName
`string`
#### handler
`EventHandler`

### Returns
`void`
```

--------------------------------

### Handle Local and Remote Changes with Events

Source: https://remotestorage.io/rs.js/docs/getting-started/loading-data.html

Use this approach to display items loaded from the local cache during startup and also synchronize items from remote storage afterwards. It's beneficial when you don't need to distinguish between local and remote changes.

```javascript
remoteStorage.myfavoritedrinks.on('change', function(event) {
  if (event.newValue && (! event.oldValue)) {
    console.log('Change from '+event.origin+' (add)', event);
    displayDrink(event.relativePath, event.newValue.name);
  }
});
```

--------------------------------

### removeEventListener()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Removes a previously installed event handler.

```APIDOC
## removeEventListener(eventName, handler)

### Description
Remove a previously installed event handler

### Parameters
#### eventName
- `string`
#### handler
- `EventHandler`

### Returns
- `void`
```

--------------------------------

### Instantiating RemoteStorage

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Create a new instance of the RemoteStorage class. You can optionally provide a configuration object to customize its behavior.

```APIDOC
## Constructor

### Description
Initializes a new `RemoteStorage` instance. It can be configured with various options.

### Usage
```javascript
const remoteStorage = new RemoteStorage();
```

### Configuration Options
```javascript
const remoteStorage = new RemoteStorage({
  cache: true,
  changeEvents: {
    local:    true,
    window:   false,
    remote:   true,
    conflict: true
  },
  cordovaRedirectUri: undefined,
  logging: false,
  modules: []
});
```

### Notes
- Currently, only a single `remoteStorage` instance can be used.
- For `changeEvents`, all events must be explicitly set; otherwise, unspecified events are disabled.
```

--------------------------------

### Initialize and Attach Connect Widget

Source: https://remotestorage.io/rs.js/docs/getting-started/connect-widget.html

Instantiate the Widget class with your remoteStorage instance and attach it to the DOM. This allows users to connect their storage through a pre-built UI.

```javascript
const widget = new Widget(remoteStorage);
```

```javascript
widget.attach();
```

--------------------------------

### Run Single Test File with Jaribu (PATH configured)

Source: https://remotestorage.io/rs.js/docs/contributing/testing.html

Execute a specific test file using Jaribu without needing to specify the full path to the executable, assuming `./node_modules/.bin` has been added to your system's PATH.

```sh
jaribu test/unit/foo_suite.js
```

--------------------------------

### Add remotestoragejs with deno

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Add the library from npm using deno.

```sh
$ deno add npm:remotestoragejs
```

--------------------------------

### Remove an Event Listener

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Detach a previously installed event handler from a specific event.

```typescript
remoteStorage.removeEventListener(eventName, handler);
```

--------------------------------

### Instantiate RemoteStorage with Configuration

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Create a new instance of the RemoteStorage class with a configuration object. This allows customization of caching, change events, logging, and modules. Note that all change events must be explicitly set.

```javascript
const remoteStorage = new RemoteStorage({
  cache: true,
  changeEvents: {
    local:    true,
    window:   false,
    remote:   true,
    conflict: true
  },
  cordovaRedirectUri: undefined,
  logging: false,
  modules: []
});
```

--------------------------------

### Get Object from BaseClient

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Retrieves an object from remote storage. Use this to fetch data stored previously.

```typescript
client.getObject('/path/to/object').then(obj => console.log(obj));
```

--------------------------------

### Production Build

Source: https://remotestorage.io/rs.js/docs/contributing/building.html

Creates a minified production-ready build of remotestorage.js in the release/ directory, along with a separate source map file.

```shell
$ npm run build:release
```

--------------------------------

### enable()

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Enables caching for a specified path using the ALL strategy, which proactively retrieves and caches all data.

```APIDOC
## enable()

### Description
Enable caching for a given path.
Uses caching strategy `ALL`.

### Parameters
#### path
`string` - Path to enable caching for

### Returns
`void`

### Example
```js
remoteStorage.caching.enable('/bookmarks/');
```
```

--------------------------------

### Get Background Sync Interval

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Retrieve the configured sync interval for when the application is in the background. Returns the interval in milliseconds.

```typescript
remoteStorage.getBackgroundSyncInterval();
// 60000
```

--------------------------------

### Get Item URL

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Retrieves the full, shareable URL for an item. This is particularly useful for items in the public folder.

```javascript
client.getItemURL('path/to/public/item');
```

--------------------------------

### Run Single Test File with Jaribu

Source: https://remotestorage.io/rs.js/docs/contributing/testing.html

Directly execute the test suite for a specific file using the Jaribu executable. This is useful for targeted testing.

```sh
$ ./node_modules/.bin/jaribu test/unit/cachinglayer-suite.js
```

--------------------------------

### Get JSON Object

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Retrieves a JSON object stored at a specific path. This method is used for structured data, as opposed to raw files.

```javascript
client.getObject('path/to/my/object').then(obj => {
  console.log(obj);
});
```

--------------------------------

### Get Request Timeout

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Retrieve the current network request timeout value in milliseconds. This setting affects how long remoteStorage waits for a response from the server.

```typescript
remoteStorage.getRequestTimeout();
// 30000
```

--------------------------------

### scope()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Instantiates a new client scoped to a subpath of the current client's path.

```APIDOC
## scope(path)

### Description
Instantiate a new client, scoped to a subpath of the current client's path.

### Parameters
#### path
- `string` - The path to scope the new client to

### Returns
- `BaseClient` - A new `BaseClient` operating on a subpath of the current base path
```

--------------------------------

### Get Current Sync Interval

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Retrieve the current sync interval, which can be either the background or foreground interval, or a custom one. Returns the interval in milliseconds.

```typescript
remoteStorage.getCurrentSyncInterval();
// 15000
```

--------------------------------

### getListing()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Fetches a list of items within a specified directory path, returning details about child nodes.

```APIDOC
## getListing()

### Description
Get a list of child nodes below a given path.

### Method
`getListing(path?: string, maxAge?: number | false): Promise<unknown>`

### Parameters
#### Path Parameters
- **path?** (string) - Optional - The path to query. It must end with a forward slash.
- **maxAge?** (number | false) - Optional - Either `false` or the maximum age of cached listing in milliseconds. See caching logic for read operations.

### Returns
`Promise<unknown>` - A promise for a folder listing object.

### Example
```js
client.getListing().then(listing => console.log(listing));
```

### Folder Listing Object
The folder listing is returned as a JSON object, with the root keys representing the pathnames of child nodes. Keys ending in a forward slash represent _folder nodes_ (subdirectories), while all other keys represent _data nodes_ (files/objects).
Data node information contains the item's ETag, content type and -length.
Example of a listing object:
```js
{
  "@context": "http://remotestorage.io/spec/folder-description",
  "items": {
    "thumbnails/": true,
    "screenshot-20170902-1913.png": {
      "ETag": "6749fcb9eef3f9e46bb537ed020aeece",
      "Content-Length": 53698,
      "Content-Type": "image/png;charset=binary"
    },
    "screenshot-20170823-0142.png": {
      "ETag": "92ab84792ef3f9e46bb537edac9bc3a1",
      "Content-Length": 412401,
      "Content-Type": "image/png;charset=binary"
    }
  }
}
```

### Warning
At the moment, this function only returns detailed metadata, when caching is turned off. With caching turned on, it will only contain the item names as properties with `true` as value. See issues 721 and 1108 — contributions welcome!
```

--------------------------------

### Get Public Item URL

Source: https://remotestorage.io/rs.js/docs/getting-started/share-public-data.html

Use the `getItemURL()` function to obtain the full public URL of a document. This URL can then be shared with others, allowing them to access the public data.

```javascript
const url = remoteStorage.getItemURL('public/my-document.txt');
console.log(url); // e.g. https://your-storage.com/user/files/public/my-document.txt
```

--------------------------------

### Initialize RemoteStorage with Debug Logging

Source: https://remotestorage.io/rs.js/docs/getting-started/initialize-and-configure.html

Initialize a RemoteStorage instance with debug logging enabled to monitor rs.js activity in the console.

```javascript
const remoteStorage = new RemoteStorage({logging: true});
```

--------------------------------

### Initialize Ad-Hoc Client for Public Scope

Source: https://remotestorage.io/rs.js/docs/getting-started/share-public-data.html

If using an ad-hoc client via the `scope()` method, you must initialize it with the correct public path/scope to access public data. This ensures the client is configured for public access.

```javascript
const publicScope = 'public/my-shared-data/';
const adHocClient = remoteStorage.scope(publicScope);

adHocClient.storeObject('items', 'item1', { value: 'some data' });
```

--------------------------------

### Development Build

Source: https://remotestorage.io/rs.js/docs/contributing/building.html

Builds remotestorage.js for development, watching for changes in src/ and outputting to release/. Includes source maps for debugging.

```shell
$ npm run dev
```

--------------------------------

### Configure Dropbox and Google Drive API Keys

Source: https://remotestorage.io/rs.js/docs/dropbox-and-google-drive.html

Set your Dropbox app key and Google Drive client ID to enable these storage options. The Connect widget will automatically detect and display available backends.

```javascript
remoteStorage.setApiKeys({
  dropbox: 'your-app-key',
  googledrive: 'your-client-id'
});
```

--------------------------------

### Publish to npm

Source: https://remotestorage.io/rs.js/docs/contributing/release-checklist.html

After completing all preceding steps, publish the new version of the remotestoragejs package to the npm registry.

```shell
$ npm publish
```

--------------------------------

### onActivate()

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Sets a callback function to be executed when caching is activated for a path.

```APIDOC
## onActivate()

### Description
Set a callback for when caching is activated for a path.

### Parameters
#### cb
(`firstPending`) => `void` - Callback function

### Returns
`void`
```

--------------------------------

### Configure and require RemoteStorage with AMD

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Configure RequireJS to load RemoteStorage and then require it for use in your application.

```javascript
requirejs.config({
  paths: {
    RemoteStorage: './lib/remotestorage'
  }
});

requirejs(['RemoteStorage'], function(RemoteStorage) {
  // Here goes my app
});
```

--------------------------------

### scope()

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Instantiates a BaseClient for a specific path, allowing direct data manipulation within that scope. Primarily for debugging and development.

```APIDOC
## scope(path)

### Description
This method allows you to quickly instantiate a BaseClient, which you can use to directly read and manipulate data in the connected storage account.
Please use this method only for debugging and development, and choose or create a data module for your app to use.

### Parameters
#### path
`string` - The base directory of the BaseClient that will be returned (with a leading and a trailing slash)

### Returns
`BaseClient` - A client with the specified scope (category/base directory)

### Example
```typescript
remoteStorage.scope('/pictures/').getListing('');
remoteStorage.scope('/public/pictures/').getListing('');
```
```

--------------------------------

### Write text file

Source: https://remotestorage.io/rs.js/docs/getting-started/read-and-write-data.html

Use `client.storeFile()` to write plain text content to a file within the client's scope. The first argument is the MIME type, and the second is the filename.

```javascript
// Write some text to "foo/bar.txt"
const content = 'The most simple things can bring the most happiness.';
client.storeFile('text/plain', 'bar.txt', content)
  .then(() => console.log("data has been saved"));
```

--------------------------------

### Load a module into RemoteStorage

Source: https://remotestorage.io/rs.js/docs/data-modules/defining-a-module.html

Modules can be included during RemoteStorage initialization or added dynamically later using the `addModule()` method.

```javascript
const remoteStorage = new RemoteStorage({ modules: [ Bookmarks ] });
```

```javascript
remoteStorage.addModule(Bookmarks);
```

--------------------------------

### Read/Write Operations

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

BaseClient provides methods for interacting with different types of data: folders, objects, and files.

```APIDOC
## Methods

### `getListing(path)`

- **Description**: Returns a mapping of all items within a folder.
- **Parameters**:
  - **path** (string) - The path to the folder.

### `getObject(path)`

- **Description**: Retrieves a JSON object from the specified path.
- **Parameters**:
  - **path** (string) - The path to the object.

### `storeObject(path, object)`

- **Description**: Stores a JSON object at the specified path.
- **Parameters**:
  - **path** (string) - The path to store the object.
  - **object** (object) - The JSON object to store.

### `getFile(path)`

- **Description**: Retrieves a file from the specified path.
- **Parameters**:
  - **path** (string) - The path to the file.

### `storeFile(path, file, contentType)`

- **Description**: Stores a file at the specified path.
- **Parameters**:
  - **path** (string) - The path to store the file.
  - **file** (Blob|Buffer|string) - The file content.
  - **contentType** (string) - The MIME type of the file.

### `getAll(path)`

- **Description**: Retrieves all objects or files for the given folder path.
- **Parameters**:
  - **path** (string) - The path to the folder.

### `remove(path)`

- **Description**: Removes an object or file at the specified path. Folders are created and removed implicitly.
- **Parameters**:
  - **path** (string) - The path to the item to remove.
```

--------------------------------

### Fetch Code from Remote

Source: https://remotestorage.io/rs.js/docs/contributing/github-flow.html

Fetch code from a specified remote repository. This command downloads commits, files, and refs from a remote repository into your local repo.

```bash
git fetch [username]
```

--------------------------------

### getAll()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Retrieves all objects directly located under a specified path. Supports caching options.

```APIDOC
### getAll()

> **getAll**(`path?`, `maxAge?`): `Promise`<`unknown`>

Defined in: baseclient.ts:390
Get all objects directly below a given path.

#### Parameters

##### path?
`string`
(optional) Path to the folder. Must end in a forward slash.

##### maxAge?
`number` | `false`
(optional) Either `false` or the maximum age of cached objects in milliseconds. See caching logic for read operations.

#### Returns

`Promise`<`unknown`>
A promise for a collection of items
```

--------------------------------

### set()

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Explicitly configures the caching strategy for a given path. This method is an alternative to using `enable()` and `disable()`.

```APIDOC
## set()

### Description
Configure caching for a given path explicitly.
Not needed when using `enable`/`disable`.

### Parameters
#### path
`string` - Path to cache
#### strategy
`"ALL"` | `"SEEN"` | `"FLUSH"` - Caching strategy. One of 'ALL', 'SEEN', or 'FLUSH'.

### Returns
`void`

### Example
```js
remoteStorage.caching.set('/bookmarks/archive/', 'SEEN');
```
```

--------------------------------

### Versioning Tree Diagrams of Node Revisions

Source: https://remotestorage.io/rs.js/docs/contributing/internals/cache-data-format.html

Illustrates the relationships between common, local, remote, and push revisions for documents and folders within the cache.

```text
//in sync:
1)  . . . . [common]

//dirty:
2)  . . . . [common]
                \
                 \ . . . . [remote]

//local change:
3)  . . . . [common] . . . . [local]

//conflict (should autoMerge):
4) . . . . [common] . . . . [local]
               \
                \ . . . . [remote]

//pushing:
5)  . . . . [common] . . . . [push] . . . . [local]

//pushing, and known dirty (should abort the push, or just wait for the conflict to occur):
6)  . . . . [common] . . . . [push] . . . . [local]
                \
                 \ . . . . [remote]
```

--------------------------------

### Create a Scoped BaseClient

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Instantiate a BaseClient for a specific path, useful for direct data manipulation during development or debugging. Use data modules for production applications.

```typescript
remoteStorage.scope('/pictures/').getListing('');
remoteStorage.scope('/public/pictures/').getListing('');
```

--------------------------------

### Include RemoteStorage via HTML script tag

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Link the remotestorage.js build file directly in your HTML to make RemoteStorage available as a global variable.

```html
<script type="text/javascript" src="remotestorage.js"></script>
```

--------------------------------

### Enable Caching for a Path

Source: https://remotestorage.io/rs.js/docs/getting-started/initialize-and-configure.html

Activate full caching and automatic synchronization for all items within a specified path (e.g., '/myfavoritedrinks/').

```javascript
remoteStorage.caching.enable('/myfavoritedrinks/')
```

--------------------------------

### Update Docs Preview with TypeDoc Changes

Source: https://remotestorage.io/rs.js/docs/contributing/docs.html

If you are editing TypeDoc comments, run this additional command to have those changes reflected in your local preview.

```sh
typedoc --watch
```

--------------------------------

### Connect Remote Storage Manually

Source: https://remotestorage.io/rs.js/docs/getting-started/connect-widget.html

Connect to remote storage by calling the connect() method on the remoteStorage instance with the user's address. This is used when building your own connection UI.

```javascript
remoteStorage.connect('user@example.com');
```

--------------------------------

### storeFile()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Stores raw data at a given path with a specified content type.

```APIDOC
## storeFile(contentType, path, body)

### Description
Store raw data at a given path.

### Parameters
#### contentType
- `string` - Content type (MIME media type) of the data being stored
#### path
- `string` - Path relative to the module root
#### body
- `string` | `ArrayBuffer` | `ArrayBufferView<ArrayBufferLike>` - Raw data to store. For binary data, use an `ArrayBuffer` or `ArrayBufferView` (e.g. `Uint8Array`), not a binary string.

### Returns
- `Promise<string>` - A promise for the created/updated revision (ETag)

### Example
UTF-8 data:
```javascript
client.storeFile('text/html', 'index.html', '<h1>Hello World!</h1>')
      .then(() => { console.log("File saved") });
```

Binary data:
```javascript
const input = document.querySelector('form#upload input[type=file]');
const file = input.files[0];
const fileReader = new FileReader();

fileReader.onload = function () {
  client.storeFile(file.type, file.name, fileReader.result)
        .then(() => { console.log("File saved") });
};

fileReader.readAsArrayBuffer(file);
```
```

--------------------------------

### Listen for RemoteStorage Connection Events

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Attach an event handler to be called when the storage account connects. This is useful for triggering actions immediately after a successful connection.

```typescript
remoteStorage.on('connected', function() {
  console.log('storage account has been connected');
});
```

--------------------------------

### Store Binary Data with BaseClient

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Stores binary data, such as images or files, at a given path. Ensure the data is provided as an ArrayBuffer or ArrayBufferView.

```javascript
const input = document.querySelector('form#upload input[type=file]');
const file = input.files[0];
const fileReader = new FileReader();

fileReader.onload = function () {
  client.storeFile(file.type, file.name, fileReader.result)
        .then(() => { console.log("File saved") });
};

fileReader.readAsArrayBuffer(file);
```

--------------------------------

### Register RemoteStorage Event Handlers

Source: https://remotestorage.io/rs.js/docs/getting-started/events.html

Use the `.on()` method to register callback functions for events like 'connected', 'network-offline', and 'network-online'. The 'connected' event provides access to the user's address.

```javascript
remoteStorage.on('connected', () => {
  const userAddress = remoteStorage.remote.userAddress;
  console.debug(`${userAddress} connected their remote storage.`);
})

remoteStorage.on('network-offline', () => {
  console.debug(`We're offline now.`);
})

remoteStorage.on('network-online', () => {
  console.debug(`Hooray, we're back online.`);
})
```

--------------------------------

### Enable Caching for a Path

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Enables caching for a specified path using the `ALL` strategy, which proactively retrieves nodes to cache.

```javascript
remoteStorage.caching.enable('/bookmarks/');
```

--------------------------------

### Connect with a Token

Source: https://remotestorage.io/rs.js/docs/nodejs.html

Use this method to connect to remoteStorage when you have already acquired an OAuth token. This bypasses the standard OAuth flow.

```javascript
remoteStorage.connect('user@example.com', 'abcdef123456')
```

--------------------------------

### RemoteStorage.enableLog

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Enables remoteStorage debug logging. Typically configured during instantiation.

```APIDOC
## Method: enableLog

### Description
Enable remoteStorage debug logging. Usually done when instantiating remoteStorage.

### Signature
`enableLog(): void`

### Returns
`void`

### Example
```javascript
const remoteStorage = new RemoteStorage({ logging: true });
```
```

--------------------------------

### RemoteStorage.connect

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Connects to a remoteStorage server by discovering the WebFinger profile and initiating the OAuth dance. Can also use a pre-supplied token.

```APIDOC
## Method: connect

### Description
Connect to a remoteStorage server. Discovers the WebFinger profile of the given user address and initiates the OAuth dance. This method must be called _after_ all required access has been claimed. Special cases include using a bearer token directly or when authorization is established out-of-band.

### Signature
`connect(userAddress: string, token?: string): void`

### Parameters
*   **userAddress** (`string`) - The user address (user@host) or URL to connect to.
*   **token?** (`string`, optional) - A bearer token acquired beforehand.

### Returns
`void`

### Example
```typescript
remoteStorage.connect('user@example.com');
```
```

--------------------------------

### Define a RemoteStorage data module

Source: https://remotestorage.io/rs.js/docs/data-modules/defining-a-module.html

A module consists of a name and a builder function. The builder receives private and public client instances and returns an object with exported methods.

```javascript
const Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
  return {
    exports: {
      addBookmark: function() {}
    }
  }
}};
```

--------------------------------

### Access module exports

Source: https://remotestorage.io/rs.js/docs/data-modules/defining-a-module.html

Once loaded, module functions and properties are accessible on the RemoteStorage instance via the module's name.

```javascript
remoteStorage.bookmarks.addBookmark()
```

--------------------------------

### checkPath()

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Retrieves the caching strategy for a given path or its nearest ancestor with a configured strategy.

```APIDOC
## checkPath()

### Description
Retrieve caching setting for a given path, or its next parent with a caching strategy set.

### Parameters
#### path
`string` - Path to retrieve setting for

### Returns
`string` - caching strategy for the path

### Example
```js
remoteStorage.caching.checkPath('documents/').then(strategy => {
  console.log(`caching strategy for 'documents/': ${strategy}`);
  // "caching strategy for 'documents/': SEEN"
});
```
```

--------------------------------

### on()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Registers an event handler for a specified event name. This is an alias for addEventListener.

```APIDOC
## on(eventName, handler)

### Description
Register an event handler for the given event name. Alias for addEventListener.

### Parameters
#### eventName
- `string` - Name of the event
#### handler
- `EventHandler` - Function to handle the event

### Returns
- `void`

### Example
```typescript
remoteStorage.on('connected', function() {
  console.log('storage account has been connected');
});
```
```

--------------------------------

### Claim Root Access

Source: https://remotestorage.io/rs.js/docs/api/access/classes/Access.html

Claim complete read/write access to all files and folders in your remote storage by using an asterisk for the scope.

```javascript
remoteStorage.access.claim('*', 'rw');
```

--------------------------------

### Add RemoteStorage Module

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Add a remoteStorage data module. This can be done after instantiation or during instantiation.

```javascript
import Bookmarks from 'remotestorage-module-bookmarks';

remoteStorage.addModule(Bookmarks);
```

```javascript
const remoteStorage = new RemoteStorage({ modules: [ Bookmarks ] });
```

```javascript
remoteStorage.bookmarks.archive.getAll(false)
  .then(bookmarks => console.log(bookmarks));
```

--------------------------------

### Enable RemoteStorage Debug Logging

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Enable remoteStorage debug logging. This is typically done during instantiation for development purposes.

```javascript
const remoteStorage = new RemoteStorage({ logging: true });
```

--------------------------------

### cache()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Sets the caching strategy for a given path and its children. Allows for method chaining.

```APIDOC
### cache()

> **cache**(`path`, `strategy?`): `BaseClient`

Defined in: baseclient.ts:679
Set caching strategy for a given path and its children.
See Caching strategies for a detailed description of the available strategies.

#### Parameters

##### path
`string`
Path to cache

##### strategy?
`"ALL"` | `"SEEN"` | `"FLUSH"`
Caching strategy. One of 'ALL', 'SEEN', or FLUSH'. Defaults to 'ALL'.

#### Returns

`BaseClient`
The same `BaseClient` instance this method is called on to allow for method chaining

#### Example

ts```
client.cache('lists/', 'SEEN');
```
```

--------------------------------

### Import RemoteStorage with ES6 module

Source: https://remotestorage.io/rs.js/docs/getting-started/how-to-add.html

Import the RemoteStorage class when using ES6 modules.

```javascript
import RemoteStorage from 'remotestoragejs';
```

--------------------------------

### storeObject()

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

Stores a JavaScript object at a given path, triggering synchronization. The object must be JSON serializable.

```APIDOC
## storeObject(typeAlias, path, object)

### Description
Store an object at given path. Triggers synchronization. See declareType and Defining data types for info on object types.
Must not be called more than once per second for any given `path`.

### Parameters
#### typeAlias
- `string` - Unique type of this object within this module.
#### path
- `string` - Path relative to the module root.
#### object
- `object` - A JavaScript object to be stored at the given path. Must be serializable as JSON.

### Returns
- `Promise<string>` - Resolves with revision on success. Rejects with an error object, if schema validations fail.

### Example
```typescript
const bookmark = {
  url: 'http://unhosted.org',
  description: 'Unhosted Adventures',
  tags: ['unhosted', 'remotestorage', 'no-backend']
}
const path = MD5Hash(bookmark.url);

client.storeObject('bookmark', path, bookmark)
      .then(() => console.log('bookmark saved'))
      .catch((err) => console.log(err));
```
```

--------------------------------

### Check Caching Strategy for a Path

Source: https://remotestorage.io/rs.js/docs/api/caching/classes/Caching.html

Retrieve the caching strategy for a given path. If no strategy is explicitly set for the path, it will check its parent directories up to the root.

```javascript
remoteStorage.caching.checkPath('documents/').then(strategy => {
  console.log(`caching strategy for 'documents/': ${strategy}`);
  // "caching strategy for 'documents/': SEEN"
});
```

--------------------------------

### Log Git Commits for Changelog

Source: https://remotestorage.io/rs.js/docs/contributing/release-checklist.html

Use this command to log all commits made since the last release tag, excluding merge commits. This output can be used to generate the changelog.

```shell
$ git log --no-merges <LAST RELEASE TAG>..HEAD
```

--------------------------------

### RemoteStorage.on

Source: https://remotestorage.io/rs.js/docs/api/remotestorage/classes/RemoteStorage.html

Registers an event handler for a given event name. This is an alias for `addEventListener`.

```APIDOC
## Method: on

### Description
Register an event handler for the given event name. Alias for addEventListener.

### Signature
`on(eventName: string, handler: EventHandler): void`

### Parameters
*   **eventName** (`string`) - Name of the event.
*   **handler** (`EventHandler`) - Function to handle the event.

### Returns
`void`
```

--------------------------------

### BaseClient Properties

Source: https://remotestorage.io/rs.js/docs/api/baseclient/classes/BaseClient.html

The BaseClient class has a 'base' property that indicates the base path it operates on.

```APIDOC
## Properties

### base

> **base** : `string`

Defined in: baseclient.ts:234
Base path, which this BaseClient operates on.
For the module's `privateClient` this would be the module name, and for the corresponding `publicClient` it is `/public/<moduleName>/`.
```