chore(storage): factor out context type to fix jsdoc processing failure

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
 

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"

handwritten/storage/src/file.ts

@@ -77,14 +77,14 @@
   RequestResponse,
   SetMetadataOptions,
 } from './nodejs-common/service-object.js';
 import * as r from 'teeny-request';
 
 export type GetExpirationDateResponse = [Date];
 export interface GetExpirationDateCallback {
   (
     err: Error | null,
     expirationDate?: Date | null,
     apiResponse?: unknown,
   ): void;
 }
 
@@ -95,7 +95,7 @@
 }
 
 export type SaveData =
   | string
   | Buffer
   | Uint8Array
   | PipelineSource<string | Buffer | Uint8Array>;
@@ -148,7 +148,7 @@
   url: string;
   fields: PolicyFields;
 }
 export interface GetSignedUrlConfig
   extends Pick<SignerGetSignedUrlConfig, 'host' | 'signingEndpoint'> {
   /**
    * The action to permit with the signed URL.
@@ -304,7 +304,7 @@
   | 'uri'
   | 'userProject';
 
 export interface CreateResumableUploadOptions
   extends Pick<resumableUpload.UploadConfig, PublicResumableUploadOptions> {
   /**
    * A CRC32C to resume from when continuing a previous upload. It is recommended
@@ -370,7 +370,7 @@
   (
     err: Error | null,
     destinationFile?: File | null,
     apiResponse?: unknown,
   ): void;
 }
 
@@ -434,7 +434,7 @@
   ]
     .map(r => r.source)
     .join(''),
   'i',
 );
 
 export interface FileOptions {
@@ -493,7 +493,7 @@
 
 export type DownloadCallback = (
   err: RequestError | null,
   contents: Buffer,
 ) => void;
 
 export interface DownloadOptions extends CreateReadStreamOptions {
@@ -570,6 +570,12 @@
   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 @@
     encryptionAlgorithm?: string;
     keySha256?: string;
   };
-  contexts?: {
-    custom: {
-      [key: string]: ContextValue | null;
-    } | null;
-  };
+  contexts?: Contexts;
   customTime?: string;
   eventBasedHold?: boolean | null;
   readonly eventBasedHoldReleaseTime?: string;
@@ -1224,7 +1226,7 @@
    * - if `idempotencyStrategy` is set to `RetryNever`
    */
   private shouldRetryBasedOnPreconditionAndIdempotencyStrat(
     options?: PreconditionOptions,
   ): boolean {
     return !(
       (options?.ifGenerationMatch === undefined &&
@@ -1238,7 +1240,7 @@
 
   copy(
     destination: string | Bucket | File,
     options?: CopyOptions,
   ): Promise<CopyResponse>;
   copy(destination: string | Bucket | File, callback: CopyCallback): void;
   copy(
@@ -1686,7 +1688,7 @@
     ) => {
       if (err) {
         // Get error message from the body.
         this.getBufferFromReadable(rawResponseStream as Readable).then(body => {
           err.message = body.toString('utf8');
           throughStream.destroy(err);
         });
@@ -2505,7 +2507,7 @@
         });
     } else {
       this.getBufferFromReadable(fileStream)
         .then(contents => callback?.(null, contents))
         .catch(callback as (err: RequestError) => void);
     }
   }
@@ -2882,14 +2884,14 @@
 
     this.storage.authClient.sign(policyBase64, options.signingEndpoint).then(
       signature => {
         callback(null, {
           string: policyString,
           base64: policyBase64,
           signature,
         });
       },
       err => {
         callback(new SigningError(err.message));
       },
     );
   }
@@ -4340,10 +4342,10 @@
       return returnValue
         .then(() => {
           if (callback) {
             return callback();
           }
         })
         .catch(callback);
     }
   }
 

handwritten/storage/src/index.ts

@@ -171,6 +171,8 @@ export {
 export * from './crc32c.js';
 export {Channel, StopCallback} from './channel.js';
 export {
+  Contexts,
+  ContextValue,
   CopyCallback,
   CopyOptions,
   CopyResponse,

handwritten/storage/src/util.ts

@@ -19,7 +19,7 @@
 // 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 @@
  * 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 @@
 
 /**
  * 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<any> | void {