This page is generated from the authoritative declaration file. Do not edit it by hand. Contract SHA-256:
152c7fab547f.SettingValue, SettingDef, SettingOption, SettingAttrs, SettingsHandle, StorageUsage, StorageHandle.
Download the complete contract from the docs source: TypeScript declaration.
Contract
// ─── settingsHandle.ts ───────────────────────────────────────────
/** @knipIgnoreUnusedButUsedByCustomNodes */
export type SettingValue = string | number | boolean | readonly string[]
/** @knipIgnoreUnusedButUsedByCustomNodes */
export interface SettingDef {
/**
* Namespaced, by convention `<Pack>.<name>` — it shares one space with core
* and every other pack, and it is what the value is stored under forever.
*/
readonly id: string
readonly name: string
/**
* Which control the panel shows. Every one of these is declarative — the
* host renders it.
*
* A pack-supplied renderer is deliberately absent. Core's own setting type
* accepts a function that is handed the value and a setter and returns an
* element; publishing that would put packs in charge of the settings
* panel's markup, which is the thing that cannot then be restyled. Packs
* that needed a colour or a file were falling back to a text field the user
* pasted into, so the gap was the missing *types*, not a missing slot.
*/
readonly type:
| 'boolean'
| 'number'
| 'slider'
| 'knob'
| 'combo'
| 'radio'
| 'text'
| 'password'
| 'color'
| 'image'
| 'url'
readonly defaultValue: SettingValue
readonly tooltip?: string
/** Panel grouping. Defaults to the id split on dots. */
readonly category?: readonly string[]
/**
* Choices for `combo` and `radio`.
*
* A bare string is both the stored value and the label. Use the pair form
* when they differ — several packs store a semantic number and show words
* for it (`0` = off, `1` = selected, `2` = all), and comparing those
* numerically is the whole point. Flattening them to strings silently
* re-types every user's saved choice.
*/
readonly options?: readonly SettingOption[]
/**
* Bounds for `number` and `slider`. Without these a slider has no range to
* draw and packs fall back to a plain text box.
*/
readonly attrs?: SettingAttrs
readonly onChange?: (value: SettingValue, previous?: SettingValue) => void
}
/** @knipIgnoreUnusedButUsedByCustomNodes */
export type SettingOption =
| string
| { readonly value: string | number; readonly label: string }
/** @knipIgnoreUnusedButUsedByCustomNodes */
export interface SettingAttrs {
readonly min?: number
readonly max?: number
readonly step?: number
}
export interface SettingsHandle {
/**
* Registers a setting. Call once, at extension load: a value already stored
* for this id survives, so re-declaring cannot reset a user's choice.
*/
declare(def: SettingDef): void
get<T extends SettingValue = SettingValue>(id: string): T | undefined
set(id: string, value: SettingValue): Promise<void>
/**
* Watches a setting, including one the pack did not declare.
*
* `declare`'s own `onChange` only fires for settings the pack owns, so a
* pack that needs to react to a *core* preference — colour palette, link
* render mode, locale — had nothing to observe and polled or ignored it.
*
* Fires on change only, not on registration. Returns a function that stops
* watching; call it from wherever the pack tears down.
*/
onChange<T extends SettingValue = SettingValue>(
id: string,
listener: (value: T | undefined, previous: T | undefined) => void
): Unsubscribe
}
// ─── storageHandle.ts ────────────────────────────────────────────
/** @knipIgnoreUnusedButUsedByCustomNodes */
export interface StorageUsage {
/** Total bytes stored under the namespace. */
readonly usedBytes: number
/** How many entries make up {@link usedBytes}. */
readonly entryCount: number
/**
* The ceiling this host enforces, or `undefined` where it enforces none.
*
* Undefined is the honest answer for a local install with the user's own
* disk behind it, and it is deliberately not reported as `Infinity`: a pack
* dividing by it to draw a gauge would get a meaningless bar rather than the
* chance to skip drawing one. Do not treat a present number as a promise
* that a write below it succeeds — another namespace shares the same store.
*/
readonly quotaBytes?: number
}
export interface StorageHandle {
/**
* Names stored under a namespace, which must be one this pack owns.
*
* Empty when nothing has been stored yet — absence is not an error.
*/
list(namespace: string): Promise<readonly string[]>
/** The stored text, or `undefined` if there is none. */
get(name: string): Promise<string | undefined>
set(name: string, value: string): Promise<void>
remove(name: string): Promise<void>
/**
* What a namespace currently occupies.
*
* For a pack that stores things a user accumulates — presets, captions,
* saved prompts — so it can show what it is holding and offer to prune it,
* rather than growing without bound until someone else's write fails.
*/
usage(namespace: string): Promise<StorageUsage>
}