google-cloud 0.0.1-preview.1
Google Cloud clients: Firestore, Cloud Storage, Cloud DNS and Cloud KMS
google-cloud#
Google Cloud client libraries for Zena, built on wasi:http and @zena/protobuf so they compile for WebAssembly component targets as well as the zena CLI host.
Installation#
zena pkg add @zena/google-cloud
Libraries#
google-cloud/firestore— Firestore document, collection, query, batch, and transaction client.google-cloud/storage— Cloud Storage client for reading, writing, stating, and deleting objects.google-cloud/dns— Cloud DNS client for managing record sets in a managed zone.google-cloud/kms— Cloud KMS client for asymmetric signing and symmetric encryption/decryption.google-cloud/auth— Default credentials and project ID discovery from the GCE metadata server or environment variables.google-cloud/firestore-v1andgoogle-cloud/storage-v2— Generated protobuf messages and low-level service clients forgoogle.firestore.v1andgoogle.storage.v2.google-cloud/testing/fake-kmsandgoogle-cloud/testing/firestore-emulator— Test helpers for in-process fake Cloud KMS and the Firestore emulator.
Firestore#
import { Direction, Fields, Firestore, Operator, integerValue } from 'google-cloud/firestore';
let db = await Firestore.connect();
let post = db.collection('posts').doc('hello');
await post.set(new Fields().string('title', 'Hello').integer('views', 0));
let snapshot = await post.get();
if (let (true, views) = snapshot.getInteger('views')) {
await post.update(new Fields().integer('views', views + 1));
}
let popular = await db.collection('posts')
.where('views', Operator.GreaterThan, integerValue(100))
.orderBy('views', Direction.Descending)
.limit(10)
.get();
for (let p in popular) {
console.log(p.id);
}
Firestore.connect() discovers the project and credentials as described under Credentials and talks gRPC to the API. new Firestore({projectId, databaseId?, transport}) accepts explicit configuration instead.
- References:
db.collection(path),db.doc(path),collection.doc(id),doc.collection(id).collection.add(fields)creates a document with a random ID. - Writes:
setreplaces a document,createfails withALREADY_EXISTSwhen it exists,updatesets the named top-level fields and fails withNOT_FOUNDwhen it does not exist, anddeleteremoves it. Errors areRpcErrors carrying thegoogle.rpc.Code. - Transforms (applied by the server when the write commits):
Fields.serverTimestamp,increment,incrementDouble,maximum,minimum,arrayUnion, andarrayRemove. In anupdate,deleteFieldremoves a field. They apply to top-level fields and work in batches and transactions as well:post.update(new Fields().increment('views', 1).serverTimestamp('seen')). - Reads:
get()returns aDocumentSnapshot, whoseexistsisfalsefor a missing document.getString,getInteger,getDouble, andgetBooleantake a field path such asauthor.nameand return(true, value)or(false, _)when the field is absent or of another type.get(path)returns the rawValue.db.getAll(refs)reads several documents in one call in the order given. - Queries:
where,orderBy,limit,offset, andselecteach return a new query.get()collects the results;stream()yields each document as it arrives (for await);count()counts them on the server. - Cursors:
startAt,startAfter,endAt, andendBeforetake values for the orderings or aDocumentSnapshot. - Batches & Transactions:
db.batch()collects writes and commits them in one call.db.runTransaction(body)runsbodywith aTransaction, retrying up to five times on contention and rolling back ifbodythrows. - Deadlines:
Firestore.connect({timeout: milliseconds(10000)})gives each call a deadline, failing withDEADLINE_EXCEEDEDif exceeded.
let total = await db.runTransaction<i64>(async (tx: Transaction): Future<i64> => {
let counter = db.doc('counters/visits');
let snapshot = await tx.get(counter);
var n: i64 = 0;
if (let (true, stored) = snapshot.getInteger('n')) {
n = stored;
}
tx.set(counter, new Fields().integer('n', n + 1));
return n + 1;
});
Transports & Emulator#
Firestore.connect()uses gRPC (protobuf/grpc) over HTTP/2. WhenFIRESTORE_EMULATOR_HOSTis set tohost:port,Firestore.connect()connects to the Firestore emulator over cleartext HTTP/2 with theownertoken.Firestore.connectFallback()uses Google's gRPC fallback protocol (protobuf/fallback), which works on HTTP/1.1-onlywasi:httphosts such as stockwasmtime serve.new Firestore({projectId, transport})accepts anyProtoTransport.
Cloud Storage#
import { Storage } from 'google-cloud/storage';
let bucket = Storage.connect().bucket('my-bucket');
await bucket.write('notes/hello.txt', bytes, 'text/plain');
let read = await bucket.read('notes/hello.txt'); // null when absent
let object = await bucket.stat('notes/hello.txt'); // metadata, or null
await bucket.delete('notes/hello.txt'); // true if deleted
Storage.connect() uses the default credentials and talks gRPC to the Cloud Storage API (write streams data in chunks of at most 2 MiB). new Storage(transport) accepts any ProtoTransport, and storage.client exposes the generated StorageClient.
Cloud DNS#
import { CloudDns, RecordSet } from 'google-cloud/dns';
let zone = CloudDns.connect('my-project', 'my-zone');
await zone.put(new RecordSet('_atproto.alice.example.com.', 'TXT', 300, ['"did=did:plc:..."']));
let set = await zone.get('_atproto.alice.example.com.', 'TXT'); // null when absent
await zone.delete('_atproto.alice.example.com.', 'TXT'); // true if deleted
CloudDns uses the Cloud DNS REST API (https://dns.googleapis.com/dns/v1) with default credentials. Names are fully qualified (ending in a .), and put creates or replaces the record set of that name and type.
Cloud KMS#
import { sha256 } from 'zena:crypto';
import { CloudKms, ecPointFromPem } from 'google-cloud/kms';
// Asymmetric signing
let signingKey = CloudKms.connect(
'projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1'
);
let derSignature = await signingKey.asymmetricSign(sha256(message));
let pubKey = await signingKey.publicKey();
let uncompressedPoint = ecPointFromPem(pubKey.pem);
// Symmetric encryption (AEAD)
let symmetricKey = CloudKms.connect('projects/p/locations/l/keyRings/r/cryptoKeys/s');
let ciphertext = await symmetricKey.encrypt(plaintext, additionalData);
let decrypted = await symmetricKey.decrypt(ciphertext, additionalData);
Credentials#
defaultCredentials() (google-cloud/auth):
GOOGLE_OAUTH_ACCESS_TOKEN, when set in the environment, is used directly (for local runs:GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)).- Otherwise, the GCE metadata server (at
GCE_METADATA_HOSTwhen set, ormetadata.google.internal) supplies tokens for the default service account, caching each token until a minute before it expires.
defaultProjectId() reads GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT when set, falling back to the metadata server.
License#
MIT
Copyright 2025 Justin Fagnani-Bell
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the “Software”), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- protobuf protobuf.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 |
|
|