Search

workspace.filter() resolves a single live object across everything the workspace holds. You give it a query string and say which kind of object you want back; it searches that kind and returns the first match, or null when nothing matches.

import { Workspace } from "wative-core";

const ws = await Workspace.open({ path: "./my-wallet", password: "wsp-pwd" });
const acc = await ws.accounts.create("Trading Desk", "wsp-pwd", MNEMONIC);

const found = await ws.filter("Trading Desk", "Account");
found?.slug === acc.slug; // true

filter() requires a live session — it throws WORKSPACE_LOCKED on a locked workspace and UNSUPPORTED_OP on a closed one.

Signature

The method is overloaded on the objective so the return type is exact:

filter(query: string, objective: "Wallet"): Wallet | null;
filter(query: string, objective: "Address"): Address | null;
filter(query: string, objective: "Account"): Account | null;
filter(query: string, objective: "Asset"): Asset | null;

The objective is normalized before use, so surrounding whitespace and letter case are tolerated ("asset" and " Asset " both mean "Asset"). The query is trimmed, so a stray leading space does not defeat a match.

The four objectives

Matching rules

Each objective folds case where it makes sense and compares exactly where it must:

• Account — matches a slug exactly, or a displayName case-insensitively.
• Wallet — matches a wallet's numeric id (the query is parsed as a number), or a tag case-insensitively. Tags keep the case they were given; only the comparison folds. All wallets across all accounts are searched.
• Address — matches a publicKey using address-aware equality: EIP-55 checksummed comparison for EVM (so mixed-case and all-lowercase input both match), byte-exact for Solana base58.
• Asset — matches a symbol case-insensitively, or a contractAddress using the same address-aware equality as above. Both built-in and user-imported assets are searched; an asset whose network is not registered is skipped.

// Wallet by id, then by tag
await ws.filter("1", "Wallet");              // the wallet with id === 1
await ws.filter("alpha-strategy", "Wallet"); // the wallet carrying that tag

// Address is case-insensitive for EVM
const evm = acc.wallets[0].addresses.find((a) => a.vm === "evm");
await ws.filter(evm.publicKey, "Address");
await ws.filter(evm.publicKey.toLowerCase(), "Address"); // same address

// Asset by symbol, then by contract address
await ws.filter("USDC", "Asset");
await ws.filter("0xdAC17F958D2ee523a2206206994597C13D831ec7", "Asset"); // USDT

A query that matches nothing returns null rather than throwing:

await ws.filter("nonexistent", "Account");    // null
await ws.filter("DOES-NOT-EXIST", "Asset");   // null

Blank-filter behavior

An empty or whitespace-only query is a caller error, not a "match nothing" — it throws a WativeError with code === "PARAMETER_ERROR" and the message filter: query must be a non-empty string. A non-string query is rejected the same way. Use a real query, or handle the null return when a genuine query finds nothing.