https://github.com/matrix-org/matrix-files-sdk
JS/TS SDK for working with files and folders in Matrix
https://github.com/matrix-org/matrix-files-sdk
Last synced: 4 months ago
JSON representation
JS/TS SDK for working with files and folders in Matrix
- Host: GitHub
- URL: https://github.com/matrix-org/matrix-files-sdk
- Owner: matrix-org
- License: apache-2.0
- Created: 2022-01-14T17:49:12.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-01-09T17:43:15.000Z (over 2 years ago)
- Last Synced: 2025-04-10T16:07:04.118Z (about 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 692 KB
- Stars: 12
- Watchers: 5
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Matrix Files SDK
Provides a file system like abstraction around MSC3089 tree & branch spaces over [Matrix](https://matrix.org).
Targets LTS versions of Node.js (currently >=12) and browsers.
## Installation
```sh
npm install matrix-files-sdk
```
or for `yarn`:
```sh
yarn add matrix-files-sdk
```
You must install `matrix-js-sdk` in your project as well.
## Usage
For a more complete example of the SDK in use see [vector-im/files-sdk-demo](https://github.com/vector-im/files-sdk-demo).
### Initialisation
The SDK acts as a wrapper around `matrix-js-sdk` so you need to create an instance of `MatrixClient` first.
The main entry point is via the `MatrixFiles` class:
```ts
import { createClient } from 'matrix-js-sdk';
import { MatrixFiles } from 'matrix-files-sdk';
const client = createClient({});
const files = new MatrixFiles(client);
// do initial sync of required state:
await files.sync();
```
### Navigating the hierarchy
You can use the `IFolder.getChildren()` function to discovery entries in the hierarchy:
```ts
import { IEntry } from 'matrix-files-sdk';
...
const entries: IEntry[] = await folder.getChildren();
for (const e: entries) {
console.log(`${e.name} => ${e.isFolder ? 'folder' : 'file' }`);
}
```
Entries are identified by an ID (`IEntry.id` of type `MatrixFilesID`) which are standard Matrix room and event IDs.
The ID can be used on an `IFolder` with `getChildById()` and `getDescendantById()`.
Furthermore the `MatrixFiles.resolvePath()` function can be used to resolve an entry by name from the root of the hierarchy:
```ts
const entry = await files.resolvePath(['My workspace', 'documents', 'file.pdf']);
```
### Common operations on entries
Deleting (redacting) a file:
```ts
await anEntry.delete();
```
Renaming on a folder:
```ts
await aFolder.rename('new name');
```
and a file:
```ts
await aFile.rename('new name.pdf');
```
Moving within the hierarchy:
```ts
const file = await files.resolvePath(['old folder', 'file.pdf']);
const newFolderId = await files.addFolder('new folder');
const newFolder = await files.getDescendantById(newFolderId);
await file.moveTo(newFolder, 'file.pdf');
```
### Observing changes
Files, folders and `MatrixFiles` all implement the `EventEmitter` pattern:
```ts
const file = await files.resolvePath(['old folder', 'file.pdf']);
file.on('modified', () => { console.log('file modified'); });
```
### Logging
Logging is available via [log4js](https://www.npmjs.com/package/log4js) under the `MatrixFilesSDK` log category.
For example, to enable trace level logging from the SDK:
```ts
import log4js from 'log4js';
log4js.configure({
appenders: {
console: {
type: 'console',
layout: { type: 'coloured' },
},
},
categories: {
default: {
appenders: ['console'],
level: 'debug',
},
MatrixFilesSDK: {
appenders: ['console'],
level: 'trace',
},
},
});
```