Merge c8d5342 into fe10710

.gitignore

@@ -24,3 +24,4 @@ lib
 
 # Project-specific
 **/__tests__/fixtures/*_report.docx
+~$*.docx

CHANGELOG.md

@@ -1,3 +1,18 @@
+## 4.0.0 (2020-04-12)
+
+* Removed Flow and switched entire codebase over to TypeScript. In the process a few minor soundness issues were fixed.
+
+* **Breaking change** Removed dependency on Node filesystem APIs so the library no longer needs a separate node and browser entrypoint, simplifying maintenance and development. This has the following implications for the public API, justifying the version bump to 4.0.0:
+  *  You can no longer provide image data as a path, and need to provide an `ArrayBuffer` or base64-encoded string instead.
+
+  *  You can no longer provide a template as a filesystem path, and you'll need to read it into a Buffer first.
+
+  * Removed `output: 'buffer'` argument. The output of `createReport` is now always a `Uint8Array`, unless the debug argument `_probe` is specified.
+
+
+The README and examples have also been updated to reflect the above changes.
+
+
 ## 3.1.1 (2019-8-20)
 
 * Avoid issue when a single paragraph contains `END-IF/FOR` for a previous loop and `IF/FOR` for a new one (#72).

README.md

@@ -15,6 +15,7 @@ Template-based docx report creation for both Node and the browser. ([See the blo
 * Define custom **aliases** for some commands (`ALIAS`) — useful for writing table templates!
 * Run all JavaScript in a **separate Node VM for security**
 * Include **literal XML**
+* Written in TypeScript, so ships with type definitions.
 * Plenty of **examples** in this repo (with Node, Webpack and Browserify)
 
 Contributions are welcome!
@@ -35,59 +36,36 @@ $ yarn add docx-templates
 
 ## Node usage
 
-Here is a (contrived) example, with report data injected directly as an object:
+Here is a simple example, with report data injected directly as an object:
 
 ```js
 import createReport from 'docx-templates';
+import fs from 'fs';
 
-createReport({
-  template: 'templates/myTemplate.docx',
-  output: 'reports/myReport.docx',
+const template = fs.readFileSync('myTemplate.docx');
+
+const buffer = createReport({
+  template,
   data: {
     name: 'John',
     surname: 'Appleseed',
   },
 });
-```
-
-This will create a report based on the input data at the specified path. Some notes:
 
-* All paths are relative to `process.cwd()`
-* If the output location is omitted, a report will be generated in the same folder as the template
+fs.writeFileSync('report.docx', buffer)
+```
 
 You can also **provide a sync or Promise-returning callback function (query resolver)** instead of a `data` object:
 
 ```js
 createReport({
-  template: 'templates/myTemplate.docx',
-  output: 'reports/myReport.docx',
+  template,
   data: query => graphqlServer.execute(query),
 });
 ```
 
 Your resolver callback will receive the query embedded in the template (in a `QUERY` command) as an argument.
 
-You can also **output to a buffer**:
-
-```js
-const buffer = await createReport({
-  output: 'buffer',
-  template: 'templates/myTemplate.docx',
-  data: { ... },
-});
-```
-
-...and **pass a buffer as an input `template`**:
-
-```js
-const template = // read from database, HTTP, etc. as a Buffer
-const buffer = await createReport({
-  output: 'buffer',
-  template,
-  data: { ... },
-});
-```
-
 Other options (with defaults):
 
 ```js
@@ -126,7 +104,7 @@ Check out the [Node examples folder](https://github.com/guigrpa/docx-templates/t
 
 ## Browser usage
 
-You can use docx-templates in the browser (yay!). Instead of providing docx-templates with the template's path, pass the template contents as a buffer. For example, get a File object with:
+You can use docx-templates in the browser (yay!). Just as when using docx-templates in Node, you need to provide the template contents as a buffer-like object. For example, you can get a `File` object with:
 
 ```html
 <input type="file">
@@ -301,12 +279,9 @@ The JS snippet must return an _image object_ or a Promise of an _image object_,
 
 * `width` in cm
 * `height` in cm
-* `path` _[optional]_ (in Node only): path to the image to be embedded (absolute or relative to the current working directory)
-* `data` _[optional]_: either an ArrayBuffer or a base64 string with the image data
+* `data`: either an ArrayBuffer or a base64 string with the image data
 * `extension` _[optional]_: e.g. `.png`
 
-Either specify the `path` or `data` + `extension`.
-
 ### `LINK`
 
 Includes a hyperlink with the data resulting from evaluating a JavaScript snippet: