Update API: export { riffChunks, findChunk };

rochars · Jul 13, 2018 · fe5154d · fe5154d
1 parent f17a0fa
commit fe5154d
Show file tree

Hide file tree

Showing 14 changed files with 868 additions and 387 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,8 @@
 # CHANGELOG
 
+## 9.0.0 (2018-07-13)
+- API change: export {riffChunks, findChunk}.
+
 ## 8.0.2 (2018-06-27)
 - Using only dot notation to allow better compilation on hosts.
 

diff --git a/README.md b/README.md
@@ -14,25 +14,25 @@ npm install riff-chunks
 
 ## Use
 
-### ES6
-```javascript
-import riffChunks from 'riff-chunks';
-let chunks = riffChunks(riffFileBuffer);
-```
-
 ### Node
 ```javascript
-const riffChunks = require("riff-chunks");
+const riffChunks = require("riff-chunks").riffChunks;
 const fs = require("fs");
 let chunks = riffChunks(fs.readFileSync("file.wav"));
 ```
 
+### ES6
+```javascript
+import {riffChunks} from 'riff-chunks';
+let chunks = riffChunks(riffFileBuffer);
+```
+
 ### Browser
 Use the compiled file in the */dist* folder:
 ```html
 <script src="riff-chunks.min.js"></script>
 <script>
-var chunks = riffChunks(riffFileBuffer);
+var chunks = riffChunks.riffChunks(riffFileBuffer);
 </script>
 ```
 
