GCSStore — Google Cloud Storage

GCSStore — Google Cloud Storage Overview GCSStore is a store for Google Cloud Storage, Google's object storage service. GCS is an object store, not a SQL database: it has no query language, no joins, and no ad hoc WHERE-clause filtering. Data lives as immutable objects (blobs) addressed by (bucket, key). Because that shape does not fit the SQL-oriented Dialect interface, GCSStore instead implements the minimal NoSqlStore marker interface (src/nosql/store.ts) and exposes GCS's own object-level operations directly. Key facts (from src/nosql/gcs/index.ts): Implements NoSqlStore — connection lifecycle (connect/disconnect/isConnected) plus a getClient() escape hatch. There is no query(sql). name = 'gcs' library = '@google-cloud/storage' The @google-cloud/storage SDK is a soft/optional dependency. It is loaded lazily inside connect() via require('@google-cloud/storage') rather than imported at the module top level, so importing this file never pulls in the SDK. Supports an injected client option: a pre-built Storage instance can be supplied via the client option. When provided, connect() uses it as-is and skips the require entirely. This is primarily an injection seam for tests, but is also useful for sharing a client or supplying custom constructor options. Options Connection Real client Construct with connection options, then call connect(). On connect() the store lazy-loads the driver and builds a Storage client from projectId and keyFilename: If projectId/keyFilename are omitted, the underlying SDK falls back to Application Default Credentials and the ambient project. If loading the SDK or constructing the client fails, connect() throws a ConnectionError (with database: 'gcs' and the original error attached as parent), and leaves the store disconnected. Injected client Supply a pre-built Storage instance via client. connect() then uses it directly and never calls require('@google-cloud/storage'): Lifecycle notes connect() is idempotent: if already connected with a live client, a second call is a no-op. disconnect() simply drops the client reference and marks the store disconnected. The GCS client is stateless (HTTP-based) with nothing to close. isConnected() returns true only while connected with a non-null client. Any object operation (or getClient()) invoked while disconnected throws a ConnectionError telling you to call connect() first. Methods All object operations resolve a File handle through the driver's client.bucket(bucket).file(key) chain (list uses client.bucket(bucket).getFiles(...)). Driver failures are wrapped in a DatabaseError via DatabaseError.from(...) with a descriptive message; connection failures surface as ConnectionError. Lifecycle uploadObject Uploads (or overwrites) an object. Calls bucket(bucket).file(key).save(data, options). data may be a Buffer or a string. options is passed straight through to the driver's file.save() (e.g. { contentType, metadata, resumable }) and defaults to {} when omitted. A save() failure is wrapped in DatabaseError. downloadObject Downloads an object's contents. Calls file.download(), which returns a [contents] tuple from the driver; the store unwraps the tuple and returns the Buffer directly. Throws (wrapped in DatabaseError) if the object does not exist. deleteObject Deletes an object. Calls file.delete(). Throws (wrapped in DatabaseError) if the object does not exist. objectExists Returns whether an object exists. Calls file.exists(), which returns a [exists] tuple; the store unwraps the tuple and returns the boolean. Errors from the driver (e.g. permission denied) are wrapped in DatabaseError. listObjects Lists objects in a bucket, optionally restricted to those whose name starts with prefix. Calls bucket(bucket).getFiles({ prefix }) (the prefix key is always passed, undefined when omitted) and unwraps the returned [files] tuple, returning files ?? [] — the raw File objects from the driver. A getFiles() failure is wrapped in DatabaseError. getMetadata Fetches an object's metadata (size, contentType, updated, custom metadata, etc). Calls file.getMetadata() and unwraps the returned [metadata] tuple. A failure is wrapped in DatabaseError. Example Verification status Unit / mock-verified only. The tests in tests/nosql/gcs.test.ts are pure unit tests: The real @google-cloud/storage package is not installed and is never loaded. Every test injects a hand-built mock Storage instance via the client option, so connect() uses it directly and skips the require. There is no network access — no real GCS buckets, credentials, or API calls are exercised. The tests assert the driver call shapes (bucket(name).file(key).<op>(...), getFiles({ prefix })), tuple unwrapping for download/exists/getMetadata/listObjects, option defaulting, DatabaseError wrapping of driver failures, ConnectionError when disconnected, and the connection lifecycle (idempotent connect, clean disconnect, name/library values). Behavior against a live GCS backend has not been verified here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories