Merge pull request #36 from invertase/@ehesp/storage-utils-lib

Author: Ehesp

.gitignore

@@ -86,4 +86,6 @@ yarn.lock
 
 
 #vscode
-.vscode
+.vscode
+
+dist

.prettierignore

@@ -1,4 +1,5 @@
 node_modules
 build
-lib
+**/functions/lib/**/*.js
+**/extensions/storage-image-processing-api/lib/src/types/**/*.ts
 package-lock.json

docs/storage-image-processing-api/index.mdx

@@ -129,3 +129,24 @@ const operations = [
 const encodedOperations = encodeURIComponent(JSON.stringify(operations));
 const url = `https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process?operations=${encodedOperations}`;
 ```
+
+### JavaScript utility library
+
+Additionally, a utility library exists to provide a fully typed interface for constructing options:
+
+```ts
+import { builder } from '@invertase/storage-image-processing-api';
+
+const output = builder()
+  .input({
+    source: 'https://example.com/image.jpg',
+  })
+  .rotate({ angle: 90 })
+  .output({
+    format: 'png',
+  });
+
+console.log(output.toJSON());
+```
+
+For more details, [view the documentation](/utility-library).

docs/storage-image-processing-api/utility-libray.mdx

@@ -0,0 +1,67 @@
+# Utilty Library
+
+To assist with the usage of this Extension, a [utility library](https://www.npmjs.com/package/@invertase/storage-image-processing-api) exists
+to help provide a typed API interface for easily constructing operations to send to the API.
+
+## Installation
+
+```bash
+npm i --save @invertase/storage-image-processing-api
+```
+
+## Usage
+
+Once installed, import the `builder` function from the library:
+
+```ts
+import { builder } from '@invertase/storage-image-processing-api';
+```
+
+The `builder` function returns a new `StorageImageProcessingApi` instance which provides a API for constructing operations to send to the API.
+At a minimum, you must provide an `input` and `output` operation as required by the extension itself:
+
+```ts
+import { builder } from '@invertase/storage-image-processing-api';
+
+const build = builder()
+  .input({
+    url: 'https://example.com/image.jpg',
+  })
+  .output({
+    format: 'png',
+  });
+```
+
+To provide additional operations, you can chain them together. For example,
+to apply a blur, grayscale and flip the provided input image, and return a new PNG image:
+
+```ts
+const output = builder()
+  .input({
+    url: 'https://example.com/image.jpg',
+  })
+  .blur()
+  .grayscale()
+  .flip()
+  .output({
+    format: 'png',
+  });
+```
+
+Please refer to the [operations](/operations) documentation for a full list of available operations, their API and examples.
+
+Once you have constructed your operations, you can return the operations as JSON, a JSON string or encoded JSON string value:
+
+```ts
+const json = output.toJSON();
+const jsonString = output.toJSONString();
+const encodedJsonString = output.toEncodedJSONString();
+```
+
+The encoded JSON string value can be passed directly to the extension as the `operations` parameter:
+
+```ts
+const encodedJsonString = output.toEncodedJSONString();
+
+const url = `https://{LOCATION}-{PROJECT_ID}.cloudfunctions.net/ext-storage-image-processing-api-handler/process?operations=${encodedJsonString}`;
+```

extensions/storage-image-processing-api/functions/package.json

@@ -4,13 +4,15 @@
   "scripts": {
     "prepare": "npm run build",
     "build": "tsc",
+    "copy-types": "tsc --emitDeclarationOnly --declaration --allowJs --outDir ../lib/src/types",
     "build:watch": "tsc --watch",
     "dev": "EXPRESS_SERVER=true ../../../node_modules/.bin/nodemon",
     "emulator:local": "FIREBASE_STORAGE_EMULATOR_HOST='localhost:9199' firebase ext:dev:emulators:start --test-config=__tests__/test-firebase.json --test-params=__tests__/test-params.env --project=extensions-testing --import=./__tests__/data",
     "generate-readme": "firebase ext:info .. --markdown > ../README.md",
     "test:watch": "jest --config=./jest.config.js --watch",
     "test": "FIREBASE_STORAGE_EMULATOR_HOST='localhost:9199' firebase ext:dev:emulators:exec ./node_modules/.bin/jest --test-config=__tests__/test-firebase.json --test-params=__tests__/test-params.env --project=extensions-testing --import=./__tests__/data",
-    "deploy": "firebase ext:install ../ --project=extensions-testing"
+    "deploy": "firebase ext:install ../ --project=extensions-testing",
+    "postinstall": "npm run copy-types"
   },
   "engines": {
     "node": "14"

extensions/storage-image-processing-api/functions/src/index.ts

@@ -35,6 +35,7 @@ import {
 } from './utils';
 import { Operation, ValidatedOperation } from './types';
 import { extensionConfiguration } from './config';
+import sharp from 'sharp';
 
 async function processImageRequest(
   validatedOperations: ValidatedOperation[],
@@ -58,14 +59,14 @@ async function processImageRequest(
   }
 
   // Apply operations.
-  let instance = null;
+  let instance: sharp.Sharp | null = null;
   for (let i = 0; i < validatedOperations.length; i++) {
     const validatedOperation = validatedOperations[i];
     instance = await applyValidatedOperation(instance, validatedOperation);
   }
 
   const finalFileMetadata = omitKeys(
-    await instance.metadata(),
+    await (instance as sharp.Sharp).metadata(),
     fileMetadataBufferKeys,
   );
 
@@ -77,7 +78,9 @@ async function processImageRequest(
     return;
   }
 
-  const output = await instance.toBuffer({ resolveWithObject: true });
+  const output = await (instance as sharp.Sharp).toBuffer({
+    resolveWithObject: true,
+  });
   const { data, info } = output;
 
   functions.logger.debug(`Processed a new request.`, validatedOperations);
@@ -125,7 +128,7 @@ app.get(
         }),
       );
     }
-    let operations: Operation[] = null;
+    let operations: Operation[] = [];
     try {
       operations = JSON.parse(decodeURIComponent(operationsString));
     } catch (e) {

extensions/storage-image-processing-api/functions/src/operations/index.ts

@@ -15,7 +15,7 @@
  */
 
 import { AssertionError } from 'assert';
-import sharp from 'sharp';
+import sharp, { SharpOptions } from 'sharp';
 import superstruct from 'superstruct';
 
 import { omitKey, omitUndefinedValues } from '../utils';
@@ -174,7 +174,7 @@ export function jsonAsValidatedOperations(
     try {
       const options = asValidatedOperationOptions(rawOptions);
       output.push({
-        source: null,
+        source: '',
         operation,
         rawOptions,
         options,
@@ -260,14 +260,14 @@ export async function applyValidatedOperation(
   for (let i = 0; i < builtOperation.actions.length; i++) {
     const action = builtOperation.actions[i];
     if (action.method == 'constructor') {
-      currentInstance = sharp(...action.arguments);
-    } else {
+      currentInstance = sharp(...(action.arguments as SharpOptions[]));
+    } else if (currentInstance != null) {
       currentInstance = (
         currentInstance[action.method] as (...args: unknown[]) => sharp.Sharp
       )(...action.arguments);
       const newBuffer = await currentInstance.toBuffer();
       currentInstance = sharp(newBuffer);
     }
   }
-  return currentInstance;
+  return currentInstance as sharp.Sharp;
 }

extensions/storage-image-processing-api/functions/src/operations/input.ts

@@ -113,7 +113,16 @@ const struct = superstruct.union([
   structCreateNewImage,
 ]);
 
-export type OperationInput = superstruct.Infer<typeof struct>;
+export type OperationInputGcs = superstruct.Infer<typeof structFromGcs>;
+export type OperationInputUrl = superstruct.Infer<typeof structFromUrl>;
+export type OperationInputCreateNew = superstruct.Infer<
+  typeof structCreateNewImage
+>;
+
+export type OperationInput =
+  | OperationInputGcs
+  | OperationInputUrl
+  | OperationInputCreateNew;
 
 export const operationInput: OperationBuilder = {
   name,
@@ -146,7 +155,7 @@ export const operationInput: OperationBuilder = {
 };
 
 async function fetchUrl(options: OperationInput): Promise<OperationAction[]> {
-  if (options.type !== 'url') return;
+  if (options.type !== 'url') return [];
   if (!options.url.startsWith('http')) {
     throw new AssertionError({
       message: `'${options.url}' does not appear to be a valid http url.`,
@@ -163,7 +172,7 @@ async function fetchUrl(options: OperationInput): Promise<OperationAction[]> {
 async function fetchGcsFile(
   options: OperationInput,
 ): Promise<OperationAction[]> {
-  if (options.type !== 'gcs') return;
+  if (options.type !== 'gcs') return [];
   const firebaseStorageApi =
     process.env.NODE_ENV === 'production'
       ? 'https://firebasestorage.googleapis.com'
@@ -203,7 +212,7 @@ async function fetchGcsFile(
 }
 
 function newImageOptions(options: OperationInput): OperationAction[] {
-  if (options.type !== 'create') return;
+  if (options.type !== 'create') return [];
   const create: Record<string, unknown | Record<string, unknown>> = {};
 
   create.width = options.width;
@@ -221,10 +230,10 @@ function newImageOptions(options: OperationInput): OperationAction[] {
     type: 'gaussian',
   };
   if (options.noiseMean != undefined) {
-    create.noise['mean'] = options.noiseMean;
+    (create.noise as Record<string, number>)['mean'] = options.noiseMean;
   }
   if (options.noiseSigma != undefined) {
-    create.noise['sigma'] = options.noiseSigma;
+    (create.noise as Record<string, number>)['sigma'] = options.noiseSigma;
   }
 
   return [

extensions/storage-image-processing-api/functions/src/operations/output.ts

@@ -335,7 +335,18 @@ const struct = superstruct.union([
   structAvif,
 ]);
 
-export type OperationOutput = superstruct.Infer<typeof struct>;
+export type OperationOutputPng = superstruct.Infer<typeof structPng>;
+export type OperationOutputJpeg = superstruct.Infer<typeof structJpeg>;
+export type OperationOutputWebp = superstruct.Infer<typeof structWebp>;
+export type OperationOutputTiff = superstruct.Infer<typeof structTiff>;
+export type OperationOutputAvif = superstruct.Infer<typeof structAvif>;
+
+export type OperationOutput =
+  | OperationOutputPng
+  | OperationOutputJpeg
+  | OperationOutputWebp
+  | OperationOutputTiff
+  | OperationOutputAvif;
 
 export const operationOutput: OperationBuilder = {
   name,

extensions/storage-image-processing-api/functions/src/utils.ts

@@ -80,7 +80,9 @@ export function coerceStringToArray<T>(
   });
 }
 
-export function omitUndefinedValues<T>(object: T): T {
+export function omitUndefinedValues<T extends Record<string, unknown>>(
+  object: T,
+): T {
   Object.keys(object).forEach(key =>
     object[key] === undefined ? delete object[key] : {},
   );
@@ -127,12 +129,12 @@ export async function fetchImageBufferFromUrl(url: string): Promise<Buffer> {
       responseType: 'arraybuffer',
     }),
   );
-  let response: axios.AxiosResponse = possibleResponse;
+  let response: axios.AxiosResponse | undefined = possibleResponse;
   if (possibleError) {
     response = possibleError.response;
   }
 
-  if (response.data && response.status == 200) {
+  if (response && response.data && response.status == 200) {
     const isImage = await isImageFileType(response.data);
     if (!isImage) {
       throw new AssertionError({
@@ -143,7 +145,7 @@ export async function fetchImageBufferFromUrl(url: string): Promise<Buffer> {
     return response.data;
   }
 
-  const errorMessage = `Unable to fetch image from url "${url}", the url returned a non-successful status code of "${response.status}".`;
+  const errorMessage = `Unable to fetch image from url "${url}", the url returned a non-successful status code of "${response?.status}".`;
   throw new AssertionError({
     message: `${errorMessage} The returned error was: ${possibleError.message}`,
   });