docs: update docs and README

Josh-McFarlin · Feb 9, 2022 · 700e358 · 700e358
1 parent 7d33585
commit 700e358
Show file tree

Hide file tree

Showing 14 changed files with 208 additions and 162 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,6 +3,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- add supported content type fields to transformers
+- modify how transform defaults are set and their types
+- Simplify transformers by removing buffer dependency for external transformers, move sharp
+  transformer to examples, and create wasm transformer
+- **BREAKING**: Modified transformer to use a new function type, Sharp can no longer be passed in
+  as is
+
+### Docs
+
+- Updated docs to use new transformer format
+- Created multiple new examples for various transformers
+- Created documentation for new usage of Sharp
+
 ## [0.2.0] - 2022-01-26
 
 ### Docs

diff --git a/README.md b/README.md
@@ -4,7 +4,12 @@
 
 A React component for responsive images in Remix.
 
-This library turns:
+This library lets you:
+* Resize images to the minimum size needed for faster page loading
+* Transform images to more efficient file types for faster speed
+* Cache commonly requested assets for the best performance
+
+Turning:
 
 ```typescript jsx
 <Image
@@ -51,11 +56,6 @@ yarn add remix-image
 
 ## Other
 
-### Status
-
-At the moment this library is experimental and has not been used in a production environment.
-Further development is ongoing, but I welcome all pull-requests and issues created on GitHub.
-
 ### Credit
 
 This repo expands on the following gists by:

diff --git a/docs/docs/advanced/creating-a-cache.md b/docs/docs/advanced/creating-a-cache.md
@@ -22,25 +22,37 @@ export interface CacheConfig {
   tbd: number;
 }
 
+export enum CacheStatus {
+  /**
+   * The cache contains the key and it has not yet expired
+   */
+  HIT = "hit",
+  /**
+   * The cache contains the key but it has expired
+   */
+  STALE = "stale",
+  /**
+   * The cache does not contain the key
+   */
+  MISS = "miss",
+}
+
 export abstract class Cache {
   abstract config: CacheConfig;
 
   abstract has(key: string): Promise<boolean>;
 
-  abstract status(key: string): Promise<"hit" | "stale" | "miss">;
+  abstract status(key: string): Promise<CacheStatus>;
 
-  abstract get(key: string): Promise<{
-    resultImg: Buffer;
-    contentType: string;
-  } | null>;
+  abstract get(key: string): Promise<Uint8Array | null>;
 
-  abstract set(key: string, resultImg: Buffer): Promise<void>;
+  abstract set(key: string, resultImg: Uint8Array): Promise<void>;
 
   abstract clear(): Promise<void>;
 }
 ```
 
-You will then provide an instance of this class to the ‘cache’ field of the ‘loader’ config
+You will then provide an instance of this class to the `cache` field of the ‘loader’ config
 ```typescript jsx
 import type { LoaderFunction } from "remix";
 import { imageLoader } from "remix-image/server";
@@ -57,9 +69,10 @@ export const loader: LoaderFunction = ({ request }) => {
 };
 ```
 
-## Example
+## Examples
 
-To see an example, look at [`diskCache`](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/caches/diskCache) in the library.
+* [diskCache](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/caches/diskCache)
+* [memoryCache](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/caches/memoryCache)
 
 ## Show Off
 

diff --git a/docs/docs/advanced/creating-a-resolver.md b/docs/docs/advanced/creating-a-resolver.md
@@ -15,21 +15,15 @@ export type Resolver = (
   asset: string,
   url: string
 ) => Promise<{
-  buffer: Buffer;
-  contentType: string;
+  buffer: Uint8Array;
+  contentType: MimeType;
 }>;
 ```
 such as:
 ```typescript
-import { fsResolver, fetchResolver } from "remix-image/server";
+import { fsResolver, fetchResolver, Resolver } from "remix-image/server";
 
