DoubleSyncFolder.js

import { DoubleSyncFile, DoubleSyncMemoryFile } from './DoubleSyncFile.js';
import { byName } from './internal.js';

const FOLDER_BRAND = Symbol.for('doublesync.DoubleSyncFolder');

/**
 * Abstract read+write folder. Concrete subclasses implement the storage backing.
 *
 * `list()` returns direct children only (one level). `walk()` is a default
 * generator that recurses depth-first in alphabetical order — so identical trees
 * always produce identical snapshot layouts regardless of underlying enumeration
 * order.
 */
export class DoubleSyncFolder {
    constructor() {
        this[FOLDER_BRAND] = true;
    }

    static [Symbol.hasInstance](obj) {
        return !!obj && obj[FOLDER_BRAND] === true;
    }
    /**
     * Leaf name (no path separators). Subclasses must populate this.
     * @returns {string}
     */
    get name() { throw new Error('DoubleSyncFolder.name: not implemented'); }

    /**
     * Direct children, mixed files and subfolders.
     * @returns {Promise<Array<DoubleSyncFile | DoubleSyncFolder>>}
     */
    async list() { throw new Error('DoubleSyncFolder.list: not implemented'); }

    /**
     * Depth-first leaf iterator. Each yielded value is `{ path, file }` where `path`
     * is the array of name segments from this folder to the file (exclusive of this
     * folder itself). Children at every level are visited in alphabetical order by
     * name to make the iteration reproducible.
     *
     * @yields {{ path: string[], file: DoubleSyncFile }}
     */
    async *walk(prefix = []) {
        const children = [...await this.list()].sort(byName);
        for (const entry of children) {
            const here = [...prefix, entry.name];
            if (entry instanceof DoubleSyncFile) yield { path: here, file: entry };
            else if (entry instanceof DoubleSyncFolder) yield* entry.walk(here);
            // unknown types are silently skipped — keeps `walk` total
        }
    }

    /**
     * Navigate `parts` segment-by-segment from this folder.
     * Returns the leaf entry (file or folder), or `null` if any segment is missing.
     *
     * @param {string[]} parts
     * @returns {Promise<DoubleSyncFile | DoubleSyncFolder | null>}
     */
    async findByPath(parts) {
        if (parts.length === 0) return this;
        const children = await this.list();
        const next = children.find(c => c.name === parts[0]);
        if (!next) return null;
        if (parts.length === 1) return next;
        if (next instanceof DoubleSyncFolder) return next.findByPath(parts.slice(1));
        return null;
    }

    /**
     * Add a new file (or replace an existing one with the same name) under this
     * folder. Optional — read-only backends throw.
     *
     * @param {string} name
     * @param {Uint8Array} bytes
     * @returns {Promise<DoubleSyncFile>} the newly created file
     */
    async addFile(_name, _bytes) { throw new Error(`${this.constructor.name}: not writable`); }

    /**
     * Add a subfolder. If one with this name already exists, return it (idempotent).
     * Optional — read-only backends throw.
     *
     * @param {string} name
     * @returns {Promise<DoubleSyncFolder>}
     */
    async addFolder(_name) { throw new Error(`${this.constructor.name}: not writable`); }

    /**
     * Remove a direct child by name. Returns true if something was removed.
     * Optional — read-only backends throw.
     *
     * @param {string} name
     * @returns {Promise<boolean>}
     */
    async removeChild(_name) { throw new Error(`${this.constructor.name}: not writable`); }

    /**
     * Ensure a nested folder path exists, creating missing segments as needed.
     * Returns the leaf folder.
     *
     * @param {string[]} parts
     * @returns {Promise<DoubleSyncFolder>}
     */
    async ensurePath(parts) {
        /** @type {DoubleSyncFolder} */
        let cur = this;
        for (const seg of parts) {
            cur = await cur.addFolder(seg);
        }
        return cur;
    }
}

/**
 * In-memory `DoubleSyncFolder`. Children are kept in a `Map` keyed by name so name
 * collisions overwrite rather than duplicate.
 *
 * @example
 * const root = new DoubleSyncMemoryFolder('project');
 * const src  = await root.addFolder('src');
 * await src.addFile('main.js', new TextEncoder().encode('console.log(1)'));
 * for await (const { path, file } of root.walk()) {
 *     console.log(path.join('/'), await file.getSize());
 * }
 */
export class DoubleSyncMemoryFolder extends DoubleSyncFolder {
    /**
     * @param {string} name
     */
    constructor(name) {
        super();
        if (typeof name !== 'string' || !name) throw new Error('DoubleSyncMemoryFolder: name must be a non-empty string');
        /** @type {string} */
        this._name = name;
        /** @type {Map<string, DoubleSyncFile | DoubleSyncFolder>} */
        this._children = new Map();
    }

    get name() { return this._name; }

    async list() {
        return [...this._children.values()];
    }

    async addFile(name, bytes) {
        const file = new DoubleSyncMemoryFile(name, bytes);
        this._children.set(name, file);
        return file;
    }

    async addFolder(name) {
        const existing = this._children.get(name);
        if (existing instanceof DoubleSyncMemoryFolder) return existing;
        if (existing) throw new Error(`DoubleSyncMemoryFolder.addFolder: '${name}' already exists as a file`);
        const folder = new DoubleSyncMemoryFolder(name);
        this._children.set(name, folder);
        return folder;
    }

    async removeChild(name) {
        return this._children.delete(name);
    }
}