fix: buffer reading in the browser environment

rewrite typescript to mjs with jsdocs to make bundle smaller
add missing engines compatibility info to package.json

Author: FRSgit

README.md

@@ -13,7 +13,7 @@
   </a>
 </p>
 
-<h1 align="center">is-animated - checks if the image is animated 🎞</h1>
+<h1 align="center">is-animated - check if the image is animated 🎞</h1>
 
 <p align="center">
   <a href="#quick-start">Getting Started</a>
@@ -31,8 +31,8 @@
   <i>A simple library for detecting animated images.
     <br>Works under Node and Browser environments!
     <br>Performant & with small bundle size
-    <br>Supports GIF, APNG and WebP
-    <br>Written completely in <a href="https://www.typescriptlang.org">typescript</a>
+    <br>Supports GIF, PNG, APNG and WebP
+    <br>Fully typed in <a href="https://www.typescriptlang.org">Typescript</a>
     <br>Published under <a href="https://opensource.org/licenses/MIT" target="_blank">MIT</a> license</i>
   <br>
   <br>
@@ -57,27 +57,34 @@ pnpm add @frsource/is-animated
 ```
 
 ```ts
+import isAnimated from '@frsource/is-animated';
+
 const input = document.querySelector('input[type="file"]');
 
 input.addEventListener('change', async function () {
   const arrayBuffer = await this.files[0].arrayBuffer();
-  const answer = isAnimated(arrayBuffer) ? 'Yes' : 'No';
-  alert(`Is "${this.files[0].name}" animated? ${answer}.`);
+  const answer = isAnimated(arrayBuffer) ? 'IS' : 'IS NOT';
+  alert(`File "${this.files[0].name}" ${answer} animated.`);
 });
 ```
 
+>If you prefer, you can import this library using unpkg:
+>`<script defer src="https://unpkg.com/@frsource/is-animated"></script>`
+
 ### Usage in Node.js
 
 ```ts
 import { readFileSync } from 'fs';
 import isAnimated from '@frsource/is-animated';
 
 readFileSync('my-test-file.png', (err, buffer) => {
-  const answer = isAnimated(buffer) ? 'Yes' : 'No';
-  console.log(`Is "my-test-file.png" animated? ${answer}.`);
+  const answer = isAnimated(buffer) ? 'IS' : 'IS NOT';
+  console.log(`File "my-test-file.png" ${answer} animated.`);
 });
 ```
 
+## Demo
+
 For a working example, check out [our demo](https://www.frsource.org/is-animated#demo).
 
 ## Questions

eslint.config.mjs

@@ -1,10 +1,10 @@
 import globals from 'globals';
 import { typescript } from '@frsource/eslint-config';
 
-/** @type {import("eslint").Linter.FlatConfig[]} */
+/** @type {import("eslint").Linter.Config[]} */
 export default [
   ...typescript,
-  { ignores: ['**/dist', '**/coverage', '**/node_modules'] },
+  { ignores: ['**/dist', '**/coverage', '**/node_modules', '**/docs'] },
   { languageOptions: { globals: globals.node } },
   {
     files: ['scripts/index.tpl.js'],

package.json

@@ -3,29 +3,26 @@
   "version": "1.0.2",
   "description": "Detects animated images in browser & node. Supports GIT, APNG & WebP",
   "sideEffects": false,
-  "source": "src/index.ts",
   "exports": {
-    "require": "./dist/index.js",
-    "types": "./dist/index.d.ts",
-    "default": "./dist/index.modern.mjs"
+    "default": "./src/index.mjs"
   },
-  "main": "./dist/index.js",
-  "module": "./dist/index.modern.mjs",
-  "unpkg": "./dist/index.umd.js",
-  "types": "./dist/index.d.ts",
+  "main": "./src/index.mjs",
+  "module": "./src/index.mjs",
+  "unpkg": "./dist/is-animated.umd.js",
   "scripts": {
-    "start": "pnpm clean && concurrently \"microbundle watch\" \"node ./scripts/build-docs.mjs --watch\" \"serve docs\"",
-    "build": "pnpm clean && microbundle --compress && node ./scripts/build-docs.mjs",
+    "typecheck": "tsc --project tsconfig.json",
+    "start": "pnpm clean && concurrently \"microbundle watch -i ./src/index.mjs -o docs -f umd\" \"node ./scripts/build-docs.mjs --watch\" \"serve docs\"",
+    "build": "pnpm clean && microbundle -i ./src/index.mjs -o dist -f umd && microbundle -i ./src/index.mjs -o docs -f umd && node ./scripts/build-docs.mjs",
     "lint": "eslint . --max-warnings 0 && prettier --check .",
     "fix": "eslint . --fix && prettier --write .",
     "release": "semantic-release",
     "release:ci": "pnpm release --yes",
     "release:test": "pnpm release --no-git-tag-version --no-push --skip-npm",
-    "clean": "pnpm rimraf \"dist/**/*\"",
+    "clean": "pnpm rimraf dist docs",
     "test": "pnpm vitest",
     "coverage": "pnpm vitest --coverage"
   },
-  "homepage": "https://github.com/FRSOURCE/is-animated/",
+  "homepage": "https://www.frsource.org/is-animated",
   "bugs": {
     "url": "https://github.com/FRSOURCE/is-animated/issues"
   },
@@ -78,7 +75,12 @@
   "packageManager": "pnpm@8.15.8",
   "files": [
     "dist",
+    "src/*.mjs",
+    "src/*/*.mjs",
     "package.json"
   ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "funding": "https://buymeacoffee.com/frsource"
 }

scripts/index.tpl.html

@@ -123,9 +123,14 @@ <h4>In browser</h4>
 
 input.addEventListener('change', async function () {
   const arrayBuffer = await this.files[0].arrayBuffer();
-  const answer = isAnimated(arrayBuffer) ? 'Yes' : 'No';
-  alert(`Is "${this.files[0].name}" animated? ${answer}.`);
+  const answer = isAnimated(arrayBuffer) ? 'IS' : 'IS NOT';
+  alert(`File "${this.files[0].name}" ${answer} animated.`);
 });</code></pre>
+
+        <blockquote>
+          <p>If you prefer, you can import this library using unpkg:</p>
+          <pre><code data-lang="html">&lt;script defer src="https://unpkg.com/@frsource/is-animated"&gt;&lt;/script&gt;</code></pre>
+        </blockquote>
       </section>
       <section>
         <h4>In Node.js</h4>
@@ -134,8 +139,8 @@ <h4>In Node.js</h4>
 import isAnimated from '@frsource/is-animated';
 
 const buffer = readFileSync('my-test-file.png');
-const answer = isAnimated(buffer) ? 'Yes' : 'No';
-console.log(`Is "my-test-file.png" animated? ${answer}.`);</code></pre>
+const answer = isAnimated(buffer) ? 'IS' : 'IS NOT';
+console.log(`File "my-test-file.png" ${answer} animated.`);</code></pre>
       </section>
     </main>
     <hr />
@@ -150,8 +155,7 @@ <h4>In Node.js</h4>
         >
       </small>
     </footer>
-    <script defer src="https://unpkg.com/@frsource/is-animated"></script>
-    <script defer src="../dist/index.umd.js"></script>
-    <script defer src="./index.js"></script>
+    <script defer src="is-animated.umd.js"></script>
+    <script defer src="index.js"></script>
   </body>
 </html>

scripts/index.tpl.js

@@ -2,6 +2,6 @@ const input = document.querySelector('input[type="file"]');
 
 input.addEventListener('change', async function () {
   const arrayBuffer = await this.files[0].arrayBuffer();
-  const answer = isAnimated(arrayBuffer) ? 'Yes' : 'No';
-  alert(`Is "${this.files[0].name}" animated? ${answer}.`);
+  const answer = isAnimated(arrayBuffer) ? 'IS' : 'IS NOT';
+  alert(`File "${this.files[0].name}" ${answer} animated.`);
 });

src/index.ts src/index.mjssrc/index.ts renamed to src/index.mjs

@@ -1,11 +1,16 @@
-import * as gif from './utils/gif';
-import * as webp from './utils/webp';
-import * as png from './utils/png';
-import type { NodeBufferOrArrayBuffer, StandardisedBuffer } from './types';
+import * as gif from './utils/gif.mjs';
+import * as webp from './utils/webp.mjs';
+import * as png from './utils/png.mjs';
 
-const toStandardisedBuffer = (
-  buffer: NodeBufferOrArrayBuffer,
-): StandardisedBuffer => {
+/** @typedef {import('./types.mjs').NodeBufferOrArrayBuffer} NodeBufferOrArrayBuffer */
+/** @typedef {import('./types.mjs').StandardisedBuffer} StandardisedBuffer */
+
+/**
+ * Converts Node.js/Web buffer into an unified one with a standardized API
+ * @param {NodeBufferOrArrayBuffer} buffer
+ * @returns {StandardisedBuffer}
+ */
+const toStandardisedBuffer = (buffer) => {
   if ('subarray' in buffer) {
     return {
       read: (begin, end, { encoding = 'utf8' } = {}) =>
@@ -17,18 +22,21 @@ const toStandardisedBuffer = (
   }
 
   const decoder = new TextDecoder();
-  const array = new Uint8Array(buffer as ArrayBuffer);
+  const array = new Uint8Array(/** @type {ArrayBuffer} */ (buffer));
   return {
     read: (begin, end, { encoding = 'utf8' } = {}) => {
       if (encoding === 'utf8')
-        return decoder.decode(buffer.slice(begin, end) as ArrayBuffer);
-      return [...array.slice(begin, end)]
+        return decoder.decode(
+          /** @type {ArrayBuffer} */ (buffer.slice(begin, end)),
+        );
+      return Array.from(array.slice(begin, end))
         .map((x) => x.toString(16).padStart(2, '0'))
         .join('');
     },
     readUInt32BE: (offset) =>
       new DataView(
-        buffer as ArrayBuffer,
+        /** @type {ArrayBuffer} */
+        (buffer),
         array.byteOffset,
         array.byteLength,
       ).getUint32(offset),
@@ -39,8 +47,9 @@ const toStandardisedBuffer = (
 
 /**
  * Checks if buffer contains animated image
+ * @param {NodeBufferOrArrayBuffer} buffer
  */
-export default function isAnimated(buffer: NodeBufferOrArrayBuffer) {
+export default function isAnimated(buffer) {
   const standardisedBuffer = toStandardisedBuffer(buffer);
   if (gif.isGIF(standardisedBuffer)) return gif.isAnimated(standardisedBuffer);
   if (png.isPNG(standardisedBuffer)) return png.isAnimated(standardisedBuffer);

src/index.spec.ts

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, extname, basename } from 'node:path';
 import { File } from 'happy-dom';
 import { it, describe } from 'vitest';
-import isAnimated from './index';
+import isAnimated from './index.mjs';
 
 const types = ['gif', 'png', 'webp'];
 const environmentTypes = ['browser', 'nodejs'];

src/types.mjs

@@ -0,0 +1,23 @@
+/**
+ * @typedef {{ slice(begin: number, end?: number): unknown }} ArrayBufferLike
+ * @typedef {{
+ *  subarray(begin: number, end?: number): NodeBufferLike;
+ *  readUInt32BE(offset: number): number;
+ *  toString(encoding: 'hex' | 'utf8'): string;
+ *  [index: number]: number;
+ *  readonly length: number;
+ * }} NodeBufferLike
+ * @typedef {ArrayBufferLike | NodeBufferLike} NodeBufferOrArrayBuffer
+ * @typedef {{
+ *   read(
+ *     begin: number,
+ *     end?: number,
+ *     opts?: {
+ *       encoding?: 'utf8' | 'hex';
+ *     },
+ *   ): string;
+ *   readUInt32BE(offset: number): number;
+ *   at(index: number): number;
+ *   length: number;
+ * }} StandardisedBuffer
+ */

src/types.ts

@@ -1,9 +1,11 @@
-import type { StandardisedBuffer } from '../types';
+/** @typedef {import('../types.mjs').StandardisedBuffer} StandardisedBuffer */
 
 /**
  * Returns total length of data blocks sequence
+ * @param {StandardisedBuffer} buffer
+ * @param {number} offset
  */
-function getDataBlocksLength(buffer: StandardisedBuffer, offset: number) {
+function getDataBlocksLength(buffer, offset) {
   let length = 0;
 
   while (buffer.at(offset + length)) {
@@ -15,14 +17,15 @@ function getDataBlocksLength(buffer: StandardisedBuffer, offset: number) {
 
 /**
  * Checks if buffer contains GIF image
+ * @param {StandardisedBuffer} buffer
  */
-export const isGIF = (buffer: StandardisedBuffer) =>
-  buffer.read(0, 3) === 'GIF';
+export const isGIF = (buffer) => buffer.read(0, 3) === 'GIF';
 
 /**
  * Checks if buffer contains animated GIF image
+ * @param {StandardisedBuffer} buffer
  */
-export const isAnimated = (buffer: StandardisedBuffer) => {
+export const isAnimated = (buffer) => {
   let hasColorTable, colorTableSize;
   let offset = 0;
   let imagesCount = 0;