fix: add module.exports CJS syntax, add example with require (#87)

aeworxet · web-flow · commit 3a16720d127c · 2022-10-26T14:07:24.000+02:00
diff --git a/API.md b/API.md
@@ -65,7 +65,8 @@ console.log(document.string()); // get JSON string
 | [options.referenceIntoComponents] | <code>boolean</code> | <p>Pass <code>true</code> to resolve external references to components.</p> |
 
 **Example**  
-```js
+**TypeScript**
+```ts
 import { readFileSync, writeFileSync } from 'fs';
 import bundle from '@asyncapi/bundler';
 
@@ -80,3 +81,37 @@ async function main() {
 
 main().catch(e => console.error(e));
 ```
+
+**JavaScript CJS module system**
+```js
+'use strict';
+
+const { readFileSync, writeFileSync } = require('fs');
+const bundle = require('@asyncapi/bundler');
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
+```
+
+**JavaScript ESM module system**
+```js
+'use strict';
+
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e)); 
+```
diff --git a/README.md b/README.md
@@ -163,9 +163,11 @@ npm install @asyncapi/bundler
 
 AsyncAPI Bundler can be easily used within your JavaScript projects as a Node.js module:
 
-```ts
-import { readFileSync, writeFileSync } from 'fs';
-import bundle from '@asyncapi/bundler';
+```js
+'use strict';
+
+const { readFileSync, writeFileSync } = require('fs');
+const bundle = require('@asyncapi/bundler');
 
 async function main() {
   const filePaths = ['./camera.yml','./audio.yml'];
@@ -264,9 +266,9 @@ components:
 
 ```
 </details>
+<br />
 
-</br>
-
+**TypeScript**
 ```ts
 import { readFileSync, writeFileSync } from 'fs';
 import bundle from '@asyncapi/bundler';
@@ -281,9 +283,42 @@ async function main() {
 }
 
 main().catch(e => console.error(e));
- 
 ```
 
+**JavaScript CJS module system**
+```js
+'use strict';
+
+const { readFileSync, writeFileSync } = require('fs');
+const bundle = require('@asyncapi/bundler');
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
+```
+
+**JavaScript ESM module system**
+```js
+'use strict';
+
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e)); 
+
+```
 
 <a name="bundle"></a>
 
diff --git a/example/bundle-cjs.cjs b/example/bundle-cjs.cjs
@@ -0,0 +1,18 @@
+/**
+ * In case `.cjs` extension is used, Node.js will recognize CJS module system
+ * automatically.
+ */
+
+'use strict';
+
+const { readFileSync, writeFileSync } = require('fs');
+const bundle = require('@asyncapi/bundler');
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
diff --git a/example/bundle-cjs.js b/example/bundle-cjs.js
@@ -0,0 +1,20 @@
+/**
+ * To use `.js` extension with CJS module system, make sure
+ * `package.json`
+ * DOES NOT contain line
+ * `"type": "module",`
+ */
+
+'use strict';
+
+const { readFileSync, writeFileSync } = require('fs');
+const bundle = require('@asyncapi/bundler');
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
diff --git a/example/bundle-esm.js b/example/bundle-esm.js
@@ -0,0 +1,20 @@
+/**
+ * To use `.js` extension with ESM module system, first add to
+ * `package.json`
+ * line
+ * `"type": "module",`
+ */
+
+'use strict';
+
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
diff --git a/example/bundle-esm.mjs b/example/bundle-esm.mjs
@@ -0,0 +1,18 @@
+/**
+ * In case `.mjs` extension is used, Node.js will recognize ESM module system
+ * automatically.
+ */
+
+'use strict';
+
+import { readFileSync, writeFileSync } from 'fs';
+import bundle from '@asyncapi/bundler';
+
+async function main() {
+  const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+    referenceIntoComponents: true,
+  });
+  writeFileSync('asyncapi.yaml', document.yml());
+}
+
+main().catch(e => console.error(e));
diff --git a/example/package.json b/example/package.json
@@ -4,13 +4,18 @@
   "description": "",
   "main": "index.js",
   "scripts": {
-    "dev": "node bundle.js"
+    "start": "npm run start:cjs && npm run start:esm && npm run start:ts",
+    "start:cjs": "node bundle-cjs.cjs",
+    "start:esm": "node bundle-esm.mjs",
+    "start:ts": "ts-node bundle.ts"
   },
   "keywords": [],
   "author": "",
   "license": "Apache-2.0",
   "dependencies": {
     "@asyncapi/bundler": "../",
-    "@types/node": "^18.7.23"
+    "@types/node": "^18.7.23",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.8.4"
   }
 }
