Merge pull request #60 from gavoja/feature/v5

New version

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+# [5.0.0] - TBA
+
+### Changed
+
+- No more callbacks in JavaScript API; asynchronous generators are used instead.
+- The pipeline has been rewritten. Instead of interval-based approach, packages are now pushed after a delay since the last change.
+- The `-i` (interval) argument becomes `-d` (delay).
+- The `-d` (debug) argument becomes `-v` (verbose).
+- The `-u` argument becomes `-q`.

README.md

@@ -25,28 +25,28 @@ Simply run `aemsync` on your project path, make a change to any of your files or
 
 ### Advanced usage
 
-Commandline
+CLI
 ```
 Usage:
   aemsync [OPTIONS]
 
 Options:
   -t <target>           URL to AEM instance; multiple can be set.
-                        Default: ${defaults.targets}
+                        Default: http://admin:admin@localhost:4502
   -w <path_to_watch>    Watch over folder.
-                        Default: CWD
+                        Default: '.'
   -p <path_to_push>     Push specific file or folder.
   -e <exclude_filter>   Extended glob filter; multiple can be set.
                         Default:
                           **/jcr_root/*
                           **/@(.git|.svn|.hg|target)
                           **/@(.git|.svn|.hg|target)/**
-  -i <sync_interval>    Update interval.
-                        Default: ${defaults.interval} ms
-  -u <packmgr_path>     Package manager path.
-                        Default: ${defaults.packmgrPath}
+  -d <delay>            Time to wait since the last change before push.
+                        Default: 300 ms
+  -q <packmgr_path>     Package manager path.
+                        Default: /crx/packmgr/service.jsp
   -c                    Check if AEM is up and running before pushing.
-  -d                    Enable debug mode.
+  -v                    Enable verbose mode.
   -h                    Display this screen.
 
 Examples:
@@ -60,83 +60,57 @@ Examples:
     > aemsync -p /foo/bar/my-workspace/jcr_content/apps/my-app/components/my-component
 ```
 
-JavaScript (full watch example):
+JavaScript API
 ```JavaScript
-const aemsync = require('aemsync')
-
-const workingDir = '~/workspace/my_project'
-
-// Arguments below are optional.
-const targets = [
-  'http://admin:admin@localhost:4502',
-  'http://admin:admin@localhost:4503'
-]
-const exclude = ['**/*.orig'] // Skip merge files.
-const packmgrPath = '/foo/crx/packmgr/service.jsp'
-const interval = 300
-const onPushEnd = (err, target, log) => {
-  // Called for each of the targets.
-  if (err) {
-    console.log(`Error when pushing package to ${target}.`, err.message)
-  } else {
-    console.log(`Package pushed to ${target}. Response log:\n${log}`)
-  }
-}
-const checkBeforePush = true
+import { aemsync, push } from 'aemsync'
+
+// Interactive watch example.
+(async function () {
+  const args = { workingDir }
 
-// Will watch for changes over workingDir and push upon a file change.
-// Only the first argument is mandatory.
-aemsync(workingDir, { targets, exclude, interval, packmgrPath, onPushEnd, checkBeforePush })
+  for await (const result of aemsync(args)) {
+    console.log(result)
+  }
+})()
+
+// Push example.
+(async function () {
+  const args = { payload: [
+    './foo/bar/my-workspace/jcr_content/apps/my-app/components/my-component',
+    './foo/bar/my-workspace/jcr_content/apps/my-app/components/something-else'
+  ]}
+
+  for await (const result of aemsync(args)) {
+    // Will yield one result for each target.
+    console.log(result)
+  }
+})()
 ```
 
-JavaScript (direct push example):
+JavaScript arguments and defaults for `aemsync()` and `push()` functions:
 ```JavaScript
-const { push } = require('aemsync')
-
-const pathToPush = '~/foo/bar/my-workspace/jcr_content/apps/my-app/components/my-component'
-
-// Arguments below are optional.
-const targets = [
-  'http://admin:admin@localhost:4502',
-  'http://admin:admin@localhost:4503'
-]
-const onPushEnd = (err, target, log) => {
-  // Called for each of the targets.
-  if (err) {
-    console.log(`Error when pushing package to ${target}.`, err.message)
-  } else {
-    console.log(`Package pushed to ${target}. Response log:\n${log}`)
-  }
+const args = {
+  workingDir: '.',
+  exclude: ['**/jcr_root/*', '**/@(.git|.svn|.hg|target)', '**/@(.git|.svn|.hg|target)/**'],
+  packmgrPath: '/crx/packmgr/service.jsp',
+  targets: ['http://admin:admin@localhost:4501'],
+  delay: 300,
+  checkIfUp: false
 }
-const checkBeforePush = true
-
-// Will push the path to AEM.
-// To use await, the call must be made inside an async function.
-// The result is a Promise so it can also be resolved with .then().
-// Only the first argument is mandatory.
-await push(pathToPush, { targets, onPushEnd, checkBeforePush })
 ```
 
 ### Description
 
-The Watcher uses Node's `fs.watch()` function to watch over directory changes recursively. For Windows and OSX the `recursive` option is used, which significantly improves the performance.
+Watching for file changes is fast, since it uses Node's `recursive` option for `fs.watch()` where applicable.
 
 Any changes inside `jcr_root` folders are detected and deployed to AEM instance(s) as a package. By default, there is an exclude filter in palce:
 * Changes to first level directories under `jcr_root` are ingored. This is to avoid accidentally removing `apps`, `libs` or any other first level node in AEM.
 * Any paths containing `.svn`, `.git`, `.hg` or `target` are ignored.
 * The exclude filter can be overriden. Do note that this will remove the above rules completely and if required, they must be added manually.
 
-Update interval is the time aemsync waits for file changes before the package is created. In case of multiple file changes (e.g. switching between code branches), creating a new package per file should be avoided and instead, all changes should be pushed in one go. Lowering the value decreases the delay for a single file change but may increase the delay for multiple file changes. If you are unsure, please leave the default value.
+Delai is the time to wait to pass since the last change before the package is created. In case of bulk changes (e.g. switching between code branches), creating a new package per file should be avoided and instead, all changes should be pushed in one go. Lowering the value decreases the delay for a single file change but may increase the delay for multiple file changes. If you are unsure, please leave the default.
 
 ### Caveats
 
 1. Packages are installed using package manager service (`/crx/packmgr/service.jsp`), which takes some time to initialize after AEM startup. If the push happens before, the Sling Post Servlet will take over causing the `/crx/packmgr/service.jsp/file` node to be added to the repository. Use `-c` option to performs a status check before sending (all bundles must be active).
 2. Changing any XML file will cause the parent folder to be pushed. Given the many special cases around XML files, the handlig is left to the package manager.
-
-### Backward incompatible changes since version 4
-
-1. Multiple targes are now specified with multiple `-t` options rather than a comma separated string.
-2. The same goes for the exclude filter (`-e`).
-3. Exclude filter supports extended globbing only. Setting exclude filter with `-e` option overrides the default.
-4. JavaScript API functions have a different signature. This is to spearate mandatory and optional arguments.
-5. The `push()` function returns Promise and can be resolved with `await`.

bin/aemsync.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from '../index.js'
+main()