@cboulanger/zotero-sync-bookends - npm Package Compare versions

Comparing version 2.0.1 to 2.1.0

package.json

 {
   "name": "@cboulanger/zotero-sync-bookends",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Bookends store for @retorquere/zotero-sync",
   "main": "src/index.ts",
+  "bin": "test.js",
   "scripts": {
@@ -10,4 +11,6 @@ "test": "tsc && npx ts-node test.ts",
     "prepublishOnly": "npm install && npm run tsc",
-    "go": "npm run tsc && npm version patch && npm publish --access public",
-    "postversion": "git push --follow-tags"
+    "publish-patch": "npm run tsc && npm version patch && npm publish --access public",
+    "publish-minor": "npm run tsc && npm version minor && npm publish --access public",
+    "postversion": "git push --follow-tags",
+    "pkg": "tsc test.ts --esModuleInterop && npx pkg ."
   },
@@ -39,5 +42,12 @@ "keywords": [
     "gauge": "^2.7.4",
+    "pkg": "^5.1.0",
     "ts-node": "^9.1.1",
     "typescript": "^4.2.4"
+  },
+  "pkg": {
+    "targets": [
+      "node12-macos-x64"
+    ],
+    "outputPath": "bin"
   }
 }

README.md

 # Bookends Store for @retorquere/zotero-sync
 
-This is a store implementation for https://github.com/retorquere/zotero-sync, 
-which allows to export Zotero libraries into Bookends, a MacOS reference
+This is a store implementation for https://github.com/retorquere/zotero-sync 
+that enables exporting/backing up Zotero libraries into Bookends, a MacOS reference
 manager from https://www.sonnysoftware.com. Using Bookend's scripting support via
-JSX, Zotero data is added to, or updated in a Bookends library.
+JavaScript for Automation (JSX), Zotero data is added to, or updated in a Bookends library.
 
@@ -16,6 +16,6 @@ This implementation saves all Zotero libraries that are accessible to a given Zotero
 
-See [the test script](test.ts) for an example on how to integrate the library in your project.
-
 ## Issues
- - Access to Bookends via OSA/JXA is slow. It can take a couple of hours to synchronize large libraries.
+ - Access to Bookends via OSA/JXA is slow. The initial synchronization can take a couple of hours for large libraries.
+   After that, especially if you do it often, syncing should go fast since only the data that has changed is 
+   synchronized. 
  - The current implementation works well enough for my use case but of course isn't perfect. Please
@@ -48,2 +48,7 @@ let me know if it works for you and open issues / pull requests if it doesn't.
 
+## Installation
+
+To use the library in your projects, simply `npm install @cboulanger/zotero-sync-bookends`. See [the test script](test.ts) 
+for an example on how to use the API.
+
 ## Testing
@@ -58,7 +63,23 @@
 # edit .env and provide the values needed there
