JS/TS SDK for working with files and folders in Matrix
  • TypeScript 99.2%
  • JavaScript 0.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
semantic-release-bot 3aecfbebc5 chore(release): 3.1.0
# [3.1.0](https://github.com/matrix-org/matrix-files-sdk/compare/v3.0.2...v3.1.0) (2023-11-29)

### Features

* update matrix-js-sdk from v24 to v30 ([4f55110](4f55110026))
2023-11-29 15:06:28 +00:00
.github build: cache node_modules 2022-12-08 17:09:04 +00:00
.vscode feat: first iteration of file system like abstraction over MatrixClient 2022-01-14 18:04:29 +00:00
docs docs: remove property types from class diagram 2022-02-07 12:09:30 +00:00
src feat: upgrade to matrix-js-sdk v22 2022-12-08 17:19:36 +00:00
.eslintrc.js build: enable eslint rules for promise safety 2022-02-05 15:19:24 +00:00
.gitignore chore: ignore .DS_Store 2022-02-18 14:32:24 +00:00
.npmrc feat: first iteration of file system like abstraction over MatrixClient 2022-01-14 18:04:29 +00:00
.nvmrc build: upgrade to Node.js 18 2022-12-08 17:09:33 +00:00
CHANGELOG.md chore(release): 3.1.0 2023-11-29 15:06:28 +00:00
commitlint.config.js feat: first iteration of file system like abstraction over MatrixClient 2022-01-14 18:04:29 +00:00
CONTRIBUTING.md docs: fix incorrect reference to package name 2022-01-16 14:31:28 +00:00
LICENSE feat: first iteration of file system like abstraction over MatrixClient 2022-01-14 18:04:29 +00:00
package.json chore(release): 3.1.0 2023-11-29 15:06:28 +00:00
README.md feat: add logging support via log4js 2022-02-18 15:33:50 +00:00
release.config.js feat: first iteration of file system like abstraction over MatrixClient 2022-01-14 18:04:29 +00:00
SECURITY.md Initial commit 2022-01-14 17:49:14 +00:00
tsconfig.json build: enable TS strict mode 2022-02-05 15:24:40 +00:00
yarn.lock feat: update matrix-js-sdk from v24 to v30 2023-11-29 15:04:55 +00:00

Matrix Files SDK

Provides a file system like abstraction around MSC3089 tree & branch spaces over Matrix.

Targets LTS versions of Node.js (currently >=12) and browsers.

Installation

npm install matrix-files-sdk

or for yarn:

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.

Class Diagram

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:

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:

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:

const entry = await files.resolvePath(['My workspace', 'documents', 'file.pdf']);

Common operations on entries

Deleting (redacting) a file:

await anEntry.delete();

Renaming on a folder:

await aFolder.rename('new name');

and a file:

await aFile.rename('new name.pdf');

Moving within the hierarchy:

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:

const file = await files.resolvePath(['old folder', 'file.pdf']);

file.on('modified', () => { console.log('file modified'); });

Logging

Logging is available via log4js under the MatrixFilesSDK log category.

For example, to enable trace level logging from the SDK:

import log4js from 'log4js';

log4js.configure({
  appenders: {
    console: {
      type: 'console',
      layout: { type: 'coloured' },
    },
  },
  categories: {
    default: {
      appenders: ['console'],
      level: 'debug',
    },
    MatrixFilesSDK: {
      appenders: ['console'],
      level: 'trace',
    },
  },
});