feat(storage): add Object Contexts samples and system tests

storage/getObjectContexts.js

@@ -0,0 +1,71 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+// sample-metadata:
+//   title: Get Object Contexts
+//   description: Retrieves the structured Object Contexts from an object.
+//   usage: node getObjectContexts.js <BUCKET_NAME> <FILE_NAME>
+
+/**
+ * This application demonstrates how to retrieve the 'contexts' field from a file
+ * in Google Cloud Storage.
+ */
+
+function main(bucketName = 'my-bucket', fileName = 'test.txt') {
+  // [START storage_get_object_contexts]
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // The ID of your GCS bucket
+  // const bucketName = 'your-unique-bucket-name';
+
+  // The ID of your GCS file
+  // const fileName = 'your-file-name';
+
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  const storage = new Storage();
+
+  async function getObjectContexts() {
+    // Gets the metadata for the file
+    const [metadata] = await storage
+      .bucket(bucketName)
+      .file(fileName)
+      .getMetadata();
+
+    // Contexts are stored in metadata.contexts.custom
+    if (metadata.contexts && metadata.contexts.custom) {
+      console.log(`Object Contexts for ${fileName}:`);
+
+      // Iterate through the custom contexts to show values and timestamps
+      for (const [key, details] of Object.entries(metadata.contexts.custom)) {
+        console.log(`- Key: ${key}`);
+        console.log(`  Value: ${details.value}`);
+        console.log(`  Created: ${details.createTime}`);
+        console.log(`  Updated: ${details.updateTime}`);
+      }
+    } else {
+      console.log(`No Object Contexts found for ${fileName}.`);
+    }
+  }
+
+  getObjectContexts().catch(console.error);
+  // [END storage_get_object_contexts]
+}
+
+main(...process.argv.slice(2));

storage/listObjectContexts.js

@@ -0,0 +1,104 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+// sample-metadata:
+//   title: List Objects with Context Filter
+//   description: Lists objects in a bucket that match specific custom contexts.
+//   usage: node listObjectContexts.js <BUCKET_NAME>
+
+/**
+ * This application demonstrates how to list objects in a bucket while filtering
+ * by their custom 'contexts' metadata.
+ */
+
+function main(bucketName = 'my-bucket') {
+  // [START storage_list_object_contexts]
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // The ID of your GCS bucket
+  // const bucketName = 'your-unique-bucket-name';
+
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  const storage = new Storage();
+
+  async function listObjectContexts() {
+    // Define the filter for contexts.
+    const bucket = storage.bucket(bucketName);
+
+    /**
+     * List any object that has a context with the specified key and value.
+     * Syntax: contexts."<key>"="<value>"
+     */
+    const filterByValue = 'contexts."priority"="high"';
+    const [filesByValue] = await bucket.getFiles({
+      filter: filterByValue,
+    });
+
+    console.log(`\nFiles matching filter [${filterByValue}]:`);
+    filesByValue.forEach(file => console.log(` - ${file.name}`));
+
+    /**
+     * List any object that has a context with the specified key attached.
+     * Syntax: contexts."<key>":*
+     */
+    const filterByExistence = 'contexts."team-owner":*';
+    const [filesWithKey] = await bucket.getFiles({
+      filter: filterByExistence,
+    });
+
+    console.log(
+      `\nFiles with the "team-owner" context key [${filterByExistence}]:`
+    );
+    filesWithKey.forEach(file => console.log(` - ${file.name}`));
+
+    /**
+     * List any object that does not have a context with the specified key and value attached.
+     * Syntax: -contexts."<key>"="<value>"
+     */
+    const absenceOfValuePair = '-contexts."priority"="high"';
+    const [filesNoHighPriority] = await bucket.getFiles({
+      filter: absenceOfValuePair,
+    });
+
+    console.log(
+      `\nFiles matching absence of value pair [${absenceOfValuePair}]:`
+    );
+    filesNoHighPriority.forEach(file => console.log(` - ${file.name}`));
+
+    /**
+     * List any object that does not have a context with the specified key attached.
+     * Syntax: -contexts."<key>":*
+     */
+    const absenceOfKey = '-contexts."team-owner":*';
+    const [filesNoTeamOwner] = await bucket.getFiles({
+      filter: absenceOfKey,
+    });
+
+    console.log(
+      `\nFiles matching absence of key regardless of value [${absenceOfKey}]:`
+    );
+    filesNoTeamOwner.forEach(file => console.log(` - ${file.name}`));
+  }
+
+  listObjectContexts().catch(console.error);
+  // [END storage_list_object_contexts]
+}
+
+main(...process.argv.slice(2));

storage/setObjectContexts.js

@@ -0,0 +1,66 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+// sample-metadata:
+//   title: Set Object Contexts
+//   description: Sets custom metadata (contexts) on an object.
+//   usage: node setObjectContexts.js <BUCKET_NAME> <FILE_NAME>
+
+/**
+ * This application demonstrates how to set, update, and delete object contexts (metadata) on a file
+ * in Google Cloud Storage.
+ */
+
+function main(bucketName = 'my-bucket', fileName = 'test.txt') {
+  // [START storage_set_object_contexts]
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // The ID of your GCS bucket
+  // const bucketName = 'your-unique-bucket-name';
+
+  // The ID of your GCS file
+  // const fileName = 'your-file-name';
+
+  // Imports the Google Cloud client library
+  const {Storage} = require('@google-cloud/storage');
+
+  // Creates a client
+  const storage = new Storage();
+
+  async function setObjectContexts() {
+    const file = storage.bucket(bucketName).file(fileName);
+
+    // Create/Update Object Contexts
+    // Object Contexts live in the 'contexts' field, not the 'metadata' field.
+    const [metadata] = await file.setMetadata({
+      contexts: {
+        custom: {
+          'team-owner': {value: 'storage-team'},
+          priority: {value: 'high'},
+        },
+      },
+    });
+
+    console.log(`Updated Object Contexts for ${fileName}:`);
+    console.log(JSON.stringify(metadata.contexts, null, 2));
+  }
+
+  setObjectContexts().catch(console.error);
+  // [END storage_set_object_contexts]
+}
+
+main(...process.argv.slice(2));

