local-kv-cli 1.0.0 → 2.0.0

package/dist/locate.d.ts

@@ -0,0 +1,19 @@
+export declare const PROJECT_FILE = ".lkv.json";
+export type StoreKind = "env" | "project" | "global";
+export interface StoreLocation {
+    path: string;
+    kind: StoreKind;
+}
+export declare function globalStorePath(): string;
+/** Walk up from `start` looking for a project store file. */
+export declare function findProjectStore(start: string): string | undefined;
+/**
+ * Which store to use, in order of priority:
+ * 1. LKV_STORE_PATH env variable
+ * 2. a .lkv.json in this folder or a parent (skipped with `global`)
+ * 3. the global store in the home folder
+ */
+export declare function locateStore(options?: {
+    cwd?: string;
+    global?: boolean;
+}): StoreLocation;

package/dist/locate.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_FILE = void 0;
+exports.globalStorePath = globalStorePath;
+exports.findProjectStore = findProjectStore;
+exports.locateStore = locateStore;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+exports.PROJECT_FILE = ".lkv.json";
+function globalStorePath() {
+    return path.join(os.homedir(), ".local-kv", "store.json");
+}
+/** Walk up from `start` looking for a project store file. */
+function findProjectStore(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        const candidate = path.join(dir, exports.PROJECT_FILE);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * Which store to use, in order of priority:
+ * 1. LKV_STORE_PATH env variable
+ * 2. a .lkv.json in this folder or a parent (skipped with `global`)
+ * 3. the global store in the home folder
+ */
+function locateStore(options = {}) {
+    if (process.env.LKV_STORE_PATH)
+        return { path: process.env.LKV_STORE_PATH, kind: "env" };
+    if (!options.global) {
+        const project = findProjectStore(options.cwd ?? process.cwd());
+        if (project)
+            return { path: project, kind: "project" };
+    }
+    return { path: globalStorePath(), kind: "global" };
+}

package/dist/store.d.ts

@@ -1,20 +1,72 @@
-export type Data = Record<string, string>;
-/** Where the data lives. Override with the LKV_STORE_PATH env variable. */
-export declare function getStorePath(): string;
+import { Entry, HistoryItem, StoreFile } from "./format";
+import { StoreKind } from "./locate";
+import { Value } from "./values";
+export interface StoreOptions {
+    /** Use this exact file instead of looking one up. */
+    path?: string;
+    /** Namespace to work in. Defaults to LKV_NAMESPACE or "default". */
+    namespace?: string;
+    /** Folder to start looking for a project .lkv.json from. */
+    cwd?: string;
+    /** Ignore project stores and use the global one. */
+    global?: boolean;
+}
+export interface ImportResult {
+    added: number;
+    overwritten: number;
+    skipped: number;
+}
 export declare class Store {
-    private readonly filePath;
-    constructor(filePath?: string);
-    get path(): string;
-    private read;
-    private write;
+    readonly path: string;
+    readonly kind: StoreKind | "custom";
+    readonly namespace: string;
+    /** Set to the backup file's path if a v1 store was upgraded while loading. */
+    migratedBackup?: string;
+    constructor(options?: StoreOptions | string);
     has(key: string): boolean;
-    /** Create a new pair. Throws if the key already exists (use update, or force). */
-    set(key: string, value: string, force?: boolean): void;
-    get(key: string): string | undefined;
+    get(key: string): Value | undefined;
+    /** The value plus its type, timestamps and history. */
+    entry(key: string): Entry | undefined;
+    /** Previous values of a key, oldest first (not including the current value). */
+    history(key: string): HistoryItem[] | undefined;
+    all(): Record<string, Value>;
+    entries(): Record<string, Entry>;
+    /** Case-insensitive match on keys and values. */
+    search(text: string): Record<string, Value>;
+    /** Namespace names with the number of keys in each. */
+    namespaces(): Record<string, number>;
+    /** Create a pair. Throws if the key already exists, unless `force` is set. */
+    set(key: string, value: Value, options?: {
+        force?: boolean;
+    }): void;
     /** Change an existing pair. Throws if the key does not exist. */
-    update(key: string, value: string): void;
+    update(key: string, value: Value): void;
     /** Returns true if the key existed and was removed. */
     delete(key: string): boolean;
-    all(): Data;
-    clear(): void;
+    rename(from: string, to: string, options?: {
+        force?: boolean;
+    }): void;
+    /** Add `by` to a number (a missing key starts at 0). Returns the new value. */
+    incr(key: string, by?: number): number;
+    /** Remove every pair in the current namespace. Returns how many were removed. */
+    clear(): number;
+    /** The current namespace (or all of them) in the store file format. */
+    export(all?: boolean): StoreFile;
+    /**
+     * Import data from an export (keeps namespaces, types and history)
+     * or a plain { key: value } object (goes into the current namespace).
+     * Existing keys are skipped unless `force` is set.
+     */
+    import(data: unknown, options?: {
+        force?: boolean;
+    }): ImportResult;
+    private readNamespace;
+    private load;
+    private save;
+    private mutate;
 }
+/**
+ * Read text that may be UTF-8 or UTF-16 (Windows PowerShell 5's `>` writes UTF-16),
+ * with or without a byte order mark.
+ */
+export declare function decodeText(buf: Buffer): string;

package/dist/store.js

@@ -34,83 +34,287 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Store = void 0;
-exports.getStorePath = getStorePath;
+exports.decodeText = decodeText;
 const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
-/** Where the data lives. Override with the LKV_STORE_PATH env variable. */
-function getStorePath() {
-    return process.env.LKV_STORE_PATH || path.join(os.homedir(), ".local-kv", "store.json");
-}
+const format_1 = require("./format");
+const locate_1 = require("./locate");
+const values_1 = require("./values");
 class Store {
-    filePath;
-    constructor(filePath = getStorePath()) {
-        this.filePath = filePath;
-    }
-    get path() {
-        return this.filePath;
-    }
-    read() {
-        // Prototype-less object so keys like "constructor" or "__proto__" are just normal keys.
-        const data = Object.create(null);
-        if (!fs.existsSync(this.filePath))
-            return data;
-        const raw = fs.readFileSync(this.filePath, "utf8");
-        if (!raw.trim())
-            return data;
-        try {
-            return Object.assign(data, JSON.parse(raw));
+    path;
+    kind;
+    namespace;
+    /** Set to the backup file's path if a v1 store was upgraded while loading. */
+    migratedBackup;
+    constructor(options = {}) {
+        const opts = typeof options === "string" ? { path: options } : options;
+        if (opts.path) {
+            this.path = opts.path;
+            this.kind = "custom";
         }
-        catch {
-            throw new Error(`Store file is corrupted: ${this.filePath}`);
+        else {
+            const location = (0, locate_1.locateStore)(opts);
+            this.path = location.path;
+            this.kind = location.kind;
         }
+        this.namespace = opts.namespace || process.env.LKV_NAMESPACE || format_1.DEFAULT_NAMESPACE;
     }
-    write(data) {
-        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
-        // Write to a temp file then rename, so a crash never leaves a half-written store.
-        const tmp = `${this.filePath}.tmp`;
-        fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
-        fs.renameSync(tmp, this.filePath);
-    }
+    // ---- reading ----
     has(key) {
-        return key in this.read();
+        return key in this.readNamespace();
     }
-    /** Create a new pair. Throws if the key already exists (use update, or force). */
-    set(key, value, force = false) {
-        const data = this.read();
-        if (!force && key in data) {
-            throw new Error(`Key "${key}" already exists. Use "update" to change it.`);
+    get(key) {
+        return this.entry(key)?.value;
+    }
+    /** The value plus its type, timestamps and history. */
+    entry(key) {
+        const ns = this.readNamespace();
+        return key in ns ? ns[key] : undefined;
+    }
+    /** Previous values of a key, oldest first (not including the current value). */
+    history(key) {
+        return this.entry(key)?.history;
+    }
+    all() {
+        const ns = this.readNamespace();
+        const out = (0, format_1.dict)();
+        for (const key of Object.keys(ns))
+            out[key] = ns[key].value;
+        return out;
+    }
+    entries() {
+        return this.readNamespace();
+    }
+    /** Case-insensitive match on keys and values. */
+    search(text) {
+        const needle = text.toLowerCase();
+        const out = (0, format_1.dict)();
+        const all = this.all();
+        for (const key of Object.keys(all)) {
+            const asText = typeof all[key] === "string" ? all[key] : JSON.stringify(all[key]);
+            if (key.toLowerCase().includes(needle) || asText.toLowerCase().includes(needle)) {
+                out[key] = all[key];
+            }
         }
-        data[key] = value;
-        this.write(data);
+        return out;
     }
-    get(key) {
-        const data = this.read();
-        return key in data ? data[key] : undefined;
+    /** Namespace names with the number of keys in each. */
+    namespaces() {
+        const file = this.load();
+        const out = (0, format_1.dict)();
+        for (const name of Object.keys(file.namespaces)) {
+            out[name] = Object.keys(file.namespaces[name]).length;
+        }
+        if (!(this.namespace in out))
+            out[this.namespace] = 0;
+        return out;
+    }
+    // ---- writing ----
+    /** Create a pair. Throws if the key already exists, unless `force` is set. */
+    set(key, value, options = {}) {
+        checkKey(key);
+        this.mutate((ns, now) => {
+            if (key in ns) {
+                if (!options.force)
+                    throw new Error(`Key "${key}" already exists. Use "update" to change it.`);
+                changeValue(ns[key], value, now);
+            }
+            else {
+                ns[key] = (0, format_1.newEntry)(value, now);
+            }
+        });
     }
     /** Change an existing pair. Throws if the key does not exist. */
     update(key, value) {
-        const data = this.read();
-        if (!(key in data)) {
-            throw new Error(`Key "${key}" not found. Use "set" to create it.`);
-        }
-        data[key] = value;
-        this.write(data);
+        this.mutate((ns, now) => {
+            if (!(key in ns))
+                throw new Error(`Key "${key}" not found. Use "set" to create it.`);
+            changeValue(ns[key], value, now);
+        });
     }
     /** Returns true if the key existed and was removed. */
     delete(key) {
-        const data = this.read();
-        if (!(key in data))
-            return false;
-        delete data[key];
-        this.write(data);
-        return true;
+        return this.mutate((ns) => {
+            if (!(key in ns))
+                return false;
+            delete ns[key];
+            return true;
+        });
     }
-    all() {
-        return this.read();
+    rename(from, to, options = {}) {
+        checkKey(to);
+        this.mutate((ns) => {
+            if (!(from in ns))
+                throw new Error(`Key "${from}" not found`);
+            if (from === to)
+                return;
+            if (to in ns && !options.force) {
+                throw new Error(`Key "${to}" already exists. Use --force to overwrite it.`);
+            }
+            ns[to] = ns[from];
+            delete ns[from];
+        });
+    }
+    /** Add `by` to a number (a missing key starts at 0). Returns the new value. */
+    incr(key, by = 1) {
+        checkKey(key);
+        if (!Number.isFinite(by))
+            throw new Error("Amount must be a number");
+        return this.mutate((ns, now) => {
+            if (!(key in ns)) {
+                ns[key] = (0, format_1.newEntry)(by, now);
+                return by;
+            }
+            const current = ns[key].value;
+            if (typeof current !== "number") {
+                throw new Error(`Key "${key}" is a ${ns[key].type}, not a number`);
+            }
+            const next = current + by;
+            changeValue(ns[key], next, now);
+            return next;
+        });
     }
+    /** Remove every pair in the current namespace. Returns how many were removed. */
     clear() {
-        this.write({});
+        return this.mutate((ns) => {
+            const keys = Object.keys(ns);
+            for (const key of keys)
+                delete ns[key];
+            return keys.length;
+        });
+    }
+    // ---- backup ----
+    /** The current namespace (or all of them) in the store file format. */
+    export(all = false) {
+        const file = this.load();
+        if (all)
+            return file;
+        return {
+            version: format_1.FORMAT_VERSION,
+            namespaces: (0, format_1.dict)({ [this.namespace]: file.namespaces[this.namespace] ?? (0, format_1.dict)() }),
+        };
+    }
+    /**
+     * Import data from an export (keeps namespaces, types and history)
+     * or a plain { key: value } object (goes into the current namespace).
+     * Existing keys are skipped unless `force` is set.
+     */
+    import(data, options = {}) {
+        if (!(0, format_1.isPlainObject)(data))
+            throw new Error("Import data must be a JSON object");
+        const now = new Date().toISOString();
+        const incoming = (0, format_1.isV2)(data)
+            ? (0, format_1.normalizeV2)(data, now).namespaces
+            : (0, format_1.dict)({ [this.namespace]: plainToNamespace(data, now) });
+        const result = { added: 0, overwritten: 0, skipped: 0 };
+        this.mutate((_, __, file) => {
+            for (const name of Object.keys(incoming)) {
+                const target = (file.namespaces[name] ??= (0, format_1.dict)());
+                for (const key of Object.keys(incoming[name])) {
+                    if (key in target) {
+                        if (!options.force) {
+                            result.skipped++;
+                            continue;
+                        }
+                        result.overwritten++;
+                    }
+                    else {
+                        result.added++;
+                    }
+                    target[key] = incoming[name][key];
+                }
+            }
+        });
+        return result;
+    }
+    // ---- file handling ----
+    readNamespace() {
+        return this.load().namespaces[this.namespace] ?? (0, format_1.dict)();
+    }
+    load() {
+        if (!fs.existsSync(this.path))
+            return (0, format_1.emptyFile)();
+        const raw = decodeText(fs.readFileSync(this.path));
+        if (!raw.trim())
+            return (0, format_1.emptyFile)();
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`Store file is corrupted: ${this.path}`);
+        }
+        const now = new Date().toISOString();
+        if ((0, format_1.isV2)(data))
+            return (0, format_1.normalizeV2)(data, now);
+        if (!(0, format_1.isPlainObject)(data))
+            throw new Error(`Store file is corrupted: ${this.path}`);
+        // A v1 store: keep a backup, then upgrade it in place.
+        const backup = `${this.path}.v1-backup`;
+        fs.copyFileSync(this.path, backup);
+        const upgraded = (0, format_1.migrateV1)(data, now);
+        this.save(upgraded);
+        this.migratedBackup = backup;
+        return upgraded;
+    }
+    save(file) {
+        fs.mkdirSync(path.dirname(this.path), { recursive: true });
+        // Write to a temp file then rename, so a crash never leaves a half-written store.
+        const tmp = `${this.path}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(file, null, 2));
+        fs.renameSync(tmp, this.path);
+    }
+    mutate(fn) {
+        const file = this.load();
+        const ns = (file.namespaces[this.namespace] ??= (0, format_1.dict)());
+        const result = fn(ns, new Date().toISOString(), file);
+        // Don't leave empty namespaces lying around (except the default one).
+        for (const name of Object.keys(file.namespaces)) {
+            if (name !== format_1.DEFAULT_NAMESPACE && Object.keys(file.namespaces[name]).length === 0) {
+                delete file.namespaces[name];
+            }
+        }
+        this.save(file);
+        return result;
     }
 }
 exports.Store = Store;
+function checkKey(key) {
+    if (typeof key !== "string" || key === "")
+        throw new Error("Key must be a non-empty string");
+}
+function changeValue(entry, value, now) {
+    if (JSON.stringify(entry.value) !== JSON.stringify(value)) {
+        entry.history.push({ value: entry.value, type: entry.type, updated: entry.updated });
+        if (entry.history.length > format_1.HISTORY_LIMIT)
+            entry.history.splice(0, entry.history.length - format_1.HISTORY_LIMIT);
+    }
+    entry.value = value;
+    entry.type = (0, values_1.typeOf)(value);
+    entry.updated = now;
+}
+function plainToNamespace(data, now) {
+    const ns = (0, format_1.dict)();
+    for (const key of Object.keys(data)) {
+        if (key === "")
+            continue;
+        ns[key] = (0, format_1.toEntry)({ value: data[key] }, now);
+    }
+    return ns;
+}
+/**
+ * Read text that may be UTF-8 or UTF-16 (Windows PowerShell 5's `>` writes UTF-16),
+ * with or without a byte order mark.
+ */
+function decodeText(buf) {
+    if (buf[0] === 0xff && buf[1] === 0xfe)
+        return buf.subarray(2).toString("utf16le");
+    if (buf[0] === 0xfe && buf[1] === 0xff) {
+        const swapped = Buffer.from(buf.subarray(2, buf.length - (buf.length % 2)));
+        swapped.swap16();
+        return swapped.toString("utf16le");
+    }
+    if (buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf)
+        return buf.subarray(3).toString("utf8");
+    return buf.toString("utf8");
+}

package/dist/values.d.ts

@@ -0,0 +1,14 @@
+export type Value = string | number | boolean | null | Value[] | {
+    [key: string]: Value;
+};
+export type ValueType = "string" | "number" | "boolean" | "json";
+export declare const VALUE_TYPES: readonly ValueType[];
+export declare function typeOf(value: Value): ValueType;
+/**
+ * Turn CLI text into a typed value.
+ * Without an explicit type, only unambiguous input is converted, so "007" or "1e5" stay text.
+ */
+export declare function parseValue(input: string, type?: ValueType): Value;
+/** Text form for display: strings as-is, everything else as JSON. */
+export declare function formatValue(value: Value, pretty?: boolean): string;
+export declare function isValueType(type: string): type is ValueType;

package/dist/values.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALUE_TYPES = void 0;
+exports.typeOf = typeOf;
+exports.parseValue = parseValue;
+exports.formatValue = formatValue;
+exports.isValueType = isValueType;
+exports.VALUE_TYPES = ["string", "number", "boolean", "json"];
+function typeOf(value) {
+    if (typeof value === "string")
+        return "string";
+    if (typeof value === "number")
+        return "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    return "json";
+}
+/**
+ * Turn CLI text into a typed value.
+ * Without an explicit type, only unambiguous input is converted, so "007" or "1e5" stay text.
+ */
+function parseValue(input, type) {
+    switch (type) {
+        case "string":
+            return input;
+        case "number": {
+            const n = Number(input);
+            if (input.trim() === "" || !Number.isFinite(n))
+                throw new Error(`"${input}" is not a number`);
+            return n;
+        }
+        case "boolean":
+            if (input === "true")
+                return true;
+            if (input === "false")
+                return false;
+            throw new Error(`"${input}" is not a boolean (use true or false)`);
+        case "json":
+            try {
+                return JSON.parse(input);
+            }
+            catch {
+                throw new Error(`"${input}" is not valid JSON`);
+            }
+        case undefined:
+            if (input === "true")
+                return true;
+            if (input === "false")
+                return false;
+            if (input.trim() !== "" && String(Number(input)) === input)
+                return Number(input);
+            if (/^\s*[[{]/.test(input)) {
+                try {
+                    return JSON.parse(input);
+                }
+                catch {
+                    // Not JSON after all; keep it as text.
+                }
+            }
+            return input;
+        default:
+            throw new Error(`Unknown type "${type}". Use one of: ${exports.VALUE_TYPES.join(", ")}`);
+    }
+}
+/** Text form for display: strings as-is, everything else as JSON. */
+function formatValue(value, pretty = false) {
+    if (typeof value === "string")
+        return value;
+    return JSON.stringify(value, null, pretty ? 2 : undefined);
+}
+function isValueType(type) {
+    return exports.VALUE_TYPES.includes(type);
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "local-kv-cli",
-  "version": "1.0.0",
-  "description": "A tiny CLI to store key-value pairs locally on your machine",
+  "version": "2.0.0",
+  "description": "A tiny CLI to store key-value pairs locally: typed values, counters, history, namespaces, per-project stores and env export",
   "keywords": [
     "cli",
     "key-value",
     "kv",
     "store",
     "local",
-    "storage"
+    "storage",
+    "counter",
+    "env",
+    "dotenv",
+    "namespace"
   ],
   "license": "MIT",
   "author": "",
@@ -19,14 +23,16 @@
     "lkv": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc",
-    "test": "npm run build && node --test",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
+    "test": "npm run build && node --test test/*.test.js",
     "prepublishOnly": "npm test"
   },
   "devDependencies": {