From 1a9500ab6d8a5c92cce85b4e339e85fd8d929f67 Mon Sep 17 00:00:00 2001
From: feywind <57276408+feywind@users.noreply.github.com>
Date: Wed, 19 Aug 2026 18:00:57 -0400
Subject: [PATCH 1/3] chore(storage): decommission removed sample test suite;
factor out context type to fix jsdoc processing
---
handwritten/storage/CONTRIBUTING.md | 3 --
handwritten/storage/package.json | 4 +-
handwritten/storage/src/acl.ts | 37 --------------
handwritten/storage/src/bucket.ts | 67 -------------------------
handwritten/storage/src/file.ts | 55 +++-----------------
handwritten/storage/src/iam.ts | 10 ----
handwritten/storage/src/index.ts | 6 +--
handwritten/storage/src/notification.ts | 6 ---
handwritten/storage/src/storage.ts | 6 ---
handwritten/storage/src/util.ts | 12 ++---
10 files changed, 16 insertions(+), 190 deletions(-)
diff --git a/handwritten/storage/CONTRIBUTING.md b/handwritten/storage/CONTRIBUTING.md
index 72c44cada5e2..20eafb851033 100644
--- a/handwritten/storage/CONTRIBUTING.md
+++ b/handwritten/storage/CONTRIBUTING.md
@@ -57,9 +57,6 @@ accept your pull requests.
# Run unit tests.
npm test
- # Run sample integration tests.
- npm run samples-test
-
# Run all system tests.
npm run system-test
diff --git a/handwritten/storage/package.json b/handwritten/storage/package.json
index d26df2165e54..653955961903 100644
--- a/handwritten/storage/package.json
+++ b/handwritten/storage/package.json
@@ -47,7 +47,7 @@
"storage"
],
"scripts": {
- "all-test": "npm test && npm run system-test && npm run samples-test",
+ "all-test": "npm test && npm run system-test",
"benchwrapper": "node bin/benchwrapper.js",
"check": "gts check",
"clean": "rm -rf build/",
@@ -63,12 +63,10 @@
"precompile": "rm -rf build/",
"preconformance-test": "npm run compile:cjs -- --sourceMap",
"predocs": "npm run compile:cjs -- --sourceMap",
- "prelint": "cd samples; npm link ../; npm install",
"prepare": "npm run compile",
"presystem-test:esm": "npm run compile:esm",
"presystem-test": "npm run compile -- --sourceMap",
"pretest": "npm run compile -- --sourceMap",
- "samples-test": "npm link && cd samples/ && npm link ../ && npm test && cd ../",
"system-test:esm": "mkdir -p $HOME/.config && mocha build/esm/system-test --timeout 600000 --exit",
"system-test": "mkdir -p $HOME/.config && mocha build/cjs/system-test --timeout 600000 --exit",
"test": "cross-env NODE_OPTIONS=\"--require ./scripts/preload-yargs.cjs --no-deprecation\" c8 mocha build/cjs/test"
diff --git a/handwritten/storage/src/acl.ts b/handwritten/storage/src/acl.ts
index ecd02bb7a832..4581cba159df 100644
--- a/handwritten/storage/src/acl.ts
+++ b/handwritten/storage/src/acl.ts
@@ -494,17 +494,6 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
- * @example include:samples/acl.js
- * region_tag:storage_add_file_owner
- * Example of adding an owner to a file:
- *
- * @example include:samples/acl.js
- * region_tag:storage_add_bucket_owner
- * Example of adding an owner to a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_add_bucket_default_owner
- * Example of adding a default owner to a bucket:
*/
add(
options: AddAclOptions,
@@ -594,17 +583,6 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
- * @example include:samples/acl.js
- * region_tag:storage_remove_bucket_owner
- * Example of removing an owner from a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_remove_bucket_default_owner
- * Example of removing a default owner from a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_remove_file_owner
- * Example of removing an owner from a bucket:
*/
delete(
options: RemoveAclOptions,
@@ -704,21 +682,6 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
- * @example include:samples/acl.js
- * region_tag:storage_print_file_acl
- * Example of printing a file's ACL:
- *
- * @example include:samples/acl.js
- * region_tag:storage_print_file_acl_for_user
- * Example of printing a file's ACL for a specific user:
- *
- * @example include:samples/acl.js
- * region_tag:storage_print_bucket_acl
- * Example of printing a bucket's ACL:
- *
- * @example include:samples/acl.js
- * region_tag:storage_print_bucket_acl_for_user
- * Example of printing a bucket's ACL for a specific user:
*/
get(
optionsOrCallback?: GetAclOptions | GetAclCallback,
diff --git a/handwritten/storage/src/bucket.ts b/handwritten/storage/src/bucket.ts
index 527e7396f87f..2a385bf00db4 100644
--- a/handwritten/storage/src/bucket.ts
+++ b/handwritten/storage/src/bucket.ts
@@ -659,17 +659,6 @@ export enum BucketExceptionMessages {
* });
*
* ```
- * @example include:samples/iam.js
- * region_tag:storage_view_bucket_iam_members
- * Example of retrieving a bucket's IAM policy:
- *
- * @example include:samples/iam.js
- * region_tag:storage_add_bucket_iam_member
- * Example of adding to a bucket's IAM policy:
- *
- * @example include:samples/iam.js
- * region_tag:storage_remove_bucket_iam_member
- * Example of removing from a bucket's IAM policy:
*/
/**
* Cloud Storage uses access control lists (ACLs) to manage object and
@@ -729,29 +718,6 @@ export enum BucketExceptionMessages {
* });
*
* ```
- * @example include:samples/acl.js
- * region_tag:storage_print_bucket_acl
- * Example of printing a bucket's ACL:
- *
- * @example include:samples/acl.js
- * region_tag:storage_print_bucket_acl_for_user
- * Example of printing a bucket's ACL for a specific user:
- *
- * @example include:samples/acl.js
- * region_tag:storage_add_bucket_owner
- * Example of adding an owner to a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_remove_bucket_owner
- * Example of removing an owner from a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_add_bucket_default_owner
- * Example of adding a default owner to a bucket:
- *
- * @example include:samples/acl.js
- * region_tag:storage_remove_bucket_default_owner
- * Example of removing a default owner from a bucket:
*/
/**
* The API-formatted resource description of the bucket.
@@ -994,9 +960,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/buckets.js
- * region_tag:storage_delete_bucket
- * Another example:
*/
delete: {
reqOpts: {
@@ -1154,9 +1117,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/requesterPays.js
- * region_tag:storage_get_requester_pays_status
- * Example of retrieving the requester pays status of a bucket:
*/
getMetadata: {
reqOpts: {
@@ -2085,9 +2045,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/createNotification.js
- * region_tag:storage_create_bucket_notifications
- * Another example:
*/
createNotification(
topic: string,
@@ -2459,9 +2416,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/requesterPays.js
- * region_tag:storage_disable_requester_pays
- * Example of disabling requester pays:
*/
disableRequesterPays(
optionsOrCallback?:
@@ -2657,9 +2611,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/requesterPays.js
- * region_tag:storage_enable_requester_pays
- * Example of enabling requester pays:
*/
enableRequesterPays(
optionsOrCallback?:
@@ -2949,14 +2900,6 @@ class Bucket extends ServiceObject {
* // files contains objects that DO NOT have the 'priority' context key.
* });
* ```
- *
- * @example include:samples/files.js
- * region_tag:storage_list_files
- * Another example:
- *
- * @example include:samples/files.js
- * region_tag:storage_list_files_with_prefix
- * Example of listing files, filtered by a prefix:
*/
getFiles(
queryOrCallback?: GetFilesOptions | GetFilesCallback,
@@ -3158,9 +3101,6 @@ class Bucket extends ServiceObject {
* });
*
* ```
- * @example include:samples/listNotifications.js
- * region_tag:storage_list_bucket_notifications
- * Another example:
*/
getNotifications(
optionsOrCallback?: GetNotificationsOptions | GetNotificationsCallback,
@@ -4478,13 +4418,6 @@ class Bucket extends ServiceObject {
* To upload a file from a URL, use {@link File#createWriteStream}.
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_upload_file
- * Another example:
- *
- * @example include:samples/encryption.js
- * region_tag:storage_upload_encrypted_file
- * Example of uploading an encrypted file:
*/
upload(
pathString: string,
diff --git a/handwritten/storage/src/file.ts b/handwritten/storage/src/file.ts
index 786998c5f4e4..994ca7d8eaba 100644
--- a/handwritten/storage/src/file.ts
+++ b/handwritten/storage/src/file.ts
@@ -570,6 +570,12 @@ export interface ContextValue {
readonly updateTime?: string;
}
+export interface Contexts {
+ custom: {
+ [key: string]: ContextValue | null;
+ } | null;
+}
+
export interface FileMetadata extends BaseMetadata {
acl?: AclMetadata[] | null;
bucket?: string;
@@ -584,11 +590,7 @@ export interface FileMetadata extends BaseMetadata {
encryptionAlgorithm?: string;
keySha256?: string;
};
- contexts?: {
- custom: {
- [key: string]: ContextValue | null;
- } | null;
- };
+ contexts?: Contexts;
customTime?: string;
eventBasedHold?: boolean | null;
readonly eventBasedHoldReleaseTime?: string;
@@ -898,9 +900,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_delete_file
- * Another example:
*/
delete: {
reqOpts: {
@@ -1043,9 +1042,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_get_metadata
- * Another example:
*/
getMetadata: {
reqOpts: {
@@ -1374,9 +1370,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_copy_file
- * Another example:
*/
copy(
destination: string | Bucket | File,
@@ -2432,17 +2425,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_download_file
- * Another example:
- *
- * @example include:samples/encryption.js
- * region_tag:storage_download_encrypted_file
- * Example of downloading an encrypted file:
- *
- * @example include:samples/requesterPays.js
- * region_tag:storage_download_file_requester_pays
- * Example of downloading a file where the requester pays:
*/
download(
optionsOrCallback?: DownloadOptions | DownloadCallback,
@@ -2547,13 +2529,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/encryption.js
- * region_tag:storage_upload_encrypted_file
- * Example of uploading an encrypted file:
- *
- * @example include:samples/encryption.js
- * region_tag:storage_download_encrypted_file
- * Example of downloading an encrypted file:
*/
setEncryptionKey(encryptionKey: string | Buffer) {
this.encryptionKey = encryptionKey;
@@ -3271,9 +3246,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_generate_signed_url
- * Another example:
*/
getSignedUrl(
cfg: GetSignedUrlConfig,
@@ -3562,9 +3534,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_make_public
- * Another example:
*/
makePublic(
callback?: MakeFilePublicCallback,
@@ -3708,9 +3677,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_move_file
- * Another example:
*/
moveFileAtomic(
destination: string | File,
@@ -3925,9 +3891,6 @@ class File extends ServiceObject {
* });
*
* ```
- * @example include:samples/files.js
- * region_tag:storage_move_file
- * Another example:
*/
move(
destination: string | Bucket | File,
@@ -4165,10 +4128,6 @@ class File extends ServiceObject {
* @param {RotateEncryptionKeyOptions} [options] - Configuration options.
* @param {RotateEncryptionKeyCallback} [callback]
* @returns {Promise}
- *
- * @example include:samples/encryption.js
- * region_tag:storage_rotate_encryption_key
- * Example of rotating the encryption key for this file:
*/
rotateEncryptionKey(
optionsOrCallback?:
diff --git a/handwritten/storage/src/iam.ts b/handwritten/storage/src/iam.ts
index 7a90a1b36d47..fbcae7f11ab0 100644
--- a/handwritten/storage/src/iam.ts
+++ b/handwritten/storage/src/iam.ts
@@ -236,9 +236,6 @@ class Iam {
* });
*
* ```
- * @example include:samples/iam.js
- * region_tag:storage_view_bucket_iam_members
- * Example of retrieving a bucket's IAM policy:
*/
getPolicy(
optionsOrCallback?: GetPolicyOptions | GetPolicyCallback,
@@ -320,13 +317,6 @@ class Iam {
* });
*
* ```
- * @example include:samples/iam.js
- * region_tag:storage_add_bucket_iam_member
- * Example of adding to a bucket's IAM policy:
- *
- * @example include:samples/iam.js
- * region_tag:storage_remove_bucket_iam_member
- * Example of removing from a bucket's IAM policy:
*/
setPolicy(
policy: Policy,
diff --git a/handwritten/storage/src/index.ts b/handwritten/storage/src/index.ts
index f93ef6002e73..25c8435ef698 100644
--- a/handwritten/storage/src/index.ts
+++ b/handwritten/storage/src/index.ts
@@ -51,10 +51,6 @@
* 'your-project-id', keyFilename: '/path/to/keyfile.json'
* });
* ```
- *
- * @example include:samples/quickstart.js
- * region_tag:storage_quickstart
- * Full quickstart example:
*/
export {ApiError} from './nodejs-common/index.js';
export {
@@ -171,6 +167,8 @@ export {
export * from './crc32c.js';
export {Channel, StopCallback} from './channel.js';
export {
+ Contexts,
+ ContextValue,
CopyCallback,
CopyOptions,
CopyResponse,
diff --git a/handwritten/storage/src/notification.ts b/handwritten/storage/src/notification.ts
index 95b2e081188d..d115245b5b1d 100644
--- a/handwritten/storage/src/notification.ts
+++ b/handwritten/storage/src/notification.ts
@@ -212,9 +212,6 @@ class Notification extends ServiceObject {
* });
*
* ```
- * @example include:samples/deleteNotification.js
- * region_tag:storage_delete_bucket_notification
- * Another example:
*/
delete: {
reqOpts: {
@@ -291,9 +288,6 @@ class Notification extends ServiceObject {
* });
*
* ```
- * @example include:samples/getMetadataNotifications.js
- * region_tag:storage_print_pubsub_bucket_notification
- * Another example:
*/
getMetadata: {
reqOpts: {
diff --git a/handwritten/storage/src/storage.ts b/handwritten/storage/src/storage.ts
index dd0f735f6ed1..892d3f28398e 100644
--- a/handwritten/storage/src/storage.ts
+++ b/handwritten/storage/src/storage.ts
@@ -992,9 +992,6 @@ export class Storage extends Service {
* });
*
* ```
- * @example include:samples/buckets.js
- * region_tag:storage_create_bucket
- * Another example:
*/
createBucket(
name: string,
@@ -1313,9 +1310,6 @@ export class Storage extends Service {
* });
*
* ```
- * @example include:samples/buckets.js
- * region_tag:storage_list_buckets
- * Another example:
*/
getBuckets(
optionsOrCallback?: GetBucketsRequest | GetBucketsCallback,
diff --git a/handwritten/storage/src/util.ts b/handwritten/storage/src/util.ts
index 024ea95f2021..aa164b6652ac 100644
--- a/handwritten/storage/src/util.ts
+++ b/handwritten/storage/src/util.ts
@@ -19,7 +19,7 @@ import * as url from 'url';
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
import {getPackageJSON} from './package-json-helper.cjs';
-import {FileMetadata} from './file';
+import {FileMetadata, Contexts} from './file';
// Done to avoid a problem with mangling of identifiers when using esModuleInterop
const fileURLToPath = url.fileURLToPath;
@@ -279,10 +279,10 @@ export class PassThroughShim extends PassThrough {
* Double quotes (") are forbidden in context keys and values as they
* interfere with GCS filter string syntax.
*
- * @param {FileMetadata['contexts']} contexts The contexts object to validate.
+ * @param {Contexts} [contexts] The contexts object to validate.
* @returns {void} Throws an error if validation fails.
*/
-export function validateContexts(contexts?: FileMetadata['contexts']): void {
+export function validateContexts(contexts?: Contexts): void {
const custom = contexts?.custom;
if (!custom) return;
for (const [key, context] of Object.entries(custom)) {
@@ -301,11 +301,11 @@ export function validateContexts(contexts?: FileMetadata['contexts']): void {
/**
* Helper to validate contexts and route errors to either a callback or a Promise.
- * @param contexts The contexts to validate.
- * @param callback The optional user-provided callback.
+ * @param {Contexts} [contexts] The contexts to validate.
+ * @param {Function} [callback] The optional user-provided callback.
*/
export function handleContextValidation(
- contexts?: FileMetadata['contexts'],
+ contexts?: Contexts,
callback?: Function,
// eslint-disable-next-line @typescript-eslint/no-explicit-any
): Promise | void {
From 7a1c8c9ab4a5b238e820fef0e6000f868f70dbc2 Mon Sep 17 00:00:00 2001
From: feywind <57276408+feywind@users.noreply.github.com>
Date: Fri, 21 Aug 2026 16:03:43 -0400
Subject: [PATCH 2/3] docs: put back the removed sample link jsdocs
---
handwritten/storage/src/acl.ts | 37 ++++++++++++++
handwritten/storage/src/bucket.ts | 67 +++++++++++++++++++++++++
handwritten/storage/src/file.ts | 43 ++++++++++++++++
handwritten/storage/src/iam.ts | 10 ++++
handwritten/storage/src/index.ts | 4 ++
handwritten/storage/src/notification.ts | 6 +++
handwritten/storage/src/storage.ts | 6 +++
7 files changed, 173 insertions(+)
diff --git a/handwritten/storage/src/acl.ts b/handwritten/storage/src/acl.ts
index 4581cba159df..ecd02bb7a832 100644
--- a/handwritten/storage/src/acl.ts
+++ b/handwritten/storage/src/acl.ts
@@ -494,6 +494,17 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
+ * @example include:samples/acl.js
+ * region_tag:storage_add_file_owner
+ * Example of adding an owner to a file:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_add_bucket_owner
+ * Example of adding an owner to a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_add_bucket_default_owner
+ * Example of adding a default owner to a bucket:
*/
add(
options: AddAclOptions,
@@ -583,6 +594,17 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
+ * @example include:samples/acl.js
+ * region_tag:storage_remove_bucket_owner
+ * Example of removing an owner from a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_remove_bucket_default_owner
+ * Example of removing a default owner from a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_remove_file_owner
+ * Example of removing an owner from a bucket:
*/
delete(
options: RemoveAclOptions,
@@ -682,6 +704,21 @@ class Acl extends AclRoleAccessorMethods {
* });
*
* ```
+ * @example include:samples/acl.js
+ * region_tag:storage_print_file_acl
+ * Example of printing a file's ACL:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_print_file_acl_for_user
+ * Example of printing a file's ACL for a specific user:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_print_bucket_acl
+ * Example of printing a bucket's ACL:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_print_bucket_acl_for_user
+ * Example of printing a bucket's ACL for a specific user:
*/
get(
optionsOrCallback?: GetAclOptions | GetAclCallback,
diff --git a/handwritten/storage/src/bucket.ts b/handwritten/storage/src/bucket.ts
index 2a385bf00db4..527e7396f87f 100644
--- a/handwritten/storage/src/bucket.ts
+++ b/handwritten/storage/src/bucket.ts
@@ -659,6 +659,17 @@ export enum BucketExceptionMessages {
* });
*
* ```
+ * @example include:samples/iam.js
+ * region_tag:storage_view_bucket_iam_members
+ * Example of retrieving a bucket's IAM policy:
+ *
+ * @example include:samples/iam.js
+ * region_tag:storage_add_bucket_iam_member
+ * Example of adding to a bucket's IAM policy:
+ *
+ * @example include:samples/iam.js
+ * region_tag:storage_remove_bucket_iam_member
+ * Example of removing from a bucket's IAM policy:
*/
/**
* Cloud Storage uses access control lists (ACLs) to manage object and
@@ -718,6 +729,29 @@ export enum BucketExceptionMessages {
* });
*
* ```
+ * @example include:samples/acl.js
+ * region_tag:storage_print_bucket_acl
+ * Example of printing a bucket's ACL:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_print_bucket_acl_for_user
+ * Example of printing a bucket's ACL for a specific user:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_add_bucket_owner
+ * Example of adding an owner to a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_remove_bucket_owner
+ * Example of removing an owner from a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_add_bucket_default_owner
+ * Example of adding a default owner to a bucket:
+ *
+ * @example include:samples/acl.js
+ * region_tag:storage_remove_bucket_default_owner
+ * Example of removing a default owner from a bucket:
*/
/**
* The API-formatted resource description of the bucket.
@@ -960,6 +994,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/buckets.js
+ * region_tag:storage_delete_bucket
+ * Another example:
*/
delete: {
reqOpts: {
@@ -1117,6 +1154,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/requesterPays.js
+ * region_tag:storage_get_requester_pays_status
+ * Example of retrieving the requester pays status of a bucket:
*/
getMetadata: {
reqOpts: {
@@ -2045,6 +2085,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/createNotification.js
+ * region_tag:storage_create_bucket_notifications
+ * Another example:
*/
createNotification(
topic: string,
@@ -2416,6 +2459,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/requesterPays.js
+ * region_tag:storage_disable_requester_pays
+ * Example of disabling requester pays:
*/
disableRequesterPays(
optionsOrCallback?:
@@ -2611,6 +2657,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/requesterPays.js
+ * region_tag:storage_enable_requester_pays
+ * Example of enabling requester pays:
*/
enableRequesterPays(
optionsOrCallback?:
@@ -2900,6 +2949,14 @@ class Bucket extends ServiceObject {
* // files contains objects that DO NOT have the 'priority' context key.
* });
* ```
+ *
+ * @example include:samples/files.js
+ * region_tag:storage_list_files
+ * Another example:
+ *
+ * @example include:samples/files.js
+ * region_tag:storage_list_files_with_prefix
+ * Example of listing files, filtered by a prefix:
*/
getFiles(
queryOrCallback?: GetFilesOptions | GetFilesCallback,
@@ -3101,6 +3158,9 @@ class Bucket extends ServiceObject {
* });
*
* ```
+ * @example include:samples/listNotifications.js
+ * region_tag:storage_list_bucket_notifications
+ * Another example:
*/
getNotifications(
optionsOrCallback?: GetNotificationsOptions | GetNotificationsCallback,
@@ -4418,6 +4478,13 @@ class Bucket extends ServiceObject {
* To upload a file from a URL, use {@link File#createWriteStream}.
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_upload_file
+ * Another example:
+ *
+ * @example include:samples/encryption.js
+ * region_tag:storage_upload_encrypted_file
+ * Example of uploading an encrypted file:
*/
upload(
pathString: string,
diff --git a/handwritten/storage/src/file.ts b/handwritten/storage/src/file.ts
index 994ca7d8eaba..3d63397ed92c 100644
--- a/handwritten/storage/src/file.ts
+++ b/handwritten/storage/src/file.ts
@@ -900,6 +900,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_delete_file
+ * Another example:
*/
delete: {
reqOpts: {
@@ -1042,6 +1045,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_get_metadata
+ * Another example:
*/
getMetadata: {
reqOpts: {
@@ -1370,6 +1376,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_copy_file
+ * Another example:
*/
copy(
destination: string | Bucket | File,
@@ -2425,6 +2434,17 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_download_file
+ * Another example:
+ *
+ * @example include:samples/encryption.js
+ * region_tag:storage_download_encrypted_file
+ * Example of downloading an encrypted file:
+ *
+ * @example include:samples/requesterPays.js
+ * region_tag:storage_download_file_requester_pays
+ * Example of downloading a file where the requester pays:
*/
download(
optionsOrCallback?: DownloadOptions | DownloadCallback,
@@ -2529,6 +2549,13 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/encryption.js
+ * region_tag:storage_upload_encrypted_file
+ * Example of uploading an encrypted file:
+ *
+ * @example include:samples/encryption.js
+ * region_tag:storage_download_encrypted_file
+ * Example of downloading an encrypted file:
*/
setEncryptionKey(encryptionKey: string | Buffer) {
this.encryptionKey = encryptionKey;
@@ -3246,6 +3273,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_generate_signed_url
+ * Another example:
*/
getSignedUrl(
cfg: GetSignedUrlConfig,
@@ -3534,6 +3564,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_make_public
+ * Another example:
*/
makePublic(
callback?: MakeFilePublicCallback,
@@ -3677,6 +3710,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_move_file
+ * Another example:
*/
moveFileAtomic(
destination: string | File,
@@ -3891,6 +3927,9 @@ class File extends ServiceObject {
* });
*
* ```
+ * @example include:samples/files.js
+ * region_tag:storage_move_file
+ * Another example:
*/
move(
destination: string | Bucket | File,
@@ -4128,6 +4167,10 @@ class File extends ServiceObject {
* @param {RotateEncryptionKeyOptions} [options] - Configuration options.
* @param {RotateEncryptionKeyCallback} [callback]
* @returns {Promise}
+ *
+ * @example include:samples/encryption.js
+ * region_tag:storage_rotate_encryption_key
+ * Example of rotating the encryption key for this file:
*/
rotateEncryptionKey(
optionsOrCallback?:
diff --git a/handwritten/storage/src/iam.ts b/handwritten/storage/src/iam.ts
index fbcae7f11ab0..7a90a1b36d47 100644
--- a/handwritten/storage/src/iam.ts
+++ b/handwritten/storage/src/iam.ts
@@ -236,6 +236,9 @@ class Iam {
* });
*
* ```
+ * @example include:samples/iam.js
+ * region_tag:storage_view_bucket_iam_members
+ * Example of retrieving a bucket's IAM policy:
*/
getPolicy(
optionsOrCallback?: GetPolicyOptions | GetPolicyCallback,
@@ -317,6 +320,13 @@ class Iam {
* });
*
* ```
+ * @example include:samples/iam.js
+ * region_tag:storage_add_bucket_iam_member
+ * Example of adding to a bucket's IAM policy:
+ *
+ * @example include:samples/iam.js
+ * region_tag:storage_remove_bucket_iam_member
+ * Example of removing from a bucket's IAM policy:
*/
setPolicy(
policy: Policy,
diff --git a/handwritten/storage/src/index.ts b/handwritten/storage/src/index.ts
index 25c8435ef698..78285e225105 100644
--- a/handwritten/storage/src/index.ts
+++ b/handwritten/storage/src/index.ts
@@ -51,6 +51,10 @@
* 'your-project-id', keyFilename: '/path/to/keyfile.json'
* });
* ```
+ *
+ * @example include:samples/quickstart.js
+ * region_tag:storage_quickstart
+ * Full quickstart example:
*/
export {ApiError} from './nodejs-common/index.js';
export {
diff --git a/handwritten/storage/src/notification.ts b/handwritten/storage/src/notification.ts
index d115245b5b1d..95b2e081188d 100644
--- a/handwritten/storage/src/notification.ts
+++ b/handwritten/storage/src/notification.ts
@@ -212,6 +212,9 @@ class Notification extends ServiceObject {
* });
*
* ```
+ * @example include:samples/deleteNotification.js
+ * region_tag:storage_delete_bucket_notification
+ * Another example:
*/
delete: {
reqOpts: {
@@ -288,6 +291,9 @@ class Notification extends ServiceObject {
* });
*
* ```
+ * @example include:samples/getMetadataNotifications.js
+ * region_tag:storage_print_pubsub_bucket_notification
+ * Another example:
*/
getMetadata: {
reqOpts: {
diff --git a/handwritten/storage/src/storage.ts b/handwritten/storage/src/storage.ts
index 892d3f28398e..dd0f735f6ed1 100644
--- a/handwritten/storage/src/storage.ts
+++ b/handwritten/storage/src/storage.ts
@@ -992,6 +992,9 @@ export class Storage extends Service {
* });
*
* ```
+ * @example include:samples/buckets.js
+ * region_tag:storage_create_bucket
+ * Another example:
*/
createBucket(
name: string,
@@ -1310,6 +1313,9 @@ export class Storage extends Service {
* });
*
* ```
+ * @example include:samples/buckets.js
+ * region_tag:storage_list_buckets
+ * Another example:
*/
getBuckets(
optionsOrCallback?: GetBucketsRequest | GetBucketsCallback,
From bd7ee7163eee330d72efa32bf2c26d3f53e4cedb Mon Sep 17 00:00:00 2001
From: feywind <57276408+feywind@users.noreply.github.com>
Date: Fri, 21 Aug 2026 16:20:19 -0400
Subject: [PATCH 3/3] build: update old module resolution to work with new node
22+ pieces
---
handwritten/storage/package.json | 1 -
handwritten/storage/src/resumable-upload.ts | 1 -
handwritten/storage/src/util.ts | 2 +-
handwritten/storage/test/resumable-upload.ts | 16 ++++------------
handwritten/storage/tsconfig.json | 4 ++--
5 files changed, 7 insertions(+), 17 deletions(-)
diff --git a/handwritten/storage/package.json b/handwritten/storage/package.json
index 653955961903..93fd9ae52fe4 100644
--- a/handwritten/storage/package.json
+++ b/handwritten/storage/package.json
@@ -75,7 +75,6 @@
"@google-cloud/paginator": "^7.0.1",
"@google-cloud/projectify": "^6.0.1",
"@google-cloud/promisify": "^6.0.1",
- "abort-controller": "^3.0.0",
"async-retry": "^1.3.3",
"duplexify": "^4.1.3",
"fast-xml-parser": "^5.3.4",
diff --git a/handwritten/storage/src/resumable-upload.ts b/handwritten/storage/src/resumable-upload.ts
index df63ec637b1d..271f22bca627 100644
--- a/handwritten/storage/src/resumable-upload.ts
+++ b/handwritten/storage/src/resumable-upload.ts
@@ -12,7 +12,6 @@
// See the License for the specific language governing permissions and
// limitations under the License.
-import AbortController from 'abort-controller';
import {createHash} from 'crypto';
import {
GaxiosOptions,
diff --git a/handwritten/storage/src/util.ts b/handwritten/storage/src/util.ts
index aa164b6652ac..3a7edf410f24 100644
--- a/handwritten/storage/src/util.ts
+++ b/handwritten/storage/src/util.ts
@@ -19,7 +19,7 @@ import * as url from 'url';
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
import {getPackageJSON} from './package-json-helper.cjs';
-import {FileMetadata, Contexts} from './file';
+import {Contexts} from './file.js';
// Done to avoid a problem with mangling of identifiers when using esModuleInterop
const fileURLToPath = url.fileURLToPath;
diff --git a/handwritten/storage/test/resumable-upload.ts b/handwritten/storage/test/resumable-upload.ts
index 6e6985878b00..9bb5fb0aa216 100644
--- a/handwritten/storage/test/resumable-upload.ts
+++ b/handwritten/storage/test/resumable-upload.ts
@@ -42,13 +42,6 @@ import {FileExceptionMessages} from '../src/file.js';
nock.disableNetConnect();
-class AbortController {
- aborted = false;
- signal = this;
- abort() {
- this.aborted = true;
- }
-}
const RESUMABLE_INCOMPLETE_STATUS_CODE = 308;
/** 256 KiB */
@@ -102,7 +95,6 @@ describe('resumable-upload', () => {
const keyFile = path.join(getDirName(), '../../../test/fixtures/keys.json');
before(() => {
- mockery.registerMock('abort-controller', AbortController);
mockery.enable({useCleanCache: true, warnOnUnregistered: false});
upload = require('../src/resumable-upload').upload;
});
@@ -2142,7 +2134,7 @@ describe('resumable-upload', () => {
it('should pass a signal from the abort controller', done => {
up.authClient = {
request: (reqOpts: GaxiosOptions) => {
- assert(reqOpts.signal instanceof AbortController);
+ assert(reqOpts.signal instanceof AbortSignal);
done();
},
};
@@ -2152,11 +2144,11 @@ describe('resumable-upload', () => {
it('should abort on an error', done => {
up.on('error', () => {});
- let abortController: AbortController;
+ let signal: AbortSignal;
up.authClient = {
request: (reqOpts: GaxiosOptions) => {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
- abortController = reqOpts.signal as any;
+ signal = reqOpts.signal as any;
},
};
@@ -2164,7 +2156,7 @@ describe('resumable-upload', () => {
up.emit('error', new Error('Error.'));
setImmediate(() => {
- assert.strictEqual(abortController.aborted, true);
+ assert.strictEqual(signal.aborted, true);
done();
});
});
diff --git a/handwritten/storage/tsconfig.json b/handwritten/storage/tsconfig.json
index bf65354d9fa1..6b554ca2a4ca 100644
--- a/handwritten/storage/tsconfig.json
+++ b/handwritten/storage/tsconfig.json
@@ -4,8 +4,8 @@
"rootDir": ".",
"outDir": "build/esm",
"resolveJsonModule": true,
- "module": "es2020",
- "moduleResolution": "node",
+ "module": "node16",
+ "moduleResolution": "node16",
"lib": ["ES2020"],
"sourceMap": false,
"esModuleInterop": true,