Interface: IStorageApi
Defined in: Extensions/ExtensionApiTypes.ts:458
Backed by the extension_storage SQLite table. The host auto-prefixes the
extension ID; extensions cannot read each other's keys.
Quotas:
- KV tier: default 5 MB per extension. Exceeding throws
QuotaExceededError. Configurable in Preferences. - Database tier: no hard quota by default — extensions that opt in via
storage:databaseare expected to need real space (indexes, embeddings, custom corpora). The Extensions UI shows per-extension disk usage and lets the user set a per-extension cap if desired. - Secrets: no quota; OS keychain limits apply.
Properties
onDidChangeSettings
onDidChangeSettings:
IEventApi<{keys:string[]; }>
Defined in: Extensions/ExtensionApiTypes.ts:478
Methods
delete()
delete(
key):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:462
Parameters
key
string
Returns
Promise<void>
deleteFile()
deleteFile(
path):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:541
Delete a file inside the granted folder. No-op if the file does not
exist. Requires fs:managed-folder.
Parameters
path
string
Returns
Promise<void>
deleteSecret()
deleteSecret(
key):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:469
Parameters
key
string
Returns
Promise<void>
diskUsage()
diskUsage():
Promise<{databases:number;kv:number;secretsCount:number; }>
Defined in: Extensions/ExtensionApiTypes.ts:498
Approximate disk usage of all storage owned by this extension, in bytes.
Returns
Promise<{ databases: number; kv: number; secretsCount: number; }>
get()
get<
T>(key):Promise<T|undefined>
Defined in: Extensions/ExtensionApiTypes.ts:460
Type Parameters
T
T = unknown
Parameters
key
string
Returns
Promise<T | undefined>
getFolderGrant()
getFolderGrant():
Promise<FolderGrantHandle|null>
Defined in: Extensions/ExtensionApiTypes.ts:516
Get the current folder grant, if one exists. Returns null if no grant
has been made or if it was revoked. Requires fs:managed-folder.
Returns
Promise<FolderGrantHandle | null>
getFolderUsage()
getFolderUsage():
Promise<FolderUsageInfo>
Defined in: Extensions/ExtensionApiTypes.ts:559
Get aggregate disk usage for the granted folder. Requires
fs:managed-folder.
Returns
Promise<FolderUsageInfo>
getSecret()
getSecret(
key):Promise<string|undefined>
Defined in: Extensions/ExtensionApiTypes.ts:468
Parameters
key
string
Returns
Promise<string | undefined>
getSetting()
getSetting<
T>(key):Promise<T|undefined>
Defined in: Extensions/ExtensionApiTypes.ts:477
Read a user-edited setting defined in contributes.configuration. The
host populates these from the rendered settings form. Equivalent to
get('__settings.<key>') but type-safe against the schema.
Type Parameters
T
T = unknown
Parameters
key
string
Returns
Promise<T | undefined>
keys()
keys():
Promise<string[]>
Defined in: Extensions/ExtensionApiTypes.ts:463
Returns
Promise<string[]>
listFiles()
listFiles(
prefix?):Promise<FileInfo[]>
Defined in: Extensions/ExtensionApiTypes.ts:547
List files and directories inside the granted folder, optionally
filtered by a relative path prefix. Requires fs:managed-folder.
Parameters
prefix?
string
Returns
Promise<FileInfo[]>
openDatabase()
openDatabase(
name,opts?):Promise<IExtensionDatabase>
Defined in: Extensions/ExtensionApiTypes.ts:492
Open a SQLite database file owned by this extension. The file lives at
data/extensions/<id>/db/<name>.db. Use this for indexes, embeddings,
or any data that exceeds the KV tier. Requires the storage:database
permission. The host opens the file with WAL mode and foreign keys on.
The database is created on first open. The host runs no migrations —
the extension is responsible for its own schema. The host backs the
file up with the rest of user data unless the extension marks it
ephemeral via opts.
Parameters
name
string
opts?
Returns
Promise<IExtensionDatabase>
readFile()
readFile(
path):Promise<ArrayBuffer>
Defined in: Extensions/ExtensionApiTypes.ts:528
Read a file inside the granted folder. The path is relative to the
grant root and must not escape it. Requires fs:managed-folder.
Parameters
path
string
Returns
Promise<ArrayBuffer>
requestFolder()
requestFolder(
purpose):Promise<FolderGrantHandle|null>
Defined in: Extensions/ExtensionApiTypes.ts:510
Request a user-chosen folder for scoped file storage. The host opens a
folder picker dialog; if the user selects a folder the grant is persisted
so it survives extension restarts. Returns null if the user cancelled.
Requires the fs:managed-folder permission.
Parameters
purpose
string
Human-readable reason shown in the folder picker dialog.
Returns
Promise<FolderGrantHandle | null>
revokeFolderGrant()
revokeFolderGrant():
Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:522
Revoke the current folder grant. The files on disk are NOT deleted — only
the extension's access is removed. Requires fs:managed-folder.
Returns
Promise<void>
set()
set(
key,value):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:461
Parameters
key
string
value
unknown
Returns
Promise<void>
setSecret()
setSecret(
key,value):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:467
Routes through the OS keychain (keytar) for sensitive values.
Parameters
key
string
value
string
Returns
Promise<void>
statFile()
statFile(
path):Promise<FileInfo|null>
Defined in: Extensions/ExtensionApiTypes.ts:553
Get metadata for a single file inside the granted folder. Returns null
if the file does not exist. Requires fs:managed-folder.
Parameters
path
string
Returns
Promise<FileInfo | null>
writeFile()
writeFile(
path,data):Promise<void>
Defined in: Extensions/ExtensionApiTypes.ts:535
Write (or overwrite) a file inside the granted folder. The path is
relative to the grant root. Parent directories are created automatically.
Requires fs:managed-folder.
Parameters
path
string
data
ArrayBuffer | Uint8Array<ArrayBufferLike>
Returns
Promise<void>