diff --git a/example/tsconfig.json b/example/tsconfig.json
@@ -2,6 +2,7 @@
   "compilerOptions": {
     "types": [
       "node"
-    ]
+    ],
+    "esModuleInterop": true,
   }
 }
diff --git a/src/index.ts b/src/index.ts
@@ -5,15 +5,21 @@ import type { AsyncAPIObject } from './spec-types';
 
 /**
  *
- * @param {string[]} files Array of stringified AsyncAPI documents in YAML format, that are to be bundled (or array of filepaths, resolved and passed via `Array.map()` and `fs.readFileSync`, which is the same, see `README.md`).
+ * @param {string[]} files Array of stringified AsyncAPI documents in YAML
+ * format, that are to be bundled (or array of filepaths, resolved and passed
+ * via `Array.map()` and `fs.readFileSync`, which is the same, see `README.md`).
  * @param {Object} [options]
- * @param {string | object} [options.base] Base object whose properties will be retained.
- * @param {boolean} [options.referenceIntoComponents] Pass `true` to resolve external references to components.
+ * @param {string | object} [options.base] Base object whose properties will be
+ * retained.
+ * @param {boolean} [options.referenceIntoComponents] Pass `true` to resolve
+ * external references to components.
  *
  * @return {Document}
  *
  * @example
  *
+ * **TypeScript**
+ * ```ts
  * import { readFileSync, writeFileSync } from 'fs';
  * import bundle from '@asyncapi/bundler';
  *
@@ -27,6 +33,41 @@ import type { AsyncAPIObject } from './spec-types';
  * }
  *
  * main().catch(e => console.error(e));
+ * ```
+ *
+ * **JavaScript CJS module system**
+ * ```js
+ * 'use strict';
+ *
+ * const { readFileSync, writeFileSync } = require('fs');
+ * const bundle = require('@asyncapi/bundler');
+ *
+ * async function main() {
+ *   const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+ *     referenceIntoComponents: true,
+ *   });
+ *   writeFileSync('asyncapi.yaml', document.yml());
+ * }
+ *
+ * main().catch(e => console.error(e));
+ * ```
+ *
+ * **JavaScript ESM module system**
+ * ```js
+ * 'use strict';
+ *
+ * import { readFileSync, writeFileSync } from 'fs';
+ * import bundle from '@asyncapi/bundler';
+ *
+ * async function main() {
+ *   const document = await bundle([readFileSync('./main.yaml', 'utf-8')], {
+ *     referenceIntoComponents: true,
+ *   });
+ *   writeFileSync('asyncapi.yaml', document.yml());
+ * }
+ *
+ * main().catch(e => console.error(e)); 
+ * ```
  *
  */
 export default async function bundle(files: string[], options: any = {}) {
@@ -47,4 +88,6 @@ export default async function bundle(files: string[], options: any = {}) {
   return new Document(resolvedJsons as AsyncAPIObject[], options.base);
 }
 
-export { Document };
+// 'module.exports' is added to maintain backward compatibility with Node.js
+// projects, that use CJS module system.
+module.exports = bundle;

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,7 @@`
`2`	`2`	`"compilerOptions": {`
`3`	`3`	`"types": [`
`4`	`4`	`"node"`
`5`		`- ]`
	`5`	`+ ],`
	`6`	`+ "esModuleInterop": true,`
`6`	`7`	`}`
`7`	`8`	`}`