diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index fa9b309..0000000 --- a/.travis.yml +++ /dev/null @@ -1,10 +0,0 @@ -language: node_js - -node_js: - - 10 - - 12 - - 14 - - 16 - -script: - - yarn test diff --git a/.vscode/extensions.json b/.vscode/extensions.json index daaa5ee..23d0bb3 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -2,6 +2,7 @@ "recommendations": [ "arcanis.vscode-zipfs", "dbaeumer.vscode-eslint", - "esbenp.prettier-vscode" + "esbenp.prettier-vscode", + "streetsidesoftware.code-spell-checker" ] } diff --git a/.vscode/settings.json b/.vscode/settings.json index 6278784..3a92cfc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.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"] } diff --git a/README.md b/README.md index 8907391..269a68b 100644 --- a/README.md +++ b/README.md @@ -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 }); + +/* + + + + + name + Joe + answer + 42 + + +*/ +``` + +### `plist.parse()` + +```js +const plist = require("simple-plist"); + +const xml = ` + + name + Joe + +`; + +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 = ` + + name + Joe + answer + 42 + +`; -// 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(xml); +// answer = 42; -// Convert a plist xml string or a binary plist buffer to a Javascript object -var data = plist.parse( - "nameJoe" -); -console.log(JSON.stringify(data)); +// typed file loading +const { name } = readFileSync("/path/to/profile.plist"); ``` diff --git a/src/index.ts b/src/index.ts index c1ec856..28cab48 100644 --- a/src/index.ts +++ b/src/index.ts @@ -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, diff --git a/src/readFileSync.ts b/src/readFileSync.ts index 4a24fff..d8b789d 100644 --- a/src/readFileSync.ts +++ b/src/readFileSync.ts @@ -1,7 +1,7 @@ import fs, { PathOrFileDescriptor } from "fs"; import { parse } from "./parse"; -export function readFileSync(aFile: PathOrFileDescriptor) { +export function readFileSync(aFile: PathOrFileDescriptor): T { const contents = fs.readFileSync(aFile); if (contents.length === 0) { return {} as Record; diff --git a/tsconfig.json b/tsconfig.json index 0b34ec9..988cc1f 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -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 */