Interfaces
Bucket
A storage bucket handle implemented by both local and remote sandbox paths. Only the documented subset is supported.
Properties
Methods
deleteFiles()
deleteFiles(query?: DeleteFilesOptions): Promise<void>;
Delete every file getFiles(query) would list across its pages. With
force, a failed delete does not stop the others, and the call rejects
with the array of errors.
Parameters
| Parameter | Type |
|---|---|
query? | DeleteFilesOptions |
Returns
Promise<void>
file()
file(path: string): File;
Get a File handle for path. The file may or may not exist.
Parameters
| Parameter | Type |
|---|---|
path | string |
Returns
getFiles()
getFiles(query?: GetFilesOptions): Promise<GetFilesResponse<File>>;
List the bucket’s files, as @google-cloud/storage does: names starting
with prefix, rolled up at delimiter, paged by maxResults and
pageToken. Resolves [files, nextQuery, apiResponse]; see get-files.ts.
Parameters
| Parameter | Type |
|---|---|
query? | GetFilesOptions |
Returns
Promise<GetFilesResponse<File>>
CopyOptions
Options bag for File.copy. Subset of @google-cloud/storage’s CopyOptions.
Properties
CreateResumableUploadOptions
Options bag for File.createResumableUpload. Subset of @google-cloud/storage’s CreateResumableUploadOptions.
Properties
| Property | Type | Description |
|---|---|---|
metadata? | Record<string, unknown> | The object’s metadata, as SaveOptions.metadata takes it. |
origin? | string | The page origin whose cross-origin requests the session URL answers. |
CreateWriteStreamOptions
Options bag for File.createWriteStream. Subset of @google-cloud/storage’s CreateWriteStreamOptions.
Properties
| Property | Type | Description |
|---|---|---|
contentType? | string | Content type stored on the file. |
metadata? | Record<string, unknown> | Stored alongside the file, as SaveOptions.metadata is. |
DeleteFilesOptions
Options for Bucket.deleteFiles. Subset of @google-cloud/storage’s DeleteFilesOptions.
Extends
Properties
DownloadOptions
Options bag for File.download. Subset of @google-cloud/storage’s DownloadOptions.
Properties
| Property | Type | Description |
|---|---|---|
end? | number | Last byte to read, inclusive. |
start? | number | First byte to read, inclusive. |
validation? | boolean | "md5" | "crc32c" | The sandbox accepts but ignores validation. |
File
A file handle within a bucket. Method shapes mirror
@google-cloud/storage’s File (return tuples for download / exists
/ getSignedUrl, etc.) so common consumer code retains the familiar shape.
The sandbox backend implements the methods documented here. Any
other File method from @google-cloud/storage (copy, move,
setMetadata beyond the basic save options, etc.) is not implemented
on the sandbox path — see module header.
Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
bucket | readonly | Bucket | Bucket the file belongs to. Same handle the file() call came from. |
name | readonly | string | Name (path) of the file within its bucket. |
Methods
copy()
copy(destination: CopyDestination, options?: CopyOptions): Promise<[File, FileMetadata]>;
Copy the object, with its content type, custom metadata and download
tokens, to destination: a path in this bucket, a gs:// URL, another
Bucket (same path), or another File. options change the
copy’s metadata; a custom key set to null is left off the copy.
Resolves [copy, copyMetadata].
Parameters
| Parameter | Type |
|---|---|
destination | CopyDestination |
options? | CopyOptions |
Returns
Promise<[File, FileMetadata]>
createReadStream()
createReadStream(options?: DownloadOptions): Readable;
A readable stream of the file’s bytes, or of the inclusive range
start..end. A missing file surfaces as the stream’s error.
Parameters
| Parameter | Type |
|---|---|
options? | DownloadOptions |
Returns
Readable
createResumableUpload()
createResumableUpload(options?: CreateResumableUploadOptions): Promise<[string]>;
@google-cloud/storage’s resumable upload session: a URL that takes the
object’s bytes from a browser, and creates the object with
options.metadata when the last byte arrives. A remote sandbox whose host
serves HTTP (the hosted dev server) gives one. In process, and on a
browser tab’s SharedWorker host, there is no HTTP host to take the bytes,
so this rejects with a not-implemented error there.
Parameters
| Parameter | Type |
|---|---|
options? | CreateResumableUploadOptions |
Returns
Promise<[string]>
createWriteStream()
createWriteStream(options?: CreateWriteStreamOptions): Writable;
A writable stream whose bytes replace the file’s content once the stream finishes, as File.save does.
Parameters
| Parameter | Type |
|---|---|
options? | CreateWriteStreamOptions |
Returns
Writable
delete()
delete(): Promise<void>;
Remove the file from its bucket. Idempotent — deleting a missing
file is a no-op (matches @google-cloud/storage’s
ignoreNotFound: true, which is the only mode the sandbox models).
Returns
Promise<void>
download()
download(options?: DownloadOptions): Promise<[Buffer<ArrayBufferLike>]>;
Read the file’s bytes, or the inclusive range start..end of them.
Returns a [Buffer] tuple to mirror @google-cloud/storage’s
File.download (which returns [Buffer, ...]). Throws if the file
does not exist.
Parameters
| Parameter | Type |
|---|---|
options? | DownloadOptions |
Returns
Promise<[Buffer<ArrayBufferLike>]>
exists()
exists(): Promise<[boolean]>;
[true] if the file exists, [false] otherwise. Tuple shape mirrors @google-cloud/storage.
Returns
Promise<[boolean]>
getMetadata()
getMetadata(): Promise<[FileMetadata]>;
The file’s metadata, as a [metadata] tuple. Throws if the file does not exist.
Returns
Promise<[FileMetadata]>
getSignedUrl()
getSignedUrl(options: GetSignedUrlOptions): Promise<[string]>;
Return a stub signed URL of the form
pyric-sandbox-storage://${path}?expires=${expires}. The sandbox
does NOT serve the URL — it’s a deterministic placeholder so
agent code that round-trips signed URLs (logs, fixtures, replay)
sees a stable shape.
Parameters
| Parameter | Type |
|---|---|
options | GetSignedUrlOptions |
Returns
Promise<[string]>
save()
save(data: string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike>, options?: SaveOptions): Promise<void>;
Persist data at this file’s path. Replaces any existing content
(no append semantics). options.metadata is stored alongside the
bytes and surfaces on later reads via the in-memory state — the
sandbox doesn’t expose a full Metadata API yet, but the payload
round-trips so future expansion is non-breaking.
Parameters
| Parameter | Type |
|---|---|
data | string | Buffer<ArrayBufferLike> | Uint8Array<ArrayBufferLike> |
options? | SaveOptions |
Returns
Promise<void>
setMetadata()
setMetadata(metadata: FileMetadataUpdate): Promise<[FileMetadata]>;
Change the file’s metadata: the named settable fields, and the custom
keys under metadata, where null removes a key and the others stay.
Removing firebaseStorageDownloadTokens revokes the file’s download URL.
Parameters
| Parameter | Type |
|---|---|
metadata | FileMetadataUpdate |
Returns
Promise<[FileMetadata]>
FileMetadata
A file’s metadata. Subset of @google-cloud/storage’s FileMetadata.
Properties
GetFilesApiResponse
The JSON API response a page came from. The sandbox leaves out items, the objects’ full metadata.
Properties
GetFilesOptions
Options for Bucket.getFiles. Subset of @google-cloud/storage’s GetFilesOptions.
Extended by
Properties
GetSignedUrlOptions
Options bag for File.getSignedUrl. Mirrors @google-cloud/storage’s shape.
Properties
SaveOptions
Options bag for File.save. Subset of @google-cloud/storage’s SaveOptions.
Properties
| Property | Type | Description |
|---|---|---|
contentType? | string | Content type hint stored on the sandbox entry. Convenience shortcut for metadata.contentType. |
metadata? | Record<string, unknown> | Metadata stored alongside the file: the settable fields setMetadata takes, and custom keys under metadata. A firebaseStorageDownloadTokens custom key sets the file’s download tokens. Other fields are ignored. Read it back with File.getMetadata. |
resumable? | boolean | How @google-cloud/storage sends the bytes. The sandbox stores the object in one write either way, so the stored object is the same. |
Storage
pyric-admin/storage’s sandbox Storage handle. It exposes the subset
documented in the module header.
The shared bucket(name?) shape is the contract — consumers code
against it without caring whether the local or remote sandbox is live.
Methods
bucket()
bucket(name?: string): Bucket;
Get a Bucket handle. When name is omitted, returns the
sandbox default bucket ('pyric-default').
Parameters
| Parameter | Type |
|---|---|
name? | string |
Returns
Type Aliases
CopyDestination
type CopyDestination = string | Bucket | File;
Where File.copy copies to.
CreateReadStreamOptions
type CreateReadStreamOptions = DownloadOptions;
Options bag for File.createReadStream. Subset of @google-cloud/storage’s CreateReadStreamOptions.
FileMetadataUpdate
type FileMetadataUpdate = Partial<Pick<FileMetadata, SettableField>> & {
metadata?: Record<string, string | number | boolean | null>;
};
What File.setMetadata takes. Subset of @google-cloud/storage’s FileMetadata.
Type Declaration
metadata?
optional metadata: Record<string, string | number | boolean | null>;
Custom keys to set; null removes a key. Values are stored as strings.
GetFilesResponse
type GetFilesResponse<F> = [F[], GetFilesOptions | null, GetFilesApiResponse];
Type Parameters
| Type Parameter |
|---|
F |
StorageApp
type StorageApp = PyricAdminApp;
Input accepted by getStorage. The branded PyricAdminApp is
the canonical shape; calling without an argument resolves the default
app from the pyric-admin/app registry (mirroring
firebase-admin/storage, where getStorage() resolves the default App),
and throws the captured app/no-app error when nothing is initialized.
Functions
getDownloadURL()
function getDownloadURL(file: File): Promise<string>;
Mirror of firebase-admin/storage’s getDownloadURL(file). A file without
a download token gets one in firebaseStorageDownloadTokens, as production
mints it. On the Node host the URL is its HTTP byte route URL, which serves
ranges and stops working when the token is removed. In process and on a
SharedWorker host there is no HTTP origin, so the URL is a data: URI that
carries the bytes.
Parameters
| Parameter | Type |
|---|---|
file | File |
Returns
Promise<string>
getStorage()
function getStorage(app?: SandboxAdminApp): Storage;
Get the Storage service for the given app.
Returns a sandbox-backed Storage whose state
lives on the Sandbox. sandbox.reset() wipes it.
Parameters
| Parameter | Type |
|---|---|
app? | SandboxAdminApp |