v0.0.1

samestrin · samestrin · commit afe0326ef134 · 2024-05-13T16:45:45.000-07:00
diff --git a/README.md b/README.md
@@ -1 +1,309 @@
-# image-size-api-netlify-edge-functions
+# image-api-netlify-edge-functions
+
+[![Star on GitHub](https://img.shields.io/github/stars/samestrin/image-api-netlify-edge-function?style=social)](https://github.com/samestrin/image-api-netlify-edge-function/stargazers)[![Fork on GitHub](https://img.shields.io/github/forks/samestrin/image-api-netlify-edge-function?style=social)](https://github.com/samestrin/image-api-netlify-edge-function/network/members)[![Watch on GitHub](https://img.shields.io/github/watchers/samestrin/image-api-netlify-edge-function?style=social)](https://github.com/samestrin/image-api-netlify-edge-function/watchers)
+
+![Version 0.0.1](https://img.shields.io/badge/Version-0.0.1-blue)[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)[![Built with Node.js](https://img.shields.io/badge/Built%20with-TypeScript-green)](https://www.typescriptlang.org/)
+
+**image-size-api-netlify-edge-functions** is a collection of serverless functions designed to handle various image processing tasks, deployed on the Netlify Edge platform. This project leverages the power of ImageMagick, a robust image manipulation library, to perform operations such as analyzing, converting, cropping, resizing, and generating thumbnails for images. These functions are optimized for edge computing, ensuring low latency and high performance.
+
+### **Netlify Edge Functions**
+
+Edge functions have limits for their size and the amount of memory and execution time they can use:
+
+- **Code size limit**: 20 MB after compression. This is the maximum edge function bundle size supported.
+- **Memory per set of deployed edge functions**: 512 MB
+- **CPU execution time per request**: _50 ms_. This tracks all time spent running your scripts. Execution time does not include time spent waiting for resources or responses.
+- **Response header timeout**: 40 s
+
+While resource-limited, Netlify provides _1M/month requests_ to edge functions per site at the free tier. Pro members have _2M/month requests_.
+
+### **Features**
+
+- **Analyze Image**: Computes the brightness and histogram of an image.
+- **Convert Image**: Converts images to different formats.
+- **Crop Image**: Crops images based on specified dimensions.
+- **Edge Enhance**: Enhances the edges of an image.
+- **Generate Thumbnail**: Creates thumbnails from images with specified dimensions.
+- **Image Dimensions**: Extracts the dimensions of various image formats.
+- **Resize Image**: Resizes images while maintaining aspect ratio.
+
+### **Dependencies**
+
+- **Netlify**: For deploying serverless functions.
+- **ImageMagick**: For performing image manipulations.
+- **multiParser**: For parsing multipart form data.
+
+### **Installation**
+
+To set up the project locally, follow these steps:
+
+1.  **Clone the Repository**:
+
+```bash
+git clone https://github.com/samestrin/image-size-api-netlify-edge-functions.git
+cd image-size-api-netlify-edge-functions
+```
+
+2.  **Install Dependencies**: Ensure you have the required dependencies installed. Use npm or yarn to install any necessary packages.
+
+```bash
+npm install
+```
+
+3.  **Set Up Netlify CLI**: Install the Netlify CLI to deploy and test the functions locally.
+
+```bash
+
+npm install -g netlify-cli
+```
+
+4.  **Run the Functions Locally**: Use the Netlify CLI to run the edge functions locally.
+
+```bash
+netlify dev
+```
+
+### **Configuration**
+
+The `**netlify.toml**` file contains the configuration for the edge functions. Each function is mapped to a specific endpoint:
+
+```toml
+[build]
+  publish = "public"
+  functions = "netlify/functions"
+
+[[edge_functions]]
+  function = "image-dimensions"
+  path = "/api/image-dimensions"
+
+[[edge_functions]]
+  function = "convert-image"
+  path = "/api/convert-image"
+
+[[edge_functions]]
+  function = "generate-thumbnail"
+  path = "/api/generate-thumbnail"
+
+[[edge_functions]]
+  function = "analyze-image"
+  path = "/api/analyze-image"
+
+[[edge_functions]]
+  function = "crop-image"
+  path = "/api/crop-image"
+
+[[edge_functions]]
+  function = "resize-image"
+  path = "/api/resize-image"
+
+[[edge_functions]]
+  function = "edge-enhance"
+  path = "/api/edge-enhance"
+```
+
+Endpoints Documentation
+
+## Endpoints
+
+### Analyze Image
+
+**Endpoint:** `/api/analyze-image`  
+**Method:** POST
+
+Analyzes an image to compute its brightness and histogram.
+
+- `file`: The image file to be analyzed.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/analyze-image \
+    -F 'file=@/path/to/image.jpg'
+```
+
+The server responds with:
+
+    {
+      "brightness": 123.45,
+      "histogram": {
+        "255,255,255": 100,
+        "0,0,0": 50,
+        ...
+      }
+    }
+
+### Convert Image
+
+**Endpoint:** `/api/convert-image`  
+**Method:** POST
+
+Converts an image to a specified format.
+
+- `file`: The image file to be converted.
+- `targetFormat`: The desired target format (e.g., `png`, `jpeg`).
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/convert-image \
+    -F 'file=@/path/to/image.jpg' \
+    -F 'targetFormat=png'
+```
+
+The server responds with the converted image file.
+
+### Crop Image
+
+**Endpoint:** `/api/crop-image`  
+**Method:** POST
+
+Crops an image based on the specified dimensions.
+
+- `file`: The image file to be cropped.
+- `x`: The x-coordinate of the top-left corner.
+- `y`: The y-coordinate of the top-left corner.
+- `width`: The width of the cropped area.
+- `height`: The height of the cropped area.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/crop-image \
+    -F 'file=@/path/to/image.jpg' \
+    -F 'x=10' \
+    -F 'y=10' \
+    -F 'width=100' \
+    -F 'height=100'
+```
+
+The server responds with the cropped image file.
+
+### Edge Enhance
+
+**Endpoint:** `/api/edge-enhance`  
+**Method:** POST
+
+Enhances the edges of an image.
+
+- `file`: The image file to be processed.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/edge-enhance \
+    -F 'file=@/path/to/image.jpg'
+```
+
+The server responds with the edge-enhanced image file.
+
+### Generate Thumbnail
+
+**Endpoint:** `/api/generate-thumbnail`  
+**Method:** POST
+
+Generates a thumbnail from an image with specified dimensions.
+
+- `file`: The image file to be used for generating the thumbnail.
+- `width`: The width of the thumbnail.
+- `height`: The height of the thumbnail.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/generate-thumbnail \
+    -F 'file=@/path/to/image.jpg' \
+    -F 'width=100' \
+    -F 'height=100'
+```
+
+The server responds with the generated thumbnail image.
+
+### Image Dimensions
+
+**Endpoint:** `/api/image-dimensions`  
+**Method:** POST
+
+Extracts the dimensions of an image.
+
+- `file`: The image file to be analyzed.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/image-dimensions \
+    -F 'file=@/path/to/image.jpg'
+```
+
+The server responds with:
+
+    {
+      "filename": "image.jpg",
+      "dimensions": {
+        "width": 800,
+        "height": 600
+      }
+    }
+
+### Resize Image
+
+**Endpoint:** `/api/resize-image`  
+**Method:** POST
+
+Resizes an image while maintaining the aspect ratio.
+
+- `file`: The image file to be resized.
+- `width`: The desired width of the resized image.
+- `height`: The desired height of the resized image.
+
+#### Example Usage
+
+Use a tool like Postman or curl to make a request:
+
+```bash
+curl -X POST \
+    https://localhost/api/resize-image \
+    -F 'file=@/path/to/image.jpg' \
+    -F 'width=800' \
+    -F 'height=600'
+```
+
+The server responds with the resized image file.
+
+## Error Handling
+
+The API handles errors gracefully and returns appropriate error responses:
+
+- **400 Bad Request**: Invalid request parameters.
+- **404 Not Found**: Resource not found.
+- **405 Method Not Allowed**: Invalid request method (not POST).
+- **500 Internal Server Error**: Unexpected server error.
+
+## Contribute
+
+Contributions to this project are welcome. Please fork the repository and submit a pull request with your changes or improvements.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Share
+
+[![Twitter](https://img.shields.io/badge/X-Tweet-blue)](https://twitter.com/intent/tweet?text=Check%20out%20this%20awesome%20project!&url=https://github.com/samestrin/image-api-netlify-edge-function) [![Facebook](https://img.shields.io/badge/Facebook-Share-blue)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/samestrin/image-api-netlify-edge-function) [![LinkedIn](https://img.shields.io/badge/LinkedIn-Share-blue)](https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/samestrin/image-api-netlify-edge-function)
diff --git a/netlify/edge-functions/analyze-image.ts b/netlify/edge-functions/analyze-image.ts
@@ -53,7 +53,17 @@ export default async (request: Request) => {
 
 export const config = { path: "/api/analyze-image" };
 
-// Helper function to get brightness using ImageMagick
+/**
+ * Calculates the brightness of an image.
+ *
+ * @param data - The image data as a Uint8Array.
+ * @returns The average brightness of the image.
+ * @throws Will throw an error if reading the image fails.
+ *
+ * @example
+ * // How to use the function.
+ * const brightness = await getBrightness(fileData);
+ */
 async function getBrightness(data: Uint8Array): Promise<number> {
   let brightness = 0;
   await ImageMagick.read(data, (image: MagickImage) => {
@@ -80,7 +90,17 @@ async function getBrightness(data: Uint8Array): Promise<number> {
   return brightness;
 }
 
-// Custom function to get histogram data
+/**
+ * Generates the histogram of an image.
+ *
+ * @param data - The image data as a Uint8Array.
+ * @returns An object representing the histogram of the image.
+ * @throws Will throw an error if generating the histogram fails.
+ *
+ * @example
+ * // How to use the function.
+ * const histogram = getHistogram(fileData);
+ */
 function getHistogram(data: Uint8Array): Record<string, number> {
   const histogram: Record<string, number> = {};
   for (let i = 0; i < data.length; i += 4) {
diff --git a/netlify/edge-functions/crop-image.ts b/netlify/edge-functions/crop-image.ts
@@ -9,6 +9,17 @@ import {
 
 await initialize();
 
+/**
+ * Handles the image cropping request.
+ *
+ * @param request - The incoming HTTP request.
+ * @returns The HTTP response with the cropped image or an error message.
+ * @throws Will throw an error if the request method is not POST or if processing fails.
+ *
+ * @example
+ * // How to call the function.
+ * fetch('/api/crop-image', { method: 'POST', body: formData });
+ */
 export default async (request: Request) => {
   if (request.method === "POST") {
     try {
diff --git a/netlify/edge-functions/generate-thumbnail.ts b/netlify/edge-functions/generate-thumbnail.ts
@@ -9,6 +9,17 @@ import {
 
 await initialize();
 
+/**
+ * Handles the image thumbnail generation request.
+ *
+ * @param request - The incoming HTTP request.
+ * @returns The HTTP response with the generated thumbnail or an error message.
+ * @throws Will throw an error if the request method is not POST or if processing fails.
+ *
+ * @example
+ * // How to call the function.
+ * fetch('/api/generate-thumbnail', { method: 'POST', body: formData });
+ */
 export default async (request: Request) => {
   if (request.method === "POST") {
     try {
diff --git a/package.json b/package.json