-export const myResolver = async (
-  asset: string,
-  src: string
-): Promise<{
-  buffer: Buffer;
-  contentType: string;
-}> => {
+export const myResolver: Resolver = async (asset, src) => {
   if (src.startsWith("/") && (src.length === 1 || src[1] !== "/")) {
     return fsResolver(asset, src);
   } else {
@@ -38,7 +32,7 @@ export const myResolver = async (
 };
 ```
 
-You will then provide this function to the ‘resolver’ field of the loader config
+You will then provide this function to the `resolver` field of the loader config
 ```typescript jsx
 import type { LoaderFunction } from "remix";
 import { imageLoader } from "remix-image/server";
@@ -55,9 +49,11 @@ export const loader: LoaderFunction = ({ request }) => {
 };
 ```
 
-## Example
+## Examples
 
-To see an example, look at [`fsResolver`](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/resolvers/fsResolver) in the library.
+* [fsResolver](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/resolvers/fsResolver)
+* [fetchResolver](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/resolvers/fetchResolver)
+* [kvResolver](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/resolvers/kvResolver)
 
 ## Show Off
 

diff --git a/docs/docs/advanced/creating-a-transformer.md b/docs/docs/advanced/creating-a-transformer.md
@@ -11,27 +11,21 @@ An example could be resizing images using Cloudinary or Cloudflare Images.
 
 To make your own, just make a class that follows the [Transformer format](https://github.com/Josh-McFarlin/remix-image/blob/master/src/types/transformer.ts):
 ```typescript
-import { JpegOptions, PngOptions, ResizeOptions, WebpOptions } from "sharp";
-
-export abstract class ImageTransformer {
-  abstract jpeg(options?: JpegOptions): this;
-  abstract png(options?: PngOptions): this;
-  abstract webp(options?: WebpOptions): this;
-
-  abstract resize(options: ResizeOptions): this;
-  abstract toBuffer(): Promise<Buffer>;
-}
-```
-
-**Note**: Transformers use Buffer, a default Node package that is not available on platforms like Cloudflare Workers.
-If you would like to use your custom transformer on these platforms, you will need to polyfill your custom transformer using a library like [`buffer`](https://www.npmjs.com/package/buffer).
-
-Then make a function that takes in a buffer as the single parameter, and creates an instance of your Transformer class
-```typescript
-export type TransformerMaker = (buffer: Buffer) => ImageTransformer;
+export type Transformer = {
+  name: string;
+  supportedInputs: Set<MimeType>;
+  supportedOutputs: Set<MimeType>;
+  transform: (
+    input: {
+      data: Uint8Array;
+      contentType: MimeType;
+    },
+    output: TransformOptions
+  ) => Promise<Uint8Array>;
+};
 ```
 
-You will then provide this function to the ‘transformer’ field of the ‘loader’ config
+You will then provide this object to the `transformer` field of the ‘loader’ config
 ```typescript jsx
 import type { LoaderFunction } from "remix";
 import { imageLoader } from "remix-image/server";
@@ -48,9 +42,11 @@ export const loader: LoaderFunction = ({ request }) => {
 };
 ```
 
-## Example
+## Examples
 
-To see an example, look at [`pureTransformer`](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/transformers/pureTransformer) in the library.
+* [pureTransformer](https://github.com/Josh-McFarlin/remix-image/tree/master/src/server/transformers/pureTransformer)
+* [sharp](https://github.com/Josh-McFarlin/remix-image/tree/master/examples/sharp/sharpTransformer)
+* [gif-resizer](https://github.com/Josh-McFarlin/remix-image/tree/master/examples/gif-resizer/gifTransformer)
 
 ## Show Off
 

diff --git a/docs/docs/component.md b/docs/docs/component.md
@@ -29,9 +29,10 @@ import { Image } from "remix-image";
 ```
 
 ## PropTypes
-|    Name    |                                Type                                | Required |   Default    |                                                                    Description                                                                    |
-|:----------:|:------------------------------------------------------------------:|:--------:|:------------:|:-------------------------------------------------------------------------------------------------------------------------------------------------:|
-|  loaderUrl |                               string                               |          | "/api/image" | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`.  |
-| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] |          |      []      |                           An array of responsive sizes. The resource route is not called if this prop is not provided.                            |
+|    Name    |                                Type                                | Required |   Default    |                                                                   Description                                                                    |
+|:----------:|:------------------------------------------------------------------:|:--------:|:------------:|:------------------------------------------------------------------------------------------------------------------------------------------------:|
+| loaderUrl  |                               string                               |          | "/api/image" | The path of the image loader resource route. The `loaderUrl` prop is optional if the resource route has been created at the path `"/api/image"`. |
+| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] |          |      []      |                           An array of responsive sizes. The resource route is not called if this prop is not provided.                           |
+|  options   |                          TransformOptions                          |          |              |                                TransformOptions that can be used to override the defaults provided to the loader.                                |
 
-**Note**: The `Image` component extends the native `img` element, so any props used with `img` can be provided to the `Image` component.
+**Note**: The `Image` component extends the native `img` element, so any props used with `img` can be provided to the `Image` component.
diff --git a/docs/docs/hook.md b/docs/docs/hook.md
@@ -29,8 +29,9 @@ const Image: React.FC<ImageProps> = ({
 ```
 
 ## Parameters
-|    Name    |                                Type                                | Required | Default |                   Description                   |
-|:----------:|:------------------------------------------------------------------:|:--------:|:-------:|:-----------------------------------------------:|
-|  imgProps  |                   ComponentPropsWithoutRef<"img">                  |     X    |         | The props to be passed to the base img element. |
-|  loaderUrl |                               string                               |     X    |    []   |   The path of the image loader resource route.  |
-| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] |          |    []   |          An array of responsive sizes.          |
+|    Name    |                                Type                                | Required | Default |                                     Description                                     |
+|:----------:|:------------------------------------------------------------------:|:--------:|:-------:|:-----------------------------------------------------------------------------------:|
+|  imgProps  |                          { src: string }                           |     X    |         |                   The props to be passed to the base img element.                   |
+| loaderUrl  |                               string                               |     X    |    []   |                    The path of the image loader resource route.                     |
+| responsive | { size: { width: number; height: number; }; maxWidth?: number; }[] |          |    []   |                            An array of responsive sizes.                            |
+|  options   |                          TransformOptions                          |          |         | TransformOptions that can be used to override the defaults provided to the loader.  |
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
@@ -8,7 +8,12 @@ sidebar_position: 1
 
 A React component for responsive images in Remix.
 
-This library turns:
+This library lets you:
+* Resize images to the minimum size needed for faster page loading
+* Transform images to more efficient file types for faster speed
+* Cache commonly requested assets for the best performance
+
+Turning:
 
 ```typescript jsx
 <Image