local-kv-cli 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 2.0.0
+
+### Breaking changes
+
+- **New data file format.** Each value now stores its type, created/updated times and history, and values are grouped into namespaces. 1.x files are upgraded automatically on first use, and the old file is kept as `store.json.v1-backup`. 1.x can't read the new format.
+- **Values are typed.** `lkv set n 42` now stores the number `42`, and `true`, `false` and JSON objects/arrays are stored as their type. Values like `007` or `1e5` stay text. Use `--type string` to keep text. Values from 1.x stay text.
+- **Library API.** `Store` values are typed (`Value`) instead of always strings. `set(key, value, force)` is now `set(key, value, { force })`. `getStorePath()` was replaced by `locateStore()` / `globalStorePath()`.
+- **Project stores.** Inside a folder with a `.lkv.json` (created by `lkv init`), `lkv` uses that file instead of the global store. Use `--global` to get the global store.
+- The `LKV_STORE_PATH` environment variable still overrides everything.
+
+### New
+
+- `incr` / `decr` counters
+- `history` of previous values (last 20 per key); `list --long` shows type and update time
+- Namespaces: `-n <name>`, `LKV_NAMESPACE`, `lkv namespaces`
+- `lkv init` for per-project stores
+- `search`, `list --filter`
+- `rename`
+- `export` / `import` (handles UTF-16 files from Windows PowerShell's `>`)
+- `env` (sh, PowerShell, cmd) and `run <command>`
+- `get --copy` to copy a value to the clipboard, `get --json`
+- `--version`
+
+## 1.0.0
+
+- First release: `set`, `get`, `update`, `delete`, `list`, `clear`, `path`

package/README.md

@@ -1,6 +1,6 @@
 # local-kv-cli
 
-A tiny, zero-dependency CLI to store key-value pairs locally on your machine.
+A tiny, zero-dependency CLI to store key-value pairs locally on your machine, with typed values, counters, history, namespaces, per-project stores and environment variable export.
 
 ## Install
 
@@ -8,32 +8,140 @@ A tiny, zero-dependency CLI to store key-value pairs locally on your machine.
 npm install -g local-kv-cli
 ```
 
-## Usage
+## Basics
 
 ```bash
 lkv set api_url https://example.com   # create a pair
 lkv get api_url                       # print a value
 lkv update api_url https://new.com    # change an existing value
-lkv list                              # show all pairs (add --json for JSON)
-lkv delete api_url                    # remove a pair
-lkv clear                             # remove everything
-lkv path                              # show where data is stored
+lkv rename api_url base_url           # rename a key
+lkv delete base_url                   # remove a pair
+lkv list                              # show all pairs
+lkv clear                             # remove everything in the namespace
 ```
 
 `set` won't overwrite an existing key; use `update`, or `set <key> <value> --force`.
 
-Data is stored in `~/.local-kv/store.json`. Set `LKV_STORE_PATH` to use a different file.
+## Typed values
+
+Numbers, `true`/`false` and JSON are stored with their type:
+
+```bash
+lkv set retries 3                 # number
+lkv set debug true                # boolean
+lkv set config '{"port":8080}'    # JSON
+lkv set zip 02134                 # stays text (leading zero)
+lkv set -t string code 42         # force a type: string, number, boolean or json
+lkv get config --json             # print as JSON
+```
+
+## Counters
+
+```bash
+lkv incr build_count      # 1  (missing keys start at 0)
+lkv incr build_count 10   # 11
+lkv decr build_count      # 10
+```
+
+## History and details
+
+Every change keeps the previous value (the last 20 per key).
+
+```bash
+lkv history retries   # current value first, then older ones
+lkv list --long       # type and last update time for each key
+```
+
+## Search
+
+```bash
+lkv search example            # key or value contains "example"
+lkv list --filter api         # key contains "api"
+lkv list --json               # everything as JSON
+```
+
+## Namespaces
+
+Keep separate groups of values:
+
+```bash
+lkv -n work set token abc123
+lkv -n work list
+lkv namespaces               # list namespaces and how many keys each has
+```
+
+You can also set the `LKV_NAMESPACE` environment variable.
+
+## Per-project stores
+
+```bash
+cd my-project
+lkv init        # creates .lkv.json here
+lkv set port 3000
+```
+
+Inside that folder (and its subfolders) `lkv` uses the project's `.lkv.json`. Add `--global` (`-g`) to use your global store instead. Add `.lkv.json` to `.gitignore` if it holds private values.
+
+`lkv path` shows which file is in use.
+
+## Environment variables
+
+```bash
+eval "$(lkv env)"                    # bash / zsh
+lkv env | Invoke-Expression          # PowerShell
+lkv env --shell cmd                  # cmd.exe syntax
+lkv env --upper                      # API_URL instead of api_url
+
+lkv run npm start                    # run a command with your values as env variables
+```
+
+Keys that aren't valid variable names (like `my-key`) are skipped with a warning.
+
+## Backup and restore
+
+```bash
+lkv export backup.json          # current namespace
+lkv export backup.json --all    # every namespace
+lkv import backup.json          # skips keys that already exist
+lkv import backup.json --force  # overwrite them
+```
+
+`import` also accepts a plain `{ "key": "value" }` JSON object.
+
+## Clipboard
+
+```bash
+lkv get api_url --copy
+```
+
+On Linux this needs `wl-clipboard`, `xclip` or `xsel`.
+
+## Where data is stored
+
+1. The file in the `LKV_STORE_PATH` environment variable, if set
+2. Otherwise a `.lkv.json` in the current folder or a parent folder
+3. Otherwise `~/.local-kv/store.json`
 
 ## Use from code
 
 ```ts
 import { Store } from "local-kv-cli";
 
-const store = new Store();
-store.set("visits", "1");
-store.get("visits"); // "1"
+const store = new Store();                        // same lookup as the CLI
+const work = new Store({ namespace: "work" });
+const custom = new Store({ path: "./data.json" });
+
+store.set("visits", 0);
+store.incr("visits");            // 1
+store.get("visits");             // 1
+store.history("visits");         // [{ value: 0, type: "number", updated: "..." }]
+store.entry("visits");           // value, type, created, updated, history
 ```
 
+## Upgrading from 1.x
+
+Your data is upgraded automatically the first time 2.x runs, and a copy of the old file is saved next to it as `store.json.v1-backup`. See [CHANGELOG.md](CHANGELOG.md) for breaking changes.
+
 ## License
 
 MIT

package/dist/args.d.ts

@@ -0,0 +1,7 @@
+export interface ParsedArgs {
+    command?: string;
+    args: string[];
+    options: Record<string, string | undefined>;
+    flags: Set<string>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;

package/dist/args.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+/** Flags that take a value, with their short aliases. */
+const VALUE_FLAGS = {
+    "--namespace": "namespace",
+    "-n": "namespace",
+    "--type": "type",
+    "-t": "type",
+    "--filter": "filter",
+    "--shell": "shell",
+};
+/** On/off flags, with their short aliases. */
+const BOOL_FLAGS = {
+    "--force": "force",
+    "-f": "force",
+    "--json": "json",
+    "--long": "long",
+    "-l": "long",
+    "--copy": "copy",
+    "-c": "copy",
+    "--all": "all",
+    "--global": "global",
+    "-g": "global",
+    "--upper": "upper",
+    "--help": "help",
+    "-h": "help",
+    "--version": "version",
+    "-v": "version",
+};
+/** Negative numbers ("-5") are values, not flags. */
+function isFlag(token) {
+    return token.startsWith("-") && token !== "-" && !/^-\d/.test(token);
+}
+function parseArgs(argv) {
+    const parsed = { args: [], options: {}, flags: new Set() };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === "--") {
+            parsed.args.push(...argv.slice(i + 1));
+            break;
+        }
+        // Everything after `run`'s first word belongs to the command being run.
+        if (parsed.command === "run" && parsed.args.length > 0) {
+            parsed.args.push(...argv.slice(i));
+            break;
+        }
+        if (!isFlag(token)) {
+            if (parsed.command === undefined)
+                parsed.command = token;
+            else
+                parsed.args.push(token);
+            continue;
+        }
+        const eq = token.indexOf("=");
+        const name = eq === -1 ? token : token.slice(0, eq);
+        if (name in VALUE_FLAGS) {
+            const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+            if (value === undefined)
+                throw new Error(`${name} needs a value`);
+            parsed.options[VALUE_FLAGS[name]] = value;
+        }
+        else if (name in BOOL_FLAGS && eq === -1) {
+            parsed.flags.add(BOOL_FLAGS[name]);
+        }
+        else {
+            throw new Error(`Unknown option "${token}". Run "lkv help".`);
+        }
+    }
+    return parsed;
+}

package/dist/cli.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { Store } from "./store";
-export declare function run(argv: string[], store?: Store): void;
+/** Runs the CLI and returns the exit code. */
+export declare function main(argv: string[]): number;