zikaari/aspen-core

Aspen Core

The most performant solution for syncing dynamic nested objects/trees with their flattened representation. Aspen trees are powered by superfast TypedArrays that are ~5x faster than regular Arrays in all operations like lookups (indexOf) and alterations (splice), which means best of the best.

Aspen was built to serve react-aspen, a library for displaying nested trees in React apps (like file trees, indented todo lists etc.) while ensuring everything is super-efficient.

It is recommended that you read documentation for react-aspen to get a better idea on what this is all about.

Usage

You shouldn't have to use this library "as is" unless you're porting react-aspen to another rendering library and you need a very efficient backend

Install

npm i aspen-core

Light it up

import * as fse from 'fs-extra'
import * as Path from 'path'
import { IBasicFileSystemHost, Root, IFileEntryItem, WatchTerminator, FileType } from 'aspen-core'

const host: IBasicFileSystemHost = {
    pathStyle: 'unix', // or 'win32'
    getItems: async (path: string): Promise<IFileEntryItem[]> => Promise.all(
        (await fse.readdir(path))
            .map(async (filename) => {
                const stat = await fse.stat(Path.join(path, filename))
                return {
                    name: filename,
                    type: stat.isDirectory() ? FileType.Directory : FileType.File
                }
            })),

    /**
     * [optional] sort function
     */
    // sortComparator: (a: FileOrDir, b: FileOrDir): number => { by default Directories come before FileEntries }

    /**
     * [optional] use this to know when a Directory is interested in file watching
     * Note that this is used just to let you "know", `Root` can receive events through `Root#inotify` regardless of this method's presence
     */
    // watch: (path: string): WatchTerminator => { return a function that will be called when a Directory is no longer interested in watching changes }
}

const root: Root = new Root(host, '/absolute/path/that/will/act/as/root')

// refer to the full API on what is possible next

API

This library is written in TypeScript. Type definitions are included when you do npm i aspen-core. Documentaion is available here.

License

This project is licensed under MIT license. You are free to use, modify, distribute the code as you like (credits although not required, are highly appreciated)