keri-ts 0.2.3 → 0.3.0

package/esm/db/core/path-manager.js

@@ -6,15 +6,17 @@
  */
 import * as dntShim from "../../_dnt.shims.js";
 import { action } from "effection";
+import { isAbsolute, join } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
 import { InvalidPathNameError, PathError } from "../../core/errors.js";
 import { consoleLogger } from "../../core/logger.js";
+/** Defaults for the path manager */
 export const PATH_DEFAULTS = {
     headDirPath: "/usr/local/var",
     tailDirPath: "keri/db",
     cleanTailDirPath: "keri/clean/db",
     altHeadDirPath: "~",
-    altTailDirPath: ".keri/db",
-    altCleanTailDirPath: ".keri/clean/db",
+    altTailDirPath: ".tufa/db",
+    altCleanTailDirPath: ".tufa/clean/db",
     tempHeadDir: "/tmp",
     tempPrefix: "keri_lmdb_",
     tempSuffix: "_test",
@@ -24,11 +26,31 @@ export const PATH_DEFAULTS = {
 };
 /**
  * PathManager manages file and directory paths
+ *
+ * Main file paths:
+ * - persistent path: /{head}/{tail}      /{base}/{name}
+ * -      clean path: /{head}/{tail}/clean/{base}/{name}
+ * -        alt path: /{altHead}/{altTail}/{base}/{name}
+ * - HOME (alt) path:          ~/{altTail}/{base}/{name}
+ *
+ * Temp files:
+ * -       temp path: /{tempPrefix}/{tempSuffix}{tempHead}
+ *
+ * The path manager will use the persistent path by default.
+ * If the persistent path does not exist, the path manager will use the alt path.
+ * If the alt path does not exist, the path manager will use the temp path.
+ *
+ * Temp files:
+ *   If the temp path does not exist, the path manager will create it.
+ *   If the temp path exists, the path manager will use it.
+ *   If the temp path exists and is not a directory, the path manager will throw an error.
+ *   If the temp path exists and is a directory, the path manager will use it.
+ *   If the temp path exists and is a directory, the path manager will use it.
  */
 export class PathManager {
     constructor(options = {}, defaults) {
-        // name of the path, dir or file name
-        Object.defineProperty(this, "_name", {
+        // head directory path
+        Object.defineProperty(this, "headDirPath", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -41,15 +63,15 @@ export class PathManager {
             writable: true,
             value: void 0
         });
-        // temporary directory flag
-        Object.defineProperty(this, "temp", {
+        // name of the path, dir or file name
+        Object.defineProperty(this, "_name", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        // head directory path
-        Object.defineProperty(this, "headDirPath", {
+        // temporary directory flag
+        Object.defineProperty(this, "temp", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -62,48 +84,56 @@ export class PathManager {
             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,
@@ -131,8 +161,10 @@ export class PathManager {
     }
     set name(value) {
         // Check if path is absolute
-        if (value.startsWith("/") || value.includes(":")) {
-            throw new InvalidPathNameError(`Not relative name=${value} path.`, { name: value });
+        if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
+            throw new InvalidPathNameError(`Not relative name=${value} path.`, {
+                name: value,
+            });
         }
         this._name = value;
     }
@@ -140,11 +172,29 @@ export class PathManager {
         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 `${tempDir}/${tempName}`;
+        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 === "~" || path.startsWith("~/")) {
-            const home = dntShim.Deno.env.get("HOME") || "~";
+        if (path === "~" || /^~[\\/]/.test(path)) {
+            const home = this._resolveHomeDir();
             return path === "~" ? home : path.replace("~", home);
         }
         return path;
@@ -161,12 +211,9 @@ export class PathManager {
         else {
             tail = this.defaults.tailDirPath;
         }
-        const parts = [head, tail];
-        if (this.base)
-            parts.push(this.base);
-        parts.push(this.name);
-        const path = parts.join("/");
-        return path;
+        return this.base
+            ? join(head, tail, this.base, this.name)
+            : join(head, tail, this.name);
     }
     _getAltPath(clean) {
         // HOME or ~ / tail / base / name
@@ -179,12 +226,9 @@ export class PathManager {
         else {
             tail = this.defaults.altTailDirPath;
         }
-        const altParts = [head, tail];
-        if (this.base)
-            altParts.push(this.base);
-        altParts.push(this.name);
-        const path = altParts.join("/");
-        return path;
+        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.
@@ -207,7 +251,7 @@ export class PathManager {
      * Helper: Convert Promise-based file system operations to Effection operations
      * This ensures proper structured concurrency and cancellation support
      */
-    *_statOp(path) {
+    *statOp(path) {
         return yield* action((resolve, reject) => {
             dntShim.Deno.stat(path)
                 .then(() => resolve(true))
@@ -222,7 +266,7 @@ export class PathManager {
             return () => { };
         });
     }
-    *_accessOp(path) {
+    *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
@@ -232,7 +276,7 @@ export class PathManager {
             return () => { };
         });
     }
-    *_mkdirOp(path, perm) {
+    *mkdirOp(path, perm) {
         return yield* action((resolve, reject) => {
             dntShim.Deno.mkdir(path, { recursive: true, mode: perm })
                 .then(() => resolve(true))
@@ -247,7 +291,7 @@ export class PathManager {
             return () => { };
         });
     }
-    *_rmOp(path) {
+    *rmOp(path) {
         return yield* action((resolve, reject) => {
             dntShim.Deno.remove(path, { recursive: true })
                 .then(() => resolve(undefined))
@@ -262,7 +306,7 @@ export class PathManager {
             return () => { };
         });
     }
-    *_statFileOp(path) {
+    *statFileOp(path) {
         return yield* action((resolve, reject) => {
             dntShim.Deno.stat(path)
                 .then((stats) => {
@@ -286,148 +330,142 @@ export class PathManager {
         });
     }
     /**
-     * Reopen/create the directory or file path
+     * 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 (~/.keri/*) on OS errors or access issues
+     * - Falls back to alt path (~/.tufa/*) on OS errors or access issues
      *
-     * Uses Effection for structured concurrency:
-     * - All file system operations are cancellable
-     * - No dangling promises - operations tracked in Effection task tree
-     * - Automatic cleanup if parent operation is halted
+     * Returns Effection Operation with true if path is created and accessible, false otherwise.
      */
     *reopen(options = {}) {
-        const temp = options.temp ?? this.temp;
-        let headDirPath = options.headDirPath ?? this.headDirPath;
-        const perm = options.perm ?? this.perm;
-        const clear = options.clear || false;
-        const reuse = options.reuse || false;
+        this._applyOptions(options);
+        const headDirPath = options.headDirPath ?? this.headDirPath;
         const clean = options.clean || false;
-        const mode = options.mode ?? this.mode;
-        const fext = options.fext ?? this.fext;
-        this.temp = temp;
-        this.perm = perm;
-        this.mode = mode;
-        this.fext = fext;
-        let path;
+        const reuse = options.reuse || false;
+        const clear = options.clear || false;
         const [primary, alt, tempPath] = this._getPaths({
             ...options,
             headDirPath,
             clean,
         });
-        if (temp) {
-            // Use temporary directory
-            path = tempPath;
-        }
-        else {
-            // Use persistent directory - try primary first, fall back to alt on error
-            path = primary;
-            let useAltPath = false;
-            // Only attempt fallback if using default headDirPath (not a custom one)
-            const usingDefaultHeadDir = headDirPath === this.defaults.headDirPath;
-            if (!reuse && usingDefaultHeadDir) {
-                // Check if path exists using Effection operation
-                const pathExists = yield* this._statOp(path);
-                if (!pathExists) {
-                    // Path doesn't exist, try to create it
-                    this.logger.info(`Creating directory at ${path}`);
-                    const created = yield* this._mkdirOp(path, perm);
-                    if (!created) {
-                        // Creation failed (e.g., EACCES) - fall back to alt path
-                        this.logger.warn(`Failed to create primary path, falling back to alt path`);
-                        useAltPath = true;
-                        path = alt;
-                        headDirPath = this.defaults.altHeadDirPath;
-                    }
-                }
-                // If we're using alt path, ensure it exists
-                if (useAltPath) {
-                    const altPathExists = yield* this._statOp(path);
-                    if (!altPathExists) {
-                        // Alt path doesn't exist, create it
-                        this.logger.info(`Creating alt directory at ${path}`);
-                        const created = yield* this._mkdirOp(path, perm);
-                        if (!created) {
-                            // Even alt path creation failed - this is unexpected, but we'll continue
-                            this.logger.error(`Failed to create alt directory at ${path}`);
-                            throw new PathError(`Failed to create alt directory at ${path}`, { path });
-                        }
-                    }
-                    else {
-                        // Path exists, verify access
-                        const altHasAccess = yield* this._accessOp(path);
-                        if (!altHasAccess) {
-                            // Path exists but no access - this shouldn't happen for alt path, but log it
-                            this.logger.error(`Alt path exists but is not accessible: ${path}`);
-                            throw new PathError(`Alt path exists but is not accessible: ${path}`, { path });
-                        }
-                    }
-                }
-            }
-            else if (reuse) {
-                // Reuse mode - just verify the path exists and is accessible
-                const pathExists = yield* this._statOp(path);
-                const hasAccess = pathExists ? yield* this._accessOp(path) : false;
-                if (!pathExists || !hasAccess) {
-                    // If reuse path doesn't work and we're using default, try alt
-                    if (usingDefaultHeadDir) {
-                        this.logger.info(`Reuse path not accessible, trying alt path`);
-                        path = alt;
-                        headDirPath = this.defaults.altHeadDirPath;
-                        const altPathExists = yield* this._statOp(path);
-                        const altHasAccess = altPathExists
-                            ? yield* this._accessOp(path)
-                            : false;
-                        if (!altPathExists) {
-                            // Alt path doesn't exist, create it
-                            this.logger.info(`Creating alt directory at ${path}`);
-                            const created = yield* this._mkdirOp(path, perm);
-                            if (!created) {
-                                this.logger.warn(`Warning: Failed to create alt directory at ${path}`);
-                            }
-                        }
-                        else if (!altHasAccess) {
-                            // Alt path exists but not accessible - unexpected but continue
-                            this.logger.warn(`Warning: Alt path exists but is not accessible: ${path}`);
-                        }
-                    }
-                }
-            }
-        }
-        // Update headDirPath if we fell back to alt
-        this.headDirPath = headDirPath;
-        // Clear if requested
+        const resolved = yield* this._resolvePath({
+            primary,
+            alt,
+            tempPath,
+            headDirPath,
+            reuse,
+        });
+        this.headDirPath = resolved.headDirPath;
         if (clear) {
-            const pathStat = yield* this._statFileOp(path);
-            if (pathStat && (pathStat.isDirectory || pathStat.isFile)) {
-                yield* this._rmOp(path);
-            }
+            yield* this._clearPath(resolved.path);
         }
-        // Create directory if it doesn't exist (final check)
         if (!this.filed) {
-            const pathExists = yield* this._statOp(path);
-            if (!pathExists) {
-                // Path doesn't exist, create it
-                this.logger.info(`Creating directory at ${path}`);
-                const created = yield* this._mkdirOp(path, perm);
-                if (!created) {
-                    // Creation failed - this is unexpected at this point, but log it
-                    this.logger.warn(`Warning: Failed to create directory at ${path}`);
-                }
-            }
-            else {
-                // Path exists, verify we can access it
-                const hasAccess = yield* this._accessOp(path);
-                if (!hasAccess) {
-                    // Path exists but not accessible - unexpected but continue
-                    this.logger.warn(`Warning: Path exists but is not accessible: ${path}`);
-                }
-            }
+            yield* this._ensureDirectoryExists(resolved.path);
         }
-        this.path = 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.info(`Creating directory at ${primary}`);
+        const created = yield* this.mkdirOp(primary, this.perm);
+        if (created) {
+            return { path: primary, headDirPath };
+        }
+        this.logger.warn(`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.info(`Reuse path unavailable, attempting to (re)create primary path`);
+        const primaryReady = yield* this._ensurePathAccessible(primary);
+        if (primaryReady) {
+            return { path: primary, headDirPath };
+        }
+        this.logger.info(`Primary path unavailable, trying alt path`);
+        const altReady = yield* this._ensurePathAccessible(alt);
+        if (!altReady) {
+            this.logger.warn(`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.info(`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.info(`Creating directory at ${path}`);
+            const created = yield* this.mkdirOp(path, this.perm);
+            if (!created) {
+                this.logger.warn(`Failed to create directory at ${path}`);
+            }
+        }
+        else {
+            const accessible = yield* this.accessOp(path);
+            if (!accessible) {
+                this.logger.warn(`Path exists but is not accessible: ${path}`);
+            }
+        }
+    }
     /**
      * Close the path manager
      * If clear is true, removes the directory/file
@@ -435,24 +473,10 @@ export class PathManager {
      */
     *close(clear = false) {
         if (clear && this.path) {
-            yield* this._rmOp(this.path);
+            yield* this.rmOp(this.path);
         }
         this.path = null;
         this.opened = false;
         return true;
     }
-    /**
-     * Check if database files exist in the path directory
-     * LMDB creates data.mdb and lock.mdb files
-     * Returns true if data.mdb exists (lock.mdb might not exist if no active transactions)
-     * Uses Effection for structured concurrency
-     */
-    *databaseFilesExist() {
-        if (!this.path) {
-            return false;
-        }
-        const dataMdbPath = `${this.path}/data.mdb`;
-        const pathStat = yield* this._statFileOp(dataMdbPath);
-        return pathStat.isFile ?? false;
-    }
 }

package/esm/db/index.js

@@ -2,3 +2,4 @@
  * Database module exports
  */
 export * from "./basing.js";
+export * from "./keeping.js";