+npm install
 npm test
 ```
 
+## Creating an executable / MacOS app
 
+You can create a standalone executable file which can be run on the command line or packaged into 
+an application by executing `npm run pkg`. The executable will be written to the `bin` directory.
 
+> Please note that if you have set environment variables in a `.env` file, the package will include 
+> include them and will be visible as plain text in the source! Please remove the file if you intend 
+> to distribute the built executable. The values will be used as defaults, which is convenient for 
+> personal use of the executable. 
+
+The usage of the executable is
+
+```bash
+zotero-sync-bookends <Zotero API key> "Bookends library file name (not the path!)"
+```
+
+
 ## Resources
@@ -65,0 +86,0 @@ - [JXA Release notes](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/Articles/OSX10-10.html#//apple_ref/doc/uid/TP40014508-CH109-SW1)

src/index.d.ts

@@ -37,8 +37,7 @@ import type { Zotero } from "@retorquere/zotero-sync/typings/zotero";
     /**
-     * Output additional information on the console if the environment variable
-     * ZOTERO_SYNC_DEBUG is set
+     * Output additional information to the console if the `verbose` property is true
      * @param {string} msg
      * @private
      */
-    private debug;
+    private logVerbose;
     /**
@@ -45,0 +44,0 @@ * Runs a JXA script in the context of the current Bookends library. The following

src/index.js

@@ -58,8 +58,7 @@ "use strict";
     /**
-     * Output additional information on the console if the environment variable
-     * ZOTERO_SYNC_DEBUG is set
+     * Output additional information to the console if the `verbose` property is true
      * @param {string} msg
      * @private
      */
-    debug(msg) {
+    logVerbose(msg) {
         if (Store.verbose) {
@@ -319,3 +318,3 @@ process.stdout.clearLine();
             if (this.lastIndex === 0) {
-                this.debug(`Fast-forwarding, skipping previously synchronized items...`);
+                this.logVerbose(`Fast-forwarding, skipping previously synchronized items...`);
             }
@@ -343,3 +342,3 @@ this.lastIndex++;
                                 changedProperties.forEach(key => changedData[key] = data[key]);
-                                this.debug(`Updating item '${data.title}', properties ${Object.keys(changedData).join(",")}`);
+                                this.logVerbose(`Updating item '${data.title}', properties ${Object.keys(changedData).join(",")}`);
                                 await this.updatePublication(Number(storedData.id), changedData);
@@ -349,3 +348,3 @@ }
                         else {
-                            this.debug(`Adding item '${data.title}' ...`);
+                            this.logVerbose(`Adding item '${data.title}' ...`);
                             await this.addPublication(data);
@@ -394,3 +393,3 @@ }
             if (item) {
-                this.debug(`Deleting '${item.title}' ...`);
+                this.logVerbose(`Deleting '${item.title}' ...`);
                 await this.removePublication(Number(item.id));
@@ -397,0 +396,0 @@ }

src/index.ts

@@ -73,8 +73,7 @@ import runJxa from 'run-jxa';
   /**
-   * Output additional information on the console if the environment variable
-   * ZOTERO_SYNC_DEBUG is set
+   * Output additional information to the console if the `verbose` property is true
    * @param {string} msg
    * @private
    */
-  private debug(msg:string) {
+  private logVerbose(msg:string) {
     if (Store.verbose) {
@@ -346,3 +345,3 @@ process.stdout.clearLine();
       if (this.lastIndex === 0) {
-        this.debug(`Fast-forwarding, skipping previously synchronized items...`);
+        this.logVerbose(`Fast-forwarding, skipping previously synchronized items...`);
       }
@@ -370,7 +369,7 @@ this.lastIndex++;
                 changedProperties.forEach(key => changedData[key] = data[key]);
-                this.debug(`Updating item '${data.title}', properties ${Object.keys(changedData).join(",")}`);
+                this.logVerbose(`Updating item '${data.title}', properties ${Object.keys(changedData).join(",")}`);
                 await this.updatePublication(Number(storedData.id), changedData);
               }
             } else {
-              this.debug(`Adding item '${data.title}' ...`);
+              this.logVerbose(`Adding item '${data.title}' ...`);
               await this.addPublication(data);
@@ -418,3 +417,3 @@ }
       if (item) {
-        this.debug(`Deleting '${item.title}' ...`);
+        this.logVerbose(`Deleting '${item.title}' ...`);
         await this.removePublication(Number(item.id));
@@ -421,0 +420,0 @@ }

test.ts

@@ -10,11 +10,34 @@ import { Sync } from '@retorquere/zotero-sync/index'
     // config
-    dotenv.config();
-    const {
-        ZOTERO_API_KEY,
-        BOOKENDS_DB_NAME
-    } = process.env as {[key : string]: string};
+    let zotero_api_key;
+    let bookends_db_name;
+    let argv = process.argv.slice(1);
 
+    // if run from an executable created with `npm run pkg`
+    if (process.pkg) {
+        argv.shift();
+    }
+
+    const help = ["help", "-h", "--help"].includes(argv[0]);
+
+    if (!help) {
+        [zotero_api_key, bookends_db_name] = argv;
+        if (!zotero_api_key || !bookends_db_name) {
+            dotenv.config();
+            const {
+                ZOTERO_API_KEY,
+                BOOKENDS_DB_NAME
+            } = process.env as {[key : string]: string};
+            zotero_api_key = ZOTERO_API_KEY;
+            bookends_db_name = BOOKENDS_DB_NAME;
+        }
+    }
+
+    if (help || !zotero_api_key || !bookends_db_name) {
+        console.info(`Usage: zotero-sync-bookends <Zotero API key> "Bookends library file name"`);
+        process.exit(help ? 0 : 1);
+    }
+
     // initialize the sync engine
     const syncEngine = new Sync;
-    await syncEngine.login(ZOTERO_API_KEY);
+    await syncEngine.login(zotero_api_key);
 
@@ -52,3 +75,3 @@ Store.verbose = true;
     // synchronize with the couchbase store
-    const store = new Store(BOOKENDS_DB_NAME);
+    const store = new Store(bookends_db_name);
     await syncEngine.sync(store);
@@ -55,0 +78,0 @@ })().catch(err => {

New alerts

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

86975

increased by10.22%

Number of package files

12

increased by9.09%

Lines of code

2406

increased by5.43%

Number of lines in readme file

86

increased by32.31%

Worsened metrics

Dev dependency count

6

increased by20%

Number of low supply chain risk alerts

2

increased by100%

No dependency changes