@synonymdev/pubky
    Preparing search index...

    Class SessionStorage

    Read/write storage scoped to your session (absolute paths: /pub/... or /priv/...).

    Failures reject with a PubkyError. Path validation, transport, and HTTP failures use RequestError; only HTTP errors include data.statusCode. Automatic grant refresh failures use CredentialRefreshError, with the refresh HTTP status in data.statusCode when available. URL parsing failures use InvalidInput. Other credential preparation and reading response bodies can also fail.

    Only SessionStorage.exists and SessionStorage.stats treat HTTP 404/410 as missing. Other HTTP failures, including 401/403 and 5xx, reject. Writes require write permission and can fail on directory targets (400), file/directory path conflicts (409), a path someone holds a StorageLock on (423), or exceeded quotas (507).

    Index
    • Returns void

    • Delete a file. Directory targets are unsupported.

      Parameters

      • path: Path

        File path; must not end with /.

      Returns Promise<void>

      Missing file (404), directory target (400), or shared errors (see SessionStorage).

    • DELETE the path of a lock this client holds. The lock stays in place.

      Parameters

      Returns Promise<void>

      A lock that has expired or was unlocked rejects with RequestError and status 412; take a new one. Otherwise as SessionStorage.delete.

    • Check existence with a HEAD request.

      Parameters

      Returns Promise<boolean>

      true on success; false for HTTP 404/410.

      All other failures (see SessionStorage).

    • Returns void

    • GET a streaming response for an absolute session path.

      Reading the returned response body can still fail after this resolves.

      Parameters

      Returns Promise<Response>

      A successful response with an unread body.

      Missing resource (404/410) or other request/response errors. See SessionStorage for shared errors.

    • GET bytes from an absolute session path.

      Parameters

      Returns Promise<Uint8Array<ArrayBufferLike>>

      The complete response body.

      Missing resource (404/410) or shared errors (see SessionStorage).

    • GET JSON from an absolute session path.

      Parameters

      Returns Promise<any>

      The parsed JSON value.

      Missing resource (404/410), JSON parsing/conversion failures, or shared errors (see SessionStorage).

    • GET text from an absolute session path.

      Parameters

      Returns Promise<string>

      The complete response body decoded as text.

      Missing resource (404/410) or shared errors (see SessionStorage).

    • List a directory (absolute session path).

      Parameters

      • path: Path

        Must end with /.

      • Optionalcursor: string | null

        Optional last entry (as returned) to start after.

      • Optionalreverse: boolean | null

        Default false.

      • Optionallimit: number | null

        Optional result limit.

      • Optionalshallow: boolean | null

        Default false.

      Returns Promise<string[]>

      pubky://<pk><path> entries, or an empty array for an empty page.

      Missing directory (404), invalid cursor (400), invalid response entries, or shared errors (see SessionStorage).

    • Take an exclusive write lock on a file at an absolute session path.

      The file need not exist; locking a free path reserves it. timeoutSeconds is the lifetime asked for; the homeserver caps it, and StorageLock.timeoutSeconds tells what was granted. A write made under the lock keeps it alive until the write ends, so it need not cover the upload itself.

      Parameters

      • path: Path

        File path; must not end with /.

      • timeout_seconds: number

      Returns Promise<StorageLock>

      The granted lock.

      InvalidInput for a negative, NaN or out-of-range timeout; a path that is already locked rejects with RequestError and status 423; directory targets with 400; a homeserver without lock support with 405. See SessionStorage for shared errors.

    • Upload a Blob or File without copying its contents into WASM memory.

      Parameters

      • path: Path

        File path; must not end with /.

      • body: Blob

        A Blob or File to upload.

      Returns Promise<void>

      InvalidInput if body is not a Blob or File; otherwise upload or shared write/request errors (see SessionStorage).

      await session.storage.putBlob("/pub/example.com/file.bin", file);
      
    • Upload a Blob or File to a locked path without copying its contents into WASM memory.

      Parameters

      • lock: StorageLock

        A lock you hold. The upload uses the lock's path.

      • body: Blob

        A Blob or File to upload.

      Returns Promise<void>

      An expired or released lock rejects with status 412. A file that changed since the write was prepared rejects with status 409. See SessionStorage.putBytesLocked for recovery and SessionStorage.putBlob for input validation and shared errors.

      const lock = await session.storage.lock("/pub/example.com/file.bin", 30);
      try {
      await session.storage.putBlobLocked(lock, file);
      } finally {
      await session.storage.unlock(lock);
      }
    • Create or replace a file with binary data at an absolute session path.

      Parameters

      • path: Path

        File path; must not end with /.

      • body: Uint8Array

      Returns Promise<void>

      Upload or shared write/request errors (see SessionStorage).

    • PUT binary data to the path of a lock this client holds.

      Parameters

      • lock: StorageLock

        A lock this client holds.

      • body: Uint8Array

      Returns Promise<void>

      A lock that has expired or was unlocked rejects with RequestError and status 412; take a new one and read the file again. A file that changed since the write was prepared rejects with status 409, which can happen when an earlier change the storage backend ran late lands first; read it again and retry. Otherwise as SessionStorage.putBytes.

    • Create or replace a file with JSON at an absolute session path.

      Parameters

      • path: Path

        File path (e.g. "/pub/app/data.json"); must not end with /.

      • body: any

        JSON-serializable value.

      Returns Promise<void>

      InvalidInput if body cannot be converted to JSON; otherwise serialization, upload, or shared write/request errors (see SessionStorage).

    • Create or replace a file with text at an absolute session path.

      Parameters

      • path: Path

        File path; must not end with /.

      • body: string

      Returns Promise<void>

      Upload or shared write/request errors (see SessionStorage).

    • PUT text to the path of a lock this client holds.

      Parameters

      • lock: StorageLock

        A lock this client holds.

      • body: string

      Returns Promise<void>

      A lock that has expired or was unlocked rejects with RequestError and status 412; take a new one and read the file again. A file that changed since the write was prepared rejects with status 409, which can happen when an earlier change the storage backend ran late lands first; read it again and retry. Otherwise as SessionStorage.putText.

    • Restart the lifetime of a lock this client holds.

      On success the lock carries the newly granted StorageLock.timeoutSeconds.

      Parameters

      • lock: StorageLock

        A lock this client holds.

      • timeout_seconds: number

      Returns Promise<void>

      A lock that has expired or was unlocked rejects with RequestError and status 412; take a new one and read the file again. InvalidInput for a negative, NaN or out-of-range timeout. See SessionStorage for shared errors.

    • Get metadata for an absolute, session-scoped path (e.g. "/pub/app/file.json").

      On success, missing or unparseable metadata headers leave their properties absent.

      Parameters

      • path: Path

        Absolute path under your user (starts with /).

      Returns Promise<ResourceStats | undefined>

      Metadata on success; undefined for HTTP 404/410.

      All other failures (see SessionStorage).

    • Release a lock this client holds.

      Parameters

      Returns Promise<void>

      A lock that no longer exists rejects with RequestError and status 409. See SessionStorage for shared errors.