polkadot-cli 1.8.1 → 1.9.0

package/README.md

@@ -1,3 +1,4 @@
+[![npm version](https://img.shields.io/npm/v/polkadot-cli)](https://www.npmjs.com/package/polkadot-cli)
 [![codecov](https://codecov.io/gh/peetzweg/polkadot-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/peetzweg/polkadot-cli)
 
 # polkadot-cli
@@ -309,12 +310,32 @@ dot query System.Number --output json | jq '.+1'
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
+#### Partial key queries
+
+For storage maps with multiple keys (NMaps), you can provide fewer keys than
+expected to retrieve all entries matching that prefix. This uses the chain's
+prefix-based iteration and does not require `--dump`.
+
+```bash
+# Full key — returns a single value
+dot query Staking.ErasStakers 100 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+
+# Partial key — returns all entries matching the first key
+dot query Staking.ErasStakers 100
+
+# No keys — requires --dump (safety net for large maps)
+dot query Staking.ErasStakers --dump --limit 10
+```
+
+The `--limit` option applies to partial key results just like it does for
+`--dump` (default: 100, use `--limit 0` for unlimited).
+
 #### Output formatting
 
 Query results automatically convert on-chain types for readability:
 
 - **BigInt** values (e.g. balances) render as decimal strings
-- **Binary** fields (e.g. token `name`, `symbol`) render as text when valid UTF-8, or as `0x`-prefixed hex otherwise
+- **Binary** fields (e.g. token `name`, `symbol`) render as text when the value contains only printable characters, or as `0x`-prefixed hex otherwise (values containing control characters, Private Use Area code points, or invalid UTF-8 sequences always fall back to hex)
 - **Uint8Array** values render as `0x`-prefixed hex
 
 ```bash

package/dist/cli.mjs

@@ -387,14 +387,35 @@ var init_accounts = __esm(() => {
   DEV_NAMES = ["alice", "bob", "charlie", "dave", "eve", "ferdie"];
 });
 
+// src/utils/binary-display.ts
+function isReadableText(text) {
+  for (let i = 0;i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code <= 31 && code !== 9 && code !== 10 && code !== 13)
+      return false;
+    if (code === 127)
+      return false;
+    if (code >= 128 && code <= 159)
+      return false;
+    if (code === 65533)
+      return false;
+    if (code >= 57344 && code <= 63743)
+      return false;
+  }
+  return true;
+}
+function binaryToDisplay(value) {
+  const text = value.asText();
+  return isReadableText(text) ? text : value.asHex();
+}
+
 // src/core/output.ts
 import { Binary } from "polkadot-api";
 function replacer(_key, value) {
   if (typeof value === "bigint")
     return value.toString();
   if (value instanceof Binary) {
-    const text = value.asText();
-    return text.includes("�") ? value.asHex() : text;
+    return binaryToDisplay(value);
   }
   if (value instanceof Uint8Array)
     return `0x${Buffer.from(value).toString("hex")}`;
@@ -2158,7 +2179,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.8.1";
+var version = "1.9.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -3927,14 +3948,15 @@ async function handleQuery(target, keys, opts) {
     ];
     const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, effectiveKeys);
     const format = opts.output ?? "pretty";
-    if (storageItem.type === "map" && parsedKeys.length === 0) {
-      if (!opts.dump) {
+    const expectedLen = storageItem.type === "map" && storageItem.keyTypeId != null ? meta.builder.buildStorage(palletInfo.name, storageItem.name).len : 0;
+    if (storageItem.type === "map" && parsedKeys.length < expectedLen) {
+      if (parsedKeys.length === 0 && !opts.dump) {
         clientHandle.destroy();
         await showItemHelp("query", target, { chain: opts.chain, rpc: opts.rpc });
         console.log(`${DIM}Hint: use --dump to fetch all entries${RESET}`);
         return;
       }
-      const entries = await storageApi.getEntries();
+      const entries = await storageApi.getEntries(...parsedKeys);
       const limit = Number(opts.limit);
       const truncated = limit > 0 && entries.length > limit;
       const display = truncated ? entries.slice(0, limit) : entries;
@@ -3978,18 +4000,18 @@ async function parseStorageKeys(meta, palletName2, storageItem, args) {
     throw new Error(`${palletName2}.${storageItem.name} key expects ${typeDesc}
 ` + `  Pass 1 argument. Got ${args.length}.`);
   }
-  if (args.length !== len) {
+  if (args.length > len) {
     let typeDesc;
     if (keyEntry.type === "tuple") {
       typeDesc = keyEntry.value.map((e) => describeType(meta.lookup, e.id)).join(", ");
     } else {
       typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
     }
-    throw new Error(`${palletName2}.${storageItem.name} expects ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
+    throw new Error(`${palletName2}.${storageItem.name} expects at most ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
   }
   if (keyEntry.type === "tuple") {
     const entries = keyEntry.value;
-    return Promise.all(entries.map((entry, i) => parseTypedArg(meta, entry, args[i])));
+    return Promise.all(entries.slice(0, args.length).map((entry, i) => parseTypedArg(meta, entry, args[i])));
   }
   return Promise.all(args.map((arg) => parseTypedArg(meta, keyEntry, arg)));
 }
@@ -4452,8 +4474,7 @@ function formatEventValue(v) {
   if (v === null || v === undefined)
     return "null";
   if (v instanceof Binary3) {
-    const text = v.asText();
-    return text.includes("�") ? v.asHex() : text;
+    return binaryToDisplay(v);
   }
   return JSON.stringify(v, (_k, val) => typeof val === "bigint" ? val.toString() : val);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {