Dict
Dicts: a key-value store for small state that code and agents share.
seen = noclick.Dict.from_name("processed-orders", create_if_missing=True)
if "o_1841" not in seen:
seen["o_1841"] = {"status": "refunded"}
print(seen.increment("refunds-today"))Keys are strings and values are JSON (a dict, list, string, number, bool or
None), never pickled, so a value your Python code writes reads the same from
TypeScript, an agent or the console. A dict works like Python's own: d[key],
d[key] = value, key in d, del d[key], len(d) and iterating its
keys, plus expiry (ttl_s), locks (put_if_absent) and atomic counters
(increment). Each of those reads or writes the API, so the .aio forms of
get, put and pop are how async code does the same.
class DictA key-value store: string keys, JSON values, optional expiry per key. get, put, has,
remove and size are what Python writes as d[key], d[key] = value, key in d,
del d[key] and len(d); each is a call to the API, so two processes see each other's
writes at once. Dict.fromName("processed-orders", { createIfMissing: true }) is lazy.
There's no Dict.get(id), since get reads a key: Dict.fromId(id).hydrate() loads one.
- Like every live object, it also has hydrate(), refresh() and raw.
| id | string | |
| name | string | |
| keyCount | number | null | How many keys it holds, as of the last load; |
| sizeBytes | number | null | The size of its keys and values as JSON. |
| usedBy | UsedBy[] | The apps that bind it. |
| region | RegionName | null | The region it keeps its data in, fixed when it was created. |
| userId | string | null | |
| createdAt | Date | null | |
| consoleUrl | string | null | This dict in the developer console (null off the hosted API). |
createstatic
static create(
name: string,
options?: CallOptions & PlacementOptions,
): Promise<Dict>Create a dict, unique by name per user (a taken name throws Conflict with existingId). region
keeps its keys there for good: us-east only for now (another, or a default elsewhere, throws
InvalidRequest).
Where it runs or keeps its data (regions()); omitted, your account's default region.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
The new dict, empty.
fromNamestatic
static fromName(
name: string,
options?: CallOptions & PlacementOptions & { createIfMissing?: boolean },
): DictA lazy reference to the dict called name; with createIfMissing it's created on first use.
Where it runs or keeps its data (regions()); omitted, your account's default region.
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A dict that loads (or is created) on first use. Nothing is sent yet.
fromIdstatic
static fromId(dictId: string, options?: CallOptions): DictA lazy reference by id; await Dict.fromId(id).hydrate() loads it now.
A dict that loads the first time you use it. Nothing is sent yet.
liststatic
static list(options?: ReadOptions & { limit?: number }): Promise<Dict[]>The current user's dicts (or those userFilter covers), newest first.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
Every matching dict, newest first, fetched page by page.
listPagestatic
static listPage(options?: ReadOptions & PageOptions): Promise<Page<Dict>>One page of dicts; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
Which users the read covers (user_id query), instead of acting as one (user).
undefined = the ambient user (asUser), null = the account itself.
The client to send with; defaults to the module client built from NOCLICK_API_KEY.
A page whose data holds the dicts and whose next_cursor is None on the last page.
get
get(key: string): Promise<T | undefined>A key's value, or undefined when it's missing or expired (a stored null reads as null).
The value as the JSON it was stored as, or default.
keys
keys(options?: DictListOptions & { limit?: number }): Promise<string[]>The keys in order (or those starting with prefix), fetched page by page.
Return at most this many.
Every matching key (or the first limit), fetched page by page.
items
items(options?: DictListOptions & { limit?: number }): Promise<DictItem[]>The keys and their values, in key order (or those starting with prefix), with each key's expiry.
Return at most this many.
A DictItem per key (or for the first limit): it unpacks as key, value and
also carries expires_at, updated_at and size_bytes.
itemsPage
itemsPage(options?: DictListOptions & PageOptions): Promise<Page<DictItem>>One page of items in key order; pass nextCursor back as cursor.
The next_cursor of the page before; omit it for the first page.
Return at most this many.
A page whose data holds DictItems and whose next_cursor is None on the last page.
put
put(key: string, value: unknown, options?: DictWriteOptions): Promise<void>Write a key. With ttlS it expires then; without, it stays until removed (and loses any expiry).
putIfAbsent
putIfAbsent(
key: string,
value: unknown,
options?: DictWriteOptions,
): Promise<boolean>Write a key only if it isn't there, atomically: of any number of callers racing, exactly
one wins. A lock (with ttlS, so a crashed holder's lock frees itself) or a run-once check.
Whether this call wrote it.
True if this call wrote it, False if the key was already there.
increment
increment(
key: string,
options?: DictWriteOptions & { by?: number },
): Promise<number>Add by (default 1, may be negative) to a counter, atomically; a missing key starts at 0.
ttlS sets its expiry only when this call creates it. The value after the increment.
1The counter's value after this increment.
update
update(
items: Readonly<Record<string, unknown>> | ReadonlyMap<string, unknown>,
options?: DictWriteOptions,
): Promise<void>Write up to 1,000 keys in one call, all or none; ttlS applies to each.
pop
pop(key: string): Promise<T | undefined>Remove a key and return its value, or undefined if it wasn't there.
The value the key held, or default.
remove
remove(key: string): Promise<boolean>Remove a key; whether it was there. (delete() deletes the whole dict.)
Whether the key was there to remove.
clear
clear(): Promise<Operation>Remove every key; the dict stays, empty. Its operation's undo() puts back what it removed.
The clear's operation: undo() puts back every key it removed that nothing has written since.
history
history(key?: string, options?: { limit?: number }): Promise<DictChange[]>Its writes of the last 30 days, newest first, each with the value it replaced; key keeps one key's.
Return at most this many.
Each change.
restoreChange
restoreChange(change: DictChange | string): Promise<void>Put the key back as change found it: the value it replaced, or gone, when the change created
the key. A value that has expired since throws Conflict.
export
export(): Promise<Operation<ExportBundle>>Export every key as it stands at one moment, as JSON Lines: one {"key", "value", "expires_at"}
per line, in key order. wait() resolves to an ExportBundle: a zip at url holding the file.
An operation whose wait() gives an ExportBundle: a zip at url holding the file.
delete
delete(): Promise<TrashItem>Delete the dict and every key in it: it goes to the trash, restorable for 30 days. A dict an
app binds throws Conflict. Returns its TrashItem: restore() puts it back, keys and all.
Its TrashItem: restore() puts it back, keys and all.
hasTypeScript only
has(key: string): Promise<boolean>Whether the key is there (and hasn't expired).
sizeTypeScript only
size(): Promise<number>How many keys it holds, read now.
DictItem
interface DictItemOne key of a dict as items() reads it: its value, when it expires (null if it doesn't),
when it was last written and the size of its value as JSON.
| key | string | |
| value | unknown | |
| expiresAt | Date | null | |
| updatedAt | Date | null | |
| sizeBytes | number | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |
DictChange
interface DictChangeOne write to a dict, from its history: op is created (the key was new), changed or deleted,
and previous the value it replaced (null for a new key). A key changed again within a minute adds
none, so a busy key keeps one a minute.
| id | string | |
| key | string | |
| op | "created" | "changed" | "deleted" | |
| previous | unknown | |
| previousExpiresAt | Date | null | |
| at | Date | null | |
| raw | JsonObject | The response JSON exactly as the API sent it. |