keri-ts 0.10.0 → 0.10.2

package/esm/keri/npm/src/keri/src/db/core/path-manager.js

@@ -1,490 +0,0 @@
-/**
- * PathManager - File and directory path management
- *
- * Manages file directories and files for KERI installation resources like databases.
- * Uses composition pattern instead of inheritance.
- */
-import * as dntShim from "../../../../_dnt.shims.js";
-import { isAbsolute, join } from "../../../../deps/jsr.io/@std/path/1.1.5/mod.js";
-import { action } from "effection";
-import { InvalidPathNameError, PathError } from "../../core/errors.js";
-import { consoleLogger } from "../../core/logger.js";
-function hasErrorCode(error, codes) {
-    if (typeof error !== "object" || error === null || !("code" in error)) {
-        return false;
-    }
-    const code = error.code;
-    return typeof code === "string" && codes.includes(code);
-}
-function isNotFoundLike(error) {
-    return error instanceof dntShim.Deno.errors.NotFound
-        || hasErrorCode(error, ["ENOENT"]);
-}
-function isPermissionDeniedLike(error) {
-    return error instanceof dntShim.Deno.errors.PermissionDenied
-        || hasErrorCode(error, ["EACCES", "EPERM"]);
-}
-/** Defaults for the path manager */
-export const PATH_DEFAULTS = {
-    headDirPath: "/usr/local/var",
-    tailDirPath: "keri/db",
-    cleanTailDirPath: "keri/clean/db",
-    altHeadDirPath: "~",
-    altTailDirPath: ".tufa/db",
-    altCleanTailDirPath: ".tufa/clean/db",
-    tempHeadDir: "/tmp",
-    tempPrefix: "keri_lmdb_",
-    tempSuffix: "_test",
-    perm: 0o1700, // sticky + owner rwx
-    mode: "r+",
-    fext: "text",
-};
-/**
- * Filesystem path lifecycle manager for database/config resources.
- *
- * Responsibilities:
- * - derive persistent, clean, alternate-home, and temporary paths from one
- *   shared option/default contract
- * - create directories on demand and fall back from primary system paths to
- *   user-home alternates when the runtime lacks permission
- * - centralize path naming constraints so higher-level DB/config wrappers do
- *   not each reimplement filesystem policy
- *
- * Current `keri-ts` difference:
- * - this is a local abstraction, not a direct KERIpy class port; it encodes
- *   the same path-layout intent while handling Deno/Node runtime differences in
- *   one place
- */
-export class PathManager {
-    constructor(options = {}, defaults) {
-        // head directory path
-        Object.defineProperty(this, "headDirPath", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // base directory path
-        Object.defineProperty(this, "base", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // name of the path, dir or file name
-        Object.defineProperty(this, "_name", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // temporary directory flag
-        Object.defineProperty(this, "temp", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // path to the directory or file
-        Object.defineProperty(this, "path", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // numeric os dir permissions for database directory and database files
-        Object.defineProperty(this, "perm", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // true means path ends in file, false means path ends in directory
-        Object.defineProperty(this, "filed", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // true means ensure path ends with extension, false means do not ensure path ends with extension
-        Object.defineProperty(this, "extensioned", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // file open mode if filed
-        Object.defineProperty(this, "mode", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // file extension if filed
-        Object.defineProperty(this, "fext", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // true means directory created and if filed then file is opened
-        Object.defineProperty(this, "opened", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // defaults for the path manager
-        Object.defineProperty(this, "defaults", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        // logger instance for logging
-        Object.defineProperty(this, "logger", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.defaults = { ...PATH_DEFAULTS, ...defaults };
-        this._name = options.name || "main";
-        this.base = options.base || "";
-        this.temp = options.temp || false;
-        this.headDirPath = options.headDirPath || this.defaults.headDirPath;
-        this.perm = options.perm ?? this.defaults.perm;
-        this.path = null;
-        this.filed = options.filed || false;
-        this.extensioned = options.extensioned || false;
-        this.mode = options.mode || this.defaults.mode;
-        this.fext = options.fext || this.defaults.fext;
-        this.opened = false;
-        this.logger = options.logger ?? consoleLogger;
-        // Note: Constructor cannot be async/generator, so reopen must be called explicitly
-        // if options.reopen is true. This is handled by callers (e.g., LMDBer).
-    }
-    get name() {
-        return this._name;
-    }
-    set name(value) {
-        // Check if path is absolute
-        if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
-            throw new InvalidPathNameError(`Not relative name=${value} path.`, {
-                name: value,
-            });
-        }
-        this._name = value;
-    }
-    _getTempPath() {
-        const tempDir = dntShim.Deno.env.get("TMPDIR") || dntShim.Deno.env.get("TMP")
-            || dntShim.Deno.env.get("TEMP") || "/tmp";
-        const tempName = `${this.defaults.tempPrefix}${this.name}${this.defaults.tempSuffix}`;
-        return join(tempDir, tempName);
-    }
-    /** Resolve user home directory with a Windows-aware fallback chain. */
-    _resolveHomeDir() {
-        const home = dntShim.Deno.env.get("HOME");
-        if (home) {
-            return home;
-        }
-        // Windows common environment variables
-        const userProfile = dntShim.Deno.env.get("USERPROFILE");
-        if (userProfile) {
-            return userProfile;
-        }
-        const homeDrive = dntShim.Deno.env.get("HOMEDRIVE");
-        const homePath = dntShim.Deno.env.get("HOMEPATH");
-        if (homeDrive && homePath) {
-            return `${homeDrive}${homePath}`;
-        }
-        return "~";
-    }
-    _pathExpandTilde(path) {
-        if (path === "~" || /^~[\\/]/.test(path)) {
-            const home = this._resolveHomeDir();
-            return path === "~" ? home : path.replace("~", home);
-        }
-        return path;
-    }
-    _getPrimaryPath(headDirPath, clean) {
-        // head / tail / base / name
-        // Expand ~ to HOME directory
-        let head = headDirPath;
-        head = this._pathExpandTilde(head);
-        let tail;
-        if (clean) {
-            tail = this.defaults.cleanTailDirPath;
-        }
-        else {
-            tail = this.defaults.tailDirPath;
-        }
-        return this.base
-            ? join(head, tail, this.base, this.name)
-            : join(head, tail, this.name);
-    }
-    _getAltPath(clean) {
-        // HOME or ~ / tail / base / name
-        let head = dntShim.Deno.env.get("HOME") || "~";
-        head = this._pathExpandTilde(head);
-        let tail;
-        if (clean) {
-            tail = this.defaults.altCleanTailDirPath;
-        }
-        else {
-            tail = this.defaults.altTailDirPath;
-        }
-        return this.base
-            ? join(head, tail, this.base, this.name)
-            : join(head, tail, this.name);
-    }
-    /*
-     * Creates a file path based on head, tail, base, and name. Ensure path is created and optionally reuse it.
-     * @param options path creation options
-     * @returns File path to a persistent file or directory
-     */
-    _getPersistentPaths(options = {}) {
-        const headDirPath = options.headDirPath ?? this.headDirPath;
-        const clean = options.clean || false;
-        const primary = this._getPrimaryPath(headDirPath, clean);
-        const alt = this._getAltPath(clean);
-        return [primary, alt];
-    }
-    _getPaths(options = {}) {
-        const [primary, alt] = this._getPersistentPaths(options);
-        const tempPath = this._getTempPath();
-        return [primary, alt, tempPath];
-    }
-    /**
-     * Helper: Convert Promise-based file system operations to Effection operations
-     * This ensures proper structured concurrency and cancellation support
-     */
-    *statOp(path) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.stat(path)
-                .then(() => resolve(true))
-                .catch((error) => {
-                if (isNotFoundLike(error)) {
-                    resolve(false);
-                }
-                else {
-                    reject(error);
-                }
-            });
-            return () => { };
-        });
-    }
-    *accessOp(path) {
-        return yield* action((resolve, reject) => {
-            // In Deno, we check access by stating or trying to read/write.
-            // Simplified to checking existence and relying on OS permissions for now
-            dntShim.Deno.stat(path)
-                .then(() => resolve(true))
-                .catch(() => resolve(false));
-            return () => { };
-        });
-    }
-    *mkdirOp(path, perm) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.mkdir(path, { recursive: true, mode: perm })
-                .then(() => resolve(true))
-                .catch((error) => {
-                if (isPermissionDeniedLike(error)) {
-                    resolve(false);
-                }
-                else {
-                    reject(error);
-                }
-            });
-            return () => { };
-        });
-    }
-    *rmOp(path) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.remove(path, { recursive: true })
-                .then(() => resolve(undefined))
-                .catch((error) => {
-                if (isNotFoundLike(error)) {
-                    resolve(undefined);
-                }
-                else {
-                    reject(error);
-                }
-            });
-            return () => { };
-        });
-    }
-    *statFileOp(path) {
-        return yield* action((resolve, reject) => {
-            dntShim.Deno.stat(path)
-                .then((stats) => {
-                resolve({
-                    isDirectory: stats.isDirectory,
-                    isFile: stats.isFile,
-                });
-            })
-                .catch((error) => {
-                if (isNotFoundLike(error)) {
-                    resolve({
-                        isDirectory: false,
-                        isFile: false,
-                    });
-                }
-                else {
-                    reject(error);
-                }
-            });
-            return () => { };
-        });
-    }
-    /**
-     * Reopen/create the directory or file path.
-     * Replicates KERIpy/HIO Filer.remake logic:
-     * - Tries primary path (/usr/local/var/keri/*) first
-     * - Falls back to alt path (~/.tufa/*) on OS errors or access issues
-     *
-     * Returns Effection Operation with true if path is created and accessible, false otherwise.
-     */
-    *reopen(options = {}) {
-        this._applyOptions(options);
-        const headDirPath = options.headDirPath ?? this.headDirPath;
-        const clean = options.clean || false;
-        const reuse = options.reuse || false;
-        const clear = options.clear || false;
-        const [primary, alt, tempPath] = this._getPaths({
-            ...options,
-            headDirPath,
-            clean,
-        });
-        const resolved = yield* this._resolvePath({
-            primary,
-            alt,
-            tempPath,
-            headDirPath,
-            reuse,
-        });
-        this.headDirPath = resolved.headDirPath;
-        if (clear) {
-            yield* this._clearPath(resolved.path);
-        }
-        if (!this.filed) {
-            yield* this._ensureDirectoryExists(resolved.path);
-        }
-        this.path = resolved.path;
-        this.opened = true;
-        return this.opened;
-    }
-    /** Update instance fields from caller-provided options. */
-    _applyOptions(options) {
-        this.temp = options.temp ?? this.temp;
-        this.perm = options.perm ?? this.perm;
-        this.mode = options.mode ?? this.mode;
-        this.fext = options.fext ?? this.fext;
-    }
-    /**
-     * Select which concrete path to use: temp, primary with alt fallback,
-     * reuse with alt fallback, or primary directly (custom headDirPath).
-     */
-    *_resolvePath(params) {
-        if (this.temp) {
-            return { path: params.tempPath, headDirPath: params.headDirPath };
-        }
-        if (params.reuse) {
-            return yield* this._reuseOrFallback(params.primary, params.alt, params.headDirPath);
-        }
-        return yield* this._createOrFallback(params.primary, params.alt, params.headDirPath);
-    }
-    /**
-     * Try to use or create the primary path. If creation fails (e.g. EACCES),
-     * fall back to the alt path. Throws if alt path also fails.
-     */
-    *_createOrFallback(primary, alt, headDirPath) {
-        const exists = yield* this.statOp(primary);
-        if (exists) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Creating directory at ${primary}`);
-        const created = yield* this.mkdirOp(primary, this.perm);
-        if (created) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Failed to create primary path, falling back to alt path`);
-        const altReady = yield* this._ensurePathAccessible(alt);
-        if (!altReady) {
-            this.logger.error(`Alt path not available at ${alt}`);
-            throw new PathError(`Alt path not available at ${alt}`, { path: alt });
-        }
-        return { path: alt, headDirPath: this.defaults.altHeadDirPath };
-    }
-    /**
-     * Verify the primary path exists and is accessible for reuse.
-     * If not accessible and using the default head dir, fall back to alt.
-     */
-    *_reuseOrFallback(primary, alt, headDirPath) {
-        const exists = yield* this.statOp(primary);
-        const accessible = exists ? yield* this.accessOp(primary) : false;
-        if (exists && accessible) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Reuse path unavailable, attempting to (re)create primary path`);
-        const primaryReady = yield* this._ensurePathAccessible(primary);
-        if (primaryReady) {
-            return { path: primary, headDirPath };
-        }
-        this.logger.debug(`Primary path unavailable, trying alt path`);
-        const altReady = yield* this._ensurePathAccessible(alt);
-        if (!altReady) {
-            this.logger.debug(`Alt path not available: ${alt}`);
-        }
-        return { path: alt, headDirPath: this.defaults.altHeadDirPath };
-    }
-    /**
-     * Ensure a path exists and is accessible, creating it if necessary.
-     * Returns true if the path is ready for use.
-     */
-    *_ensurePathAccessible(path) {
-        const exists = yield* this.statOp(path);
-        if (!exists) {
-            this.logger.debug(`Creating directory at ${path}`);
-            return yield* this.mkdirOp(path, this.perm);
-        }
-        return yield* this.accessOp(path);
-    }
-    /** Remove existing file or directory at path. */
-    *_clearPath(path) {
-        const stat = yield* this.statFileOp(path);
-        if (stat.isDirectory || stat.isFile) {
-            yield* this.rmOp(path);
-        }
-    }
-    /** Ensure the directory at path exists and is accessible, creating it if needed. */
-    *_ensureDirectoryExists(path) {
-        const exists = yield* this.statOp(path);
-        if (!exists) {
-            this.logger.debug(`Creating directory at ${path}`);
-            const created = yield* this.mkdirOp(path, this.perm);
-            if (!created) {
-                this.logger.debug(`Failed to create directory at ${path}`);
-            }
-        }
-        else {
-            const accessible = yield* this.accessOp(path);
-            if (!accessible) {
-                this.logger.debug(`Path exists but is not accessible: ${path}`);
-            }
-        }
-    }
-    /**
-     * Close the path manager
-     * If clear is true, removes the directory/file
-     * Uses Effection for structured concurrency
-     */
-    *close(clear = false) {
-        if (clear && this.path) {
-            yield* this.rmOp(this.path);
-        }
-        this.path = null;
-        this.opened = false;
-        return true;
-    }
-}