@@ -49,7 +49,7 @@ Or get it from [unpkg](https://www.unpkg.com):
 Or as a ES6 module in modern browsers from [jspm](https://jspm.io):
 ```html
 <script type="module">
-  import riffChunks from 'https://dev.jspm.io/riff-chunks';
+  import {riffChunks} from 'https://dev.jspm.io/riff-chunks';
   // ...
 </script>
 ```
@@ -60,10 +60,21 @@ Or as a ES6 module in modern browsers from [jspm](https://jspm.io):
 ```javascript
 /**
  * Return the chunks in a RIFF/RIFX file.
- * @param {!Uint8Array|!Array<number>} buffer The file bytes.
+ * @param {!Uint8Array} buffer The file bytes.
  * @return {!Object} The RIFF chunks.
  */
-function riffChunks(buffer) {}
+export function riffChunks(buffer) {}
+
+/**
+ * Find a chunk by its fourCC_ in a array of RIFF chunks.
+ * @param {!Object} chunks The wav file chunks.
+ * @param {string} chunkId The chunk fourCC_.
+ * @param {boolean} multiple True if there may be multiple chunks
+ *    with the same chunkId.
+ * @return {?Array<!Object>}
+ * @private
+ */
+export function findChunk(chunks, chunkId, multiple=false) {}
 ```
 
 **riffChunks()** returns a object like this:
@@ -85,17 +96,36 @@ function riffChunks(buffer) {}
 }
 ```
 
-The **chunkData** field contains the raw bytes of the chunk data.
-
 ## Distribution
-This library is a ES6 module also distributed as a CommonJS module, UMD and a compiled script for browsers.
+This library is a ES module also distributed as a CommonJS module, UMD module and a compiled script for browsers. It works out of the box in Node when installed with ```npm install riff-chunks```.
+
+### If you are using this lib in a browser:
+
+You may load both **./dist/riff-chunks.umd.js** and **./dist/riff-chunks.min.js** in the browser with ```<script>``` tags. Ideally you should use **riff-chunks.min.js**. You can load it via the https://unpkg.com and https://www.jsdelivr.com/ CDNs:
+
+[unpkg](https://unpkg.com/riff-chunks):
+```html
+<script src="https://unpkg.com/riff-chunks"></script>
+```
+
+[jsDelivr](https://cdn.jsdelivr.net/npm/riff-chunks):
+```html
+<script src="https://cdn.jsdelivr.net/npm/riff-chunks"></script>
+```
+
+### If you are using this lib as a dependency:
+
+- The **CommonJS** dist is **./dist/riff-chunks.cjs.js**. It is the dist file used by Node. It is served in the "main" field of package.json and is the source you are running when you **npm install riff-chunks**. It is not compiled or minified.
+
+- The **UMD** module is **./dist/riff-chunks.umd.js**. It is transpiled to ES5 and compatible with Node, AMD and browsers. It is served in the "browser" field of package.json.
+
+- The **browser-only** dist is **./dist/riff-chunks.min.js**. It is transpiled to ES5 and compiled. It is used in the "unpkg" and "jsdelivr" fields of package.json.
+
+- The **ES6 bundle** is **./dist/riff-chunks.js**, served as "es2015" in package.json. It is not compiled/minified.
 
-- The **CommonJS** is the one used by Node. It is served in the "main" field of package.json
-- The **UMD** module is compatible with Node, AMD and browsers. It is served in the "browser" field.
-- The **compiled dist** is browser-only and should be the one served by CDNs.
-- The **ES6** dist is **riff-chunks.js**, served as "module" in package.json
+- **./main.js** is served as "module" in package.json. This should be the entry point for bundlers.
 
-You may load both **riff-chunks.umd.js** and **riff-chunks.min.js** in the browser with ```<script>``` tags.
+If your module bundler is using "browser" as the entry point **your dist should work the same** but will be a larger file.
 
 ## LICENSE
 Copyright (c) 2017-2018 Rafael da Silva Rocha.

diff --git a/dist/README.md b/dist/README.md
@@ -1,10 +1,30 @@
 # Distribution
+This library is a ES module also distributed as a CommonJS module, UMD module and a compiled script for browsers. It works out of the box in Node when installed with ```npm install riff-chunks```.
 
-This library is a ES6 module also distributed as a CommonJS module, UMD and a compiled script for browsers.
+## If you are using this lib in a browser:
 
-- The **CommonJS** is the one used by Node. It is served in the "main" field of package.json
-- The **UMD** module is compatible with Node, AMD and browsers. It is served in the "browser" field.
-- The **compiled dist** is browser-only and should be the one served by CDNs.
-- The **ES6** dist is **riff-chunks.js**, served as "module" in package.json
+You may load both **./dist/riff-chunks.umd.js** and **./dist/riff-chunks.min.js** in the browser with ```<script>``` tags. Ideally you should use **riff-chunks.min.js**. You can load it via the https://unpkg.com and https://www.jsdelivr.com/ CDNs:
 
-You may load both **riff-chunks.umd.js** and **riff-chunks.min.js** in the browser with ```<script>``` tags.
+[unpkg](https://unpkg.com/riff-chunks):
+```html
+<script src="https://unpkg.com/riff-chunks"></script>
+```
+
+[jsDelivr](https://cdn.jsdelivr.net/npm/riff-chunks):
+```html
+<script src="https://cdn.jsdelivr.net/npm/riff-chunks"></script>
+```
+
+## If you are using this lib as a dependency:
+
+- The **CommonJS** dist is **./dist/riff-chunks.cjs.js**. It is the dist file used by Node. It is served in the "main" field of package.json and is the source you are running when you **npm install riff-chunks**. It is not compiled or minified.
+
+- The **UMD** module is **./dist/riff-chunks.umd.js**. It is transpiled to ES5 and compatible with Node, AMD and browsers. It is served in the "browser" field of package.json.
+
+- The **browser-only** dist is **./dist/riff-chunks.min.js**. It is transpiled to ES5 and compiled. It is used in the "unpkg" and "jsdelivr" fields of package.json.
+
+- The **ES6 bundle** is **./dist/riff-chunks.js**, served as "es2015" in package.json. It is not compiled/minified.
+
+- **./main.js** is served as "module" in package.json. This should be the entry point for bundlers.
+
+If your module bundler is using "browser" as the entry point **your dist should work the same** but will be a larger file.
diff --git a/dist/riff-chunks.cjs.js b/dist/riff-chunks.cjs.js
@@ -1,11 +1,10 @@
 'use strict';
 
+Object.defineProperty(exports, '__esModule', { value: true });
+
 var byteData = require('byte-data');
 
 /*
- * riff-chunks: Read and write the chunks of RIFF and RIFX files.
- * https://github.com/rochars/riff-chunks
- *
  * Copyright (c) 2017-2018 Rafael da Silva Rocha.
  *
  * Permission is hereby granted, free of charge, to any person obtaining
@@ -53,6 +52,32 @@ function riffChunks(buffer) {
     };
 }
 
+/**
+  * Find a chunk by its fourCC_ in a array of RIFF chunks.
+  * @param {!Object} chunks The wav file chunks.
+  * @param {string} chunkId The chunk fourCC_.
+  * @param {boolean} multiple True if there may be multiple chunks
+  *    with the same chunkId.
+  * @return {?Array<!Object>}
+  */
+function findChunk(chunks, chunkId, multiple=false) {
+  /** @type {!Array<!Object>} */
+  let chunk = [];
+  for (let i=0; i<chunks.length; i++) {
+    if (chunks[i].chunkId == chunkId) {
+      if (multiple) {
+        chunk.push(chunks[i]);
+      } else {
+        return chunks[i];
+      }
+    }
+  }
+  if (chunkId == 'LIST') {
+    return chunk.length ? chunk : null;
+  }
+  return null;
+}
+
 /**
  * Return the sub chunks of a RIFF file.
  * @param {!Uint8Array} buffer the RIFF file bytes.
@@ -122,4 +147,5 @@ function getChunkSize_(buffer, index) {
     return byteData.unpackFrom(buffer, uInt32_, index + 4);
 }
 
-module.exports = riffChunks;
+exports.riffChunks = riffChunks;
+exports.findChunk = findChunk;