docs: update documentation to include typescript examples

Author: wollardj

.travis.yml

@@ -2,6 +2,7 @@
   "recommendations": [
     "arcanis.vscode-zipfs",
     "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode"
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker"
   ]
 }

.vscode/extensions.json

@@ -6,5 +6,6 @@
   "eslint.nodePath": ".yarn/sdks",
   "prettier.prettierPath": ".yarn/sdks/prettier/index.js",
   "typescript.tsdk": ".yarn/sdks/typescript/lib",
-  "typescript.enablePromptUseWorkspaceTsdk": true
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "cSpell.words": ["bplist"]
 }

.vscode/settings.json

@@ -2,9 +2,9 @@
 
 [![npm](https://img.shields.io/npm/dw/simple-plist.svg?style=popout&logo=npm)](https://www.npmjs.org/package/simple-plist)
 [![npm](https://img.shields.io/npm/v/simple-plist.svg?style=popout&logo=npm)](https://www.npmjs.com/package/simple-plist)
-[![Travis (.com) branch](https://img.shields.io/travis/com/wollardj/node-simple-plist/develop.svg?style=popout&logo=Travis%20CI)](https://travis-ci.com/wollardj/node-simple-plist)
 
-A simple API for interacting with binary and plain text plist data.
+A simple API for interacting with binary and plain text
+[plist](https://en.wikipedia.org/wiki/Property_list) data.
 
 ## Installation
 
@@ -16,63 +16,115 @@ npm install simple-plist
 yarn add simple-plist
 ```
 
-## Reading Data
+## Synchronous API
 
 ```js
-var plist = require("simple-plist");
-
-// Read data from a file (xml or binary) (asynchronous)
-plist.readFile("/path/to/some.plist", function (err, data) {
-  if (err) {
-    throw err;
-  }
-  console.log(JSON.stringify(data));
-});
-
-// Read data from a file (xml or binary) (synchronous)
-var data = plist.readFileSync("/path/to/some.plist");
-console.log(JSON.stringify(data));
+const plist = require("simple-plist");
+
+let data;
+
+// read
+data = plist.readFileSync("/path/to/some.plist");
+
+// write xml
+plist.writeFileSync("/path/to/plaintext.plist", data);
+
+// write binary
+plist.writeBinaryFileSync("/path/to/binary.plist", data);
 ```
 
-## Writing Data
+## Asynchronous API
+
+> Note: all of the async examples can optionally be converted to promises using
+> node's [`util.promisify`](https://nodejs.org/dist/latest-v8.x/docs/api/util.html#util_util_promisify_original).
 
 ```js
-var plist = require("simple-plist"),
-  data = plist.readFileSync("/path/to/some.plist");
+const plist = require("simple-plist");
 
-// Write data to a xml file (asynchronous)
-plist.writeFile("/path/to/plaintext.plist", data, function (err) {
-  if (err) {
-    throw err;
-  }
-});
+let data;
 
-// Write data to a xml file (synchronous)
-plist.writeFileSync("/path/to/plaintext.plist", data);
+function callback(err, contents) {
+  if (err) throw err;
+  data = contents;
+}
 
-// Write data to a binary plist file (asynchronous)
-plist.writeBinaryFile("/path/to/binary.plist", data, function (err) {
-  if (err) {
-    throw err;
-  }
-});
+// read
+plist.readFile("/path/to/some.plist", callback);
 
-// Write data to a binary plist file (synchronous)
-plist.writeBinaryFileSync("/path/to/binary.plist", data);
+// write xml
+plist.writeFile("/path/to/plaintext.plist", data, callback);
+
+// write binary
+plist.writeBinaryFile("/path/to/binary.plist", data, callback);
 ```
 
-## Mutating Plists In Memory
+## In Memory
+
+### `plist.stringify()`
 
 ```js
-var plist = require("simple-plist");
+const plist = require("simple-plist");
+
+// Convert an object to a plist xml string
+plist.stringify({ name: "Joe", answer: 42 });
+
+/*
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>name</key>
+    <string>Joe</string>
+    <key>answer</key>
+    <integer>42</integer>
+  </dict>
+</plist>
+*/
+```
+
+### `plist.parse()`
+
+```js
+const plist = require("simple-plist");
+
+const xml = `<plist>
+	<dict>
+		<key>name</key>
+		<string>Joe</string>
+	</dict>
+</plist>`;
+
+plist.parse(xml);
+// { "name": "Joe" }
+```
+
+## TypeScript Support
+
+All functions have typescript signatures, but there are a few handy generics
+that are worth pointing out. Those generics belong to `parse`, `readFile`,
+and `readFileSync`. Here's an example:
+
+```tsx
+import { parse, readFile, readFileSync } from "simple-plist";
+
+type Profile = {
+  name: string;
+  answer: number;
+};
+
+const xml = `<plist>
+	<dict>
+		<key>name</key>
+		<string>Joe</string>
+		<key>answer</key>
+		<integer>42</integer>
+	</dict>
+</plist>`;
 
-// Convert a Javascript object to a plist xml string
-var xml = plist.stringify({ name: "Joe", answer: 42 });
-console.log(xml); // output is a valid plist xml string
+// typed string parsing
+const { answer } = parse<Profile>(xml);
+// answer = 42;
 
-// Convert a plist xml string or a binary plist buffer to a Javascript object
-var data = plist.parse(
-  "<plist><dict><key>name</key><string>Joe</string></dict></plist>"
-);
-console.log(JSON.stringify(data));
+// typed file loading
+const { name } = readFileSync<Profile>("/path/to/profile.plist");
 ```

README.md

@@ -8,9 +8,20 @@ import { writeBinaryFile } from "./writeBinaryFile";
 import { writeBinaryFileSync } from "./writeBinaryFileSync";
 import { writeFile } from "./writeFile";
 import { writeFileSync } from "./writeFileSync";
-export type { PlistJsObj, StringOrBuffer, callbackFn } from "./types";
 
-export default {
+// "modern" named exports
+export { parse } from "./parse";
+export { readFile } from "./readFile";
+export { readFileSync } from "./readFileSync";
+export { stringify } from "./stringify";
+export type { callbackFn, PlistJsObj, StringOrBuffer } from "./types";
+export { writeBinaryFile } from "./writeBinaryFile";
+export { writeBinaryFileSync } from "./writeBinaryFileSync";
+export { writeFile } from "./writeFile";
+export { writeFileSync } from "./writeFileSync";
+
+// preserve backwards compatibility
+module.exports = {
   bplistCreator,
   bplistParser,
   parse,

src/index.ts

@@ -1,7 +1,7 @@
 import fs, { PathOrFileDescriptor } from "fs";
 import { parse } from "./parse";
 
-export function readFileSync<T = unknown>(aFile: PathOrFileDescriptor) {
+export function readFileSync<T = unknown>(aFile: PathOrFileDescriptor): T {
   const contents = fs.readFileSync(aFile);
   if (contents.length === 0) {
     return {} as Record<any, any>;

src/readFileSync.ts

@@ -6,7 +6,7 @@
     "target": "es5" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
 
     /* Modules */
-    "module": "amd" /* Specify what module code is generated. */,
+    "module": "UMD" /* Specify what module code is generated. */,
     "moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
 
     /* JavaScript Support */