Navigate

API reference

pyric-admin/storage

20 published symbols from pyric-admin

Generated from the TypeScript declarations shipped at this import path.

Check behavioral conformance

Interfaces

Bucket

A storage bucket handle implemented by both local and remote sandbox paths. Only the documented subset is supported.

Properties

PropertyModifierTypeDescription
namereadonlystringName of the bucket. Stable across file() lookups.

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
ParameterType
query?DeleteFilesOptions
Returns

Promise<void>

file()
file(path: string): File;

Get a File handle for path. The file may or may not exist.

Parameters
ParameterType
pathstring
Returns

File

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
ParameterType
query?GetFilesOptions
Returns

Promise<GetFilesResponse<File>>


CopyOptions

Options bag for File.copy. Subset of @google-cloud/storage’s CopyOptions.

Properties

PropertyTypeDescription
cacheControl?string-
contentDisposition?string-
contentEncoding?string-
contentLanguage?string-
contentType?string-
metadata?Record<string, string | number | boolean | null>Custom keys for the copy, merged over the source’s; null leaves a key off.

CreateResumableUploadOptions

Options bag for File.createResumableUpload. Subset of @google-cloud/storage’s CreateResumableUploadOptions.

Properties

PropertyTypeDescription
metadata?Record<string, unknown>The object’s metadata, as SaveOptions.metadata takes it.
origin?stringThe page origin whose cross-origin requests the session URL answers.

CreateWriteStreamOptions

Options bag for File.createWriteStream. Subset of @google-cloud/storage’s CreateWriteStreamOptions.

Properties

PropertyTypeDescription
contentType?stringContent 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

PropertyTypeDescription
autoPaginate?boolean-
delimiter?string-
force?booleanDelete every file it can, then reject with the array of errors, instead of stopping at the first.
maxResults?number-
pageToken?string-
prefix?string-

DownloadOptions

Options bag for File.download. Subset of @google-cloud/storage’s DownloadOptions.

Properties

PropertyTypeDescription
end?numberLast byte to read, inclusive.
start?numberFirst 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

PropertyModifierTypeDescription
bucketreadonlyBucketBucket the file belongs to. Same handle the file() call came from.
namereadonlystringName (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
ParameterType
destinationCopyDestination
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
ParameterType
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
ParameterType
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
ParameterType
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
ParameterType
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
ParameterType
optionsGetSignedUrlOptions
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
ParameterType
datastring | 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
ParameterType
metadataFileMetadataUpdate
Returns

Promise<[FileMetadata]>


FileMetadata

A file’s metadata. Subset of @google-cloud/storage’s FileMetadata.

Properties

PropertyTypeDescription
bucketstring-
cacheControl?string-
contentDisposition?string-
contentEncoding?string-
contentLanguage?string-
contentType?string-
generationstring-
md5Hash?string-
metadata?Record<string, string>Custom metadata, including firebaseStorageDownloadTokens once the file has a download URL. Absent when there is none.
metagenerationstring-
namestring-
sizestringSize in bytes, as a decimal string.
timeCreatedstring-
updatedstring-

GetFilesApiResponse

The JSON API response a page came from. The sandbox leaves out items, the objects’ full metadata.

Properties

PropertyType
kind"storage#objects"
nextPageToken?string
prefixes?string[]

GetFilesOptions

Options for Bucket.getFiles. Subset of @google-cloud/storage’s GetFilesOptions.

Extended by

Properties

PropertyType
autoPaginate?boolean
delimiter?string
maxResults?number
pageToken?string
prefix?string

GetSignedUrlOptions

Options bag for File.getSignedUrl. Mirrors @google-cloud/storage’s shape.

Properties

PropertyTypeDescription
action"read" | "write" | "delete" | "resumable"`‘read'
expiresstring | number | DateExpiration. Accepts ms-since-epoch (number), ISO date string, or Date. Sandbox normalizes to ms-since-epoch and embeds in the stub URL’s expires= query.

SaveOptions

Options bag for File.save. Subset of @google-cloud/storage’s SaveOptions.

Properties

PropertyTypeDescription
contentType?stringContent 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?booleanHow @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
ParameterType
name?string
Returns

Bucket

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

ParameterType
fileFile

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

ParameterType
app?SandboxAdminApp

Returns

Storage