storage/system-test/files.test.js

@@ -0,0 +1,153 @@
+// Copyright 2019 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {Storage} = require('@google-cloud/storage');
+const {assert} = require('chai');
+const {before, after, it, describe} = require('mocha');
+const cp = require('child_process');
+const uuid = require('uuid');
+const {promisify} = require('util');
+
+const execSync = cmd => cp.execSync(cmd, {encoding: 'utf-8'});
+
+const storage = new Storage();
+const cwd = path.join(__dirname, '..');
+const bucketName = generateName();
+const bucket = storage.bucket(bucketName);
+const fileName = 'test.txt';
+const filePath = path.join(cwd, 'resources', fileName);
+const downloadFilePath = path.join(cwd, 'downloaded.txt');
+
+describe('file', () => {
+  before(async () => {
+    await bucket.create();
+  });
+
+  after(async () => {
+    await promisify(fs.unlink)(downloadFilePath).catch(console.error);
+    // Try deleting all files twice, just to make sure
+    await bucket.deleteFiles({force: true}).catch(console.error);
+    await bucket.deleteFiles({force: true}).catch(console.error);
+    await bucket.delete().catch(console.error);
+  });
+
+  describe('Object Contexts', () => {
+    const contextFile = bucket.file(fileName);
+
+    beforeEach(async () => {
+      await bucket.upload(filePath, {destination: fileName});
+
+      await contextFile.setMetadata({
+        contexts: {
+          custom: {
+            'team-owner': {value: 'storage-team'},
+            priority: {value: 'high'},
+          },
+        },
+      });
+    });
+
+    it('should set object contexts', async () => {
+      const output = execSync(
+        `node setObjectContexts.js ${bucketName} ${fileName}`
+      );
+      // Verify Initial Creation
+      assert.include(output, `Updated Object Contexts for ${fileName}:`);
+      assert.include(output, '"team-owner":');
+      assert.include(output, '"value": "storage-team"');
+      assert.include(output, '"priority":');
+      assert.include(output, '"value": "high"');
+      assert.include(output, '"createTime":');
+      assert.include(output, '"updateTime":');
+
+      const [metadata] = await contextFile.getMetadata();
+      const customContexts = metadata.contexts?.custom || {};
+
+      assert.strictEqual(customContexts['priority']?.value, 'high');
+      assert.strictEqual(customContexts['team-owner']?.value, 'storage-team');
+    });
+
+    it('should get object contexts', async () => {
+      const output = execSync(
+        `node getObjectContexts.js ${bucketName} ${fileName}`
+      );
+      assert.include(output, `Object Contexts for ${fileName}:`);
+      assert.include(output, 'Key: priority');
+      assert.include(output, 'Value: high');
+      assert.include(output, 'Key: team-owner');
+      assert.include(output, 'Value: storage-team');
+
+      const [metadata] = await contextFile.getMetadata();
+      const customContexts = metadata.contexts?.custom || {};
+
+      assert.strictEqual(customContexts['priority'].value, 'high');
+      assert.strictEqual(customContexts['team-owner'].value, 'storage-team');
+    });
+
+    it('should list objects with context filters', async () => {
+      const noContextFileName = `no-context-${fileName}`;
+      await bucket.upload(filePath, {destination: noContextFileName});
+      // Ensure it has no contexts
+      await bucket
+        .file(noContextFileName)
+        .setMetadata({contexts: {custom: null}});
+
+      const output = execSync(`node listObjectContexts.js ${bucketName}`);
+
+      // Testing Existence of Value Pair (contexts."key"="val")
+      assert.include(
+        output,
+        'Files matching filter [contexts."priority"="high"]'
+      );
+      assert.include(output, ` - ${fileName}`);
+
+      // Testing Existence of Key (contexts."key":*)
+      assert.include(output, 'Files with the "team-owner" context key');
+      assert.include(output, ` - ${fileName}`);
+
+      // Testing Absence of Value Pair (-contexts."key"="val")
+      assert.include(
+        output,
+        'Files matching absence of value pair [-contexts."priority"="high"]'
+      );
+      assert.include(output, ` - ${noContextFileName}`);
+
+      // Testing Absence of Key (-contexts."key":*)
+      assert.include(
+        output,
+        'Files matching absence of key regardless of value [-contexts."team-owner":*]'
+      );
+      assert.include(output, ` - ${noContextFileName}`);
+
+      const [files] = await bucket.getFiles();
+      const targetFile = files.find(f => f.name === fileName);
+
+      assert.exists(targetFile);
+      const [metadata] = await targetFile.getMetadata();
+
+      // Verify the state that the list filter is supposed to find
+      assert.strictEqual(metadata.contexts?.custom?.priority?.value, 'high');
+
+      await bucket.file(noContextFileName).delete();
+    });
+  });
+});
+
+function generateName() {
+  return `nodejs-storage-samples-${uuid.v4()}`;
+}