PowerKeys Scripting API
    Preparing search index...

    Interface WorkspaceAPI

    interface WorkspaceAPI {
        List(path?: string): Promise<WorkspaceEntry[]>;
        Stat(path: string): Promise<WorkspaceEntry | null>;
        ReadText(path: string): Promise<string>;
        WriteText(path: string, text: string): Promise<void>;
        CreateDirectory(path: string): Promise<void>;
        Delete(path: string): Promise<boolean>;
        Move(fromPath: string, toPath: string): Promise<void>;
    }
    Index
    List Stat ReadText WriteText CreateDirectory Delete Move

    • Lists the files and directories directly inside this script's workspace.

      Parameters

      • Optionalpath: string

        Workspace-relative directory to list. Omit or pass null for the workspace root.

      Returns Promise<WorkspaceEntry[]>

      Name-sorted entries directly inside the directory.

      Listing is not recursive: call List again with a subdirectory path to descend. Entries are sorted by name so repeated calls are stable. Links and reparse points are never listed, so every entry is a real file or a real directory. At most 4096 entries are returned and an over-full directory rejects rather than truncating silently, because a silently short listing would read as an empty directory. A missing or non-directory path rejects; an existing but empty directory returns an empty array.

      await HTTP.DownloadFile({ url: "https://example.com/data.json", path: "in/data.json" });
      for (const entry of await Workspace.List("in")) {
      Console.Log(`${entry.name} ${entry.isDirectory ? "dir" : entry.sizeBytes + " bytes"}`);
      }

      workspace

    • Describes one workspace entry, or resolves null when nothing is there.

      Parameters

      • path: string

        Workspace-relative path to describe.

      Returns Promise<WorkspaceEntry | null>

      The entry, or null when nothing exists at that path.

      A missing entry resolves with null rather than rejecting, so an existence check does not need a try/catch. An invalid path still rejects. A link or reparse point resolves as null, because the sandbox does not treat one as a real entry.

      const file = await Workspace.Stat("in/data.json");
      if (file !== null && !file.isDirectory) {
      Console.Log(`ready: ${file.sizeBytes} bytes`);
      }

      workspace

    • Reads a workspace file as UTF-8 text.

      Parameters

      • path: string

        Workspace-relative file to read.

      Returns Promise<string>

      The file decoded as UTF-8 text.

      Bytes are decoded as UTF-8 with malformed sequences replaced, so this never rejects on encoding. It reads at most one-eighth of the effective script heap, the same availability budget HTTP response bodies use, and rejects with limit_exceeded above it rather than growing the isolate. That budget is why binary files belong in HTTP.UploadFile, which streams them natively without ever building a JavaScript string. A missing path, a directory, or a link rejects.

      await HTTP.DownloadFile({ url: "https://example.com/feed.json", path: "feed.json" });
      const items = JSON.parse(await Workspace.ReadText("feed.json"));
      Console.Log(`${items.length} items`);

      workspace

    • Writes UTF-8 text to a workspace file, replacing any existing contents.

      Parameters

      • path: string

        Workspace-relative file to write.

      • text: string

        Text to encode as UTF-8 and store.

      Returns Promise<void>

      Resolves once the new contents are durably published.

      Missing intermediate directories in the path are created. Unlike HTTP.DownloadFile, this deliberately replaces an existing file: a script rewriting its own output should not have to delete first. The write goes to a sibling temporary file and is published atomically, so an interrupted write leaves the previous contents intact rather than a truncated file. Text is encoded as UTF-8.

      await Workspace.WriteText("out/report.csv", "name,count\nalpha,3\n");
      await HTTP.UploadFile({ url: "https://example.com/import", path: "out/report.csv" });

      workspace

    • Creates a directory inside the workspace, including missing parents.

      Parameters

      • path: string

        Workspace-relative directory to create.

      Returns Promise<void>

      Resolves once the directory exists.

      Creating a directory that already exists succeeds, so this is safe to call unconditionally. A path whose final component already exists as a file rejects instead of being treated as a directory.

      await Workspace.CreateDirectory("archive/2026");

      workspace

    • Deletes one workspace file or one empty directory.

      Parameters

      • path: string

        Workspace-relative entry to delete.

      Returns Promise<boolean>

      True when something was deleted, false when nothing was there.

      Deleting something that is not there resolves false rather than rejecting, so cleanup does not need a try/catch. A non-empty directory rejects: this deliberately has no recursive delete, so a single wrong path cannot erase a tree of user files. Delete the entries first, or leave the directory in place.

      if (await Workspace.Delete("in/data.json")) {
      Console.Log("cleaned up");
      }

      workspace

    • Moves or renames a workspace entry without overwriting anything.

      Parameters

      • fromPath: string

        Workspace-relative entry to move.

      • toPath: string

        Workspace-relative destination that must not already exist.

      Returns Promise<void>

      Resolves once the entry is at its new path.

      Both paths are workspace-relative and resolved through the same sandbox, so a move can never leave the workspace. Missing intermediate directories in the destination are created. An existing destination rejects rather than being replaced, matching HTTP.DownloadFile: delete it first if replacing is intended.

      await HTTP.DownloadFile({ url: "https://example.com/f.csv", path: "in/f.csv" });
      await Workspace.CreateDirectory("archive");
      await Workspace.Move("in/f.csv", "archive/f.csv");

      workspace

    Settings
    Member Visibility

    On This Page
    Methods