@legit-sdk/core 0.4.5 → 0.6.0

package/dist/index.d.ts

@@ -557,6 +557,7 @@ declare class CompositeFs {
     } | BufferEncoding | null): Promise<void>;
 }
 
+declare function mergeLegitRouteFolders(a: LegitRouteFolder, b: LegitRouteFolder): LegitRouteFolder;
 declare function openLegitFsWithMemoryFs(props?: Parameters<typeof openLegitFs>[0]): Promise<CompositeFs & {
     auth: LegitAuth;
     sync: {
@@ -572,11 +573,32 @@ declare function openLegitFsWithMemoryFs(props?: Parameters<typeof openLegitFs>[
     shareCurrentBranch: () => Promise<string>;
     setCurrentBranch: (branch: string) => Promise<void>;
     getCurrentBranch: () => Promise<string>;
+    /**
+     *
+     * This function takes a legit archive - earlier compressed with saveArchive and writes it to storage fs.
+     *
+     * Refs that can be fast forwarded should get updeted - referecences that cannot be fast forwarded create a ref named branchname-conflict-uuid.
+     * New Refs should be added. (TODO how do we handle deleted refs to prevent them from coming back?)
+     *
+     * The git config should get ignored for now
+     *
+     * @param legitArchieve a zlib compressed legit repo
+     */
+    loadArchive: ({ legitArchive: legitArchive, clearExisting, }: {
+        legitArchive: Uint8Array;
+        clearExisting?: boolean;
+    }) => Promise<void>;
+    /**
+     * creates a legit archieve - a compressed representation of the legit repo (the .git folder in the storage fs)
+     *
+     * @returns
+     */
+    saveArchive: () => Promise<Uint8Array>;
 }>;
 /**
  * Creates and configures a LegitFs instance with CompositeFs, GitSubFs, HiddenFileSubFs, and EphemeralSubFs.
  */
-declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFiles, initialAuthor, serverUrl, publicKey, ephemaralGitConfig, additionalFilterLayers, }: {
+declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFiles, initialAuthor, serverUrl, publicKey, ephemaralGitConfig, additionalFilterLayers, routeOverrides, }: {
     storageFs: typeof nodeFs;
     gitRoot: string;
     anonymousBranch?: string;
@@ -586,6 +608,7 @@ declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFile
     publicKey?: string;
     ephemaralGitConfig?: boolean;
     additionalFilterLayers?: CompositeSubFs[];
+    routeOverrides?: LegitRouteFolder;
 }): Promise<CompositeFs & {
     auth: LegitAuth;
     sync: {
@@ -601,6 +624,27 @@ declare function openLegitFs({ storageFs, gitRoot, anonymousBranch, showKeepFile
     shareCurrentBranch: () => Promise<string>;
     setCurrentBranch: (branch: string) => Promise<void>;
     getCurrentBranch: () => Promise<string>;
+    /**
+     *
+     * This function takes a legit archive - earlier compressed with saveArchive and writes it to storage fs.
+     *
+     * Refs that can be fast forwarded should get updeted - referecences that cannot be fast forwarded create a ref named branchname-conflict-uuid.
+     * New Refs should be added. (TODO how do we handle deleted refs to prevent them from coming back?)
+     *
+     * The git config should get ignored for now
+     *
+     * @param legitArchieve a zlib compressed legit repo
+     */
+    loadArchive: ({ legitArchive: legitArchive, clearExisting, }: {
+        legitArchive: Uint8Array;
+        clearExisting?: boolean;
+    }) => Promise<void>;
+    /**
+     * creates a legit archieve - a compressed representation of the legit repo (the .git folder in the storage fs)
+     *
+     * @returns
+     */
+    saveArchive: () => Promise<Uint8Array>;
 }>;
 
 type FileAccess = {
@@ -791,66 +835,6 @@ declare class CopyOnWriteSubFs extends BaseCompositeSubFs {
     writeFile(filePath: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
 }
 
-/**
- * FS utilized to provide pass-through access to the underlying filesystem
- */
-declare class PassThroughSubFs extends BaseCompositeSubFs {
-    private openFh;
-    private memFs;
-    private targetFs;
-    constructor({ name, parentFs, rootPath, }: {
-        name: string;
-        parentFs: CompositeFs;
-        rootPath: string;
-    });
-    responsible(filePath: string): Promise<boolean>;
-    fileType(): number;
-    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
-    access(filePath: PathLike$1, mode?: number): Promise<void>;
-    stat(path: PathLike$1, opts?: {
-        bigint?: false;
-    }): Promise<nodeFs.Stats>;
-    stat(path: PathLike$1, opts: {
-        bigint: true;
-    }): Promise<nodeFs.BigIntStats>;
-    stat(path: PathLike$1, opts?: {
-        bigint?: boolean;
-    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
-    lstat(path: PathLike$1, opts?: {
-        bigint?: false;
-    }): Promise<nodeFs.Stats>;
-    lstat(path: PathLike$1, opts: {
-        bigint: true;
-    }): Promise<nodeFs.BigIntStats>;
-    lstat(path: PathLike$1, opts?: {
-        bigint?: boolean;
-    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
-    opendir(folderPath: nodeFs.PathLike, options?: nodeFs.OpenDirOptions): Promise<CompositeFsDir>;
-    link(existingPath: PathLike$1, newPath: PathLike$1): Promise<void>;
-    mkdir(dirPath: PathLike$1, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
-    readdir(path: PathLike$1, ...args: any[]): Promise<any>;
-    readlink(path: PathLike$1, ...args: any[]): Promise<any>;
-    unlink(path: PathLike$1): Promise<void>;
-    rename(oldPath: PathLike$1, newPath: PathLike$1): Promise<void>;
-    rmdir(path: PathLike$1, options?: nodeFs.RmDirOptions): Promise<void>;
-    symlink(target: PathLike$1, path: PathLike$1, type?: string | null): Promise<void>;
-    lookup(filePath: string): Promise<number>;
-    close(fh: CompositFsFileHandle): Promise<void>;
-    dataSync(fh: CompositFsFileHandle): Promise<void>;
-    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
-    fchmod(fh: CompositFsFileHandle, mode: TMode): Promise<void>;
-    fchown(fh: CompositFsFileHandle, uid: number, gid: number): Promise<void>;
-    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
-    ftruncate(fh: CompositFsFileHandle, len?: number): Promise<void>;
-    resolvePath(fd: number): string;
-    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
-    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
-    writev(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleWritevResult>;
-    readv(fh: CompositFsFileHandle, buffers: ArrayBufferView[], position?: number | null): Promise<TFileHandleReadvResult>;
-    readFile(path: PathLike$1 | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
-    writeFile(path: string, data: TData, options: IWriteFileOptions | string): Promise<void>;
-}
-
 type VirtualFile = {
     type: 'file';
     content?: string | Buffer;
@@ -866,9 +850,7 @@ type VirtualFile = {
 interface VirtualFileArgs {
     cacheFs: IFs;
     filePath: string;
-    gitRoot: string;
     userSpaceFs: CompositeFs;
-    nodeFs?: any;
     pathParams: any;
     author: {
         name: string;
@@ -1021,6 +1003,33 @@ declare class CompositeSubFsAdapter extends BaseCompositeSubFs implements Compos
     fileType(): number;
 }
 
+/**
+ * Creates a CompositeSubFsAdapter for legit virtual folder operations
+ *
+ * This adapter handles the .legit folder, which serves as the root
+ * for all legit-related virtual files and operations.
+ *
+ * @example
+ * ```ts
+ * const adapter = createLegitVirtualFileAdapter({
+ *   gitStorageFs: memFs,
+ *   gitRoot: '/my-repo',
+ * });
+ *
+ * // Use in CompositeFs routes
+ * const compositeFs = new CompositeFs({
+ *   routes: {
+ *     '.legit': adapter,
+ *   },
+ * });
+ * ```
+ */
+declare function createLegitVirtualFileAdapter({ gitStorageFs, gitRoot, rootPath, }: {
+    gitStorageFs: any;
+    gitRoot: string;
+    rootPath?: string;
+}): CompositeSubFsAdapter;
+
 type Operation = {
     oid: string;
     parentOids: string[];
@@ -1074,5 +1083,248 @@ type HistoryItem = {
     author: User;
 };
 
-export { CompositeFs, CompositeSubFsAdapter, CopyOnWriteSubFs, EphemeralSubFs, HiddenFileSubFs, PassThroughSubFs, createBranchOperationsAdapter, createFsOperationFileLogger, createLegitSyncService, getLegitFsAccess, openLegitFs, openLegitFsWithMemoryFs };
-export type { FsOperationLogger, HistoryItem, Operation, User };
+declare abstract class ASimpleCompositeSubfs extends BaseCompositeSubFs implements CompositeSubFs {
+    private memFs;
+    private openFh;
+    constructor({ name, rootPath }: {
+        name: string;
+        rootPath: string;
+    });
+    /**
+     * Check if write operations are supported by this adapter
+     * Subclasses can override this to return false for read-only adapters
+     */
+    isWriteSupported(): boolean;
+    responsible(_filePath: string): Promise<boolean>;
+    /**
+     * Get route parameters from the operation context
+     * CompositeFs sets this context when routing to this adapter
+     */
+    private getRouteParams;
+    /**
+     * Get static siblings from the operation context
+     * These are static entries that should appear in directory listings
+     */
+    private getStaticSiblings;
+    /**
+     * Opens a virtual file using the configured handler.
+     *
+     * The handler receives route parameters via context set by CompositeFs.
+     */
+    open(filePath: string, flags: string, mode?: number): Promise<CompositFsFileHandle>;
+    abstract createDirectory(args: {
+        path: string;
+        recursive?: boolean;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    abstract readFileContent(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<{
+        content: string | Buffer;
+        oid?: string;
+    } | undefined>;
+    abstract writeFileContent(args: {
+        path: string;
+        content: Buffer | string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    abstract readDirectory(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<nodeFs.Dirent[]>;
+    abstract renamePath(args: {
+        oldPath: string;
+        newPath: string;
+        oldContext: ASimpleCompositeSubfs['context'];
+        newContext: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    abstract deleteFile(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    abstract removeDirectory(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    mkdir(path: PathLike, options?: nodeFs.MakeDirectoryOptions | nodeFs.Mode | null): Promise<void>;
+    access(path: PathLike, _mode?: number): Promise<void>;
+    futimes(fh: CompositFsFileHandle, atime: TTime, mtime: TTime): Promise<void>;
+    fstat(fh: CompositFsFileHandle, options?: IStatOptions): Promise<IStats>;
+    ftruncate(fh: CompositFsFileHandle, len?: number): Promise<void>;
+    stat(path: PathLike, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    stat(path: PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    stat(path: PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    abstract getStats(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<nodeFs.Stats>;
+    lstat(path: PathLike, opts?: {
+        bigint?: false;
+    }): Promise<nodeFs.Stats>;
+    lstat(path: PathLike, opts: {
+        bigint: true;
+    }): Promise<nodeFs.BigIntStats>;
+    lstat(path: PathLike, opts?: {
+        bigint?: boolean;
+    }): Promise<nodeFs.Stats | nodeFs.BigIntStats>;
+    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | BufferEncoding | null): Promise<string[]>;
+    readdir(path: PathLike, options?: {
+        encoding: 'buffer';
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    } | 'buffer' | null): Promise<Buffer[]>;
+    readdir(path: PathLike, options?: (nodeFs.ObjectEncodingOptions & {
+        withFileTypes?: false | undefined;
+        recursive?: boolean | undefined;
+    }) | BufferEncoding | null): Promise<string[] | Buffer[]>;
+    readdir(path: PathLike, options: nodeFs.ObjectEncodingOptions & {
+        withFileTypes: true;
+        recursive?: boolean | undefined;
+    }): Promise<nodeFs.Dirent[]>;
+    read(fh: CompositFsFileHandle, buffer: Buffer | Uint8Array, offset: number, length: number, position: number): Promise<TFileHandleReadResult>;
+    /**
+     *
+     * Writes (parts) of a buffer to a specific position in the file
+     *
+     * - a write leads to a new commit and on flush since the point in time a flush may occur may vary a read operation may
+     *  not see changed done on the read lays.
+     *
+     *
+     * @param fh
+     * @param buffer
+     * @param offset
+     * @param length
+     * @param position
+     * @returns
+     */
+    write(fh: CompositFsFileHandle, buffer: Buffer | ArrayBufferView | DataView, offset?: number, length?: number, position?: number): Promise<TFileHandleWriteResult>;
+    close(fh: CompositFsFileHandle): Promise<void>;
+    dataSync(fh: CompositFsFileHandle): Promise<void>;
+    readFile(path: PathLike | IFileHandle, options?: IReadFileOptions | string): Promise<TDataOut>;
+    writeFile(path: string, data: TData, options?: IWriteFileOptions | string): Promise<void>;
+    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
+    fchmod(_fh: CompositFsFileHandle, _mode: TMode): Promise<void>;
+    unlink(path: PathLike): Promise<void>;
+    rmdir(path: PathLike, ..._args: any[]): Promise<void>;
+    fileType(): number;
+}
+
+interface MemoryFile {
+    type: 'file';
+    content: Buffer;
+    mode: number;
+    createdAt: Date;
+    modifiedAt: Date;
+}
+interface MemoryDirectory {
+    type: 'directory';
+    entries: Set<string>;
+    mode: number;
+    createdAt: Date;
+    modifiedAt: Date;
+}
+type MemoryNode = MemoryFile | MemoryDirectory;
+type FileSystemData = string | {
+    [key: string]: FileSystemData;
+};
+/**
+ * SimpleMemorySubFs - A simple in-memory filesystem implementation
+ *
+ * This class extends ASimpleCompositeSubfs and stores all files and directories
+ * in a JavaScript Map in memory. It's useful for testing, caching, or temporary
+ * file storage that doesn't need to persist.
+ */
+declare class SimpleMemorySubFs extends ASimpleCompositeSubfs {
+    private storage;
+    private nextFileType;
+    /**
+     * Debug method to inspect internal storage
+     */
+    _debugGetStorage(): Map<string, MemoryNode>;
+    constructor({ name, rootPath, initialData, }: {
+        name: string;
+        rootPath: string;
+        initialData?: FileSystemData;
+    });
+    /**
+     * Populate the filesystem from initial data structure
+     * @param data - The data structure to populate from (string = file, object = folder)
+     * @param currentPath - The current path in the filesystem
+     */
+    private populateFromInitialData;
+    fileType(): number;
+    createDirectory(args: {
+        path: string;
+        recursive?: boolean;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    getStats(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<nodeFs.Stats>;
+    readFileContent(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<{
+        content: string | Buffer;
+        oid?: string;
+    } | undefined>;
+    writeFileContent(args: {
+        path: string;
+        content: Buffer | string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    readDirectory(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<nodeFs.Dirent[]>;
+    renamePath(args: {
+        oldPath: string;
+        newPath: string;
+        oldContext: ASimpleCompositeSubfs['context'];
+        newContext: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    deleteFile(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    removeDirectory(args: {
+        path: string;
+        context: ASimpleCompositeSubfs['context'];
+    }): Promise<void>;
+    /**
+     * Normalize a path to ensure consistent format
+     */
+    private normalizePath;
+    /**
+     * Get the parent directory path
+     */
+    private getParentPath;
+    /**
+     * Get the base name of a path
+     */
+    private getBaseName;
+    /**
+     * Join path segments
+     */
+    private joinPath;
+}
+
+declare function toDirEntry(args: {
+    parent: string;
+    name: string;
+    isDir: boolean;
+}): nodeFs.Dirent;
+
+export { ASimpleCompositeSubfs, CompositeFs, CompositeSubFsAdapter, CopyOnWriteSubFs, EphemeralSubFs, HiddenFileSubFs, SimpleMemorySubFs, createBranchOperationsAdapter, createFsOperationFileLogger, createLegitSyncService, createLegitVirtualFileAdapter, getLegitFsAccess, mergeLegitRouteFolders, openLegitFs, openLegitFsWithMemoryFs, toDirEntry };
+export type { FileSystemData, FsOperationLogger, HistoryItem, Operation, User };