Merge pull request #67 from micro-analytics/feat/add-adapter-details

feat: Add adapter-utils

Author: mxstbr

adapter-utils.js

@@ -0,0 +1,8 @@
+const supportsAsyncAwait =
+  parseInt(process.version.slice(1).split('.').join('')) > 760;
+
+const path = supportsAsyncAwait
+  ? './src/adapter-utils'
+  : './dist/adapter-utils';
+
+module.exports = require(path);

package.json

@@ -34,13 +34,17 @@
     ]
   },
   "lint-staged": {
-    "*.js": ["prettier --single-quote --trailing-comma es5 --write", "git add"]
+    "*.js": [
+      "prettier --single-quote --trailing-comma es5 --write",
+      "git add"
+    ]
   },
   "author": "Max Stoiber <[email protected]> (http://mxstbr.com/)",
   "license": "MIT",
   "repository": "https://github.com/mxstbr/micro-analytics",
   "dependencies": {
     "args": "^2.3.0",
+    "escape-regex": "^1.0.7",
     "flat-file-db": "^1.0.0",
     "micro": "6.1.0",
     "micro-analytics-adapter-flat-file-db": "^1.3.0",

src/adapter-utils.js

@@ -0,0 +1,37 @@
+const escapeRegexp = require('escape-regex');
+
+function createKeyRegex(str) {
+  str = str.split('*').map(s => escapeRegexp(s)).join('*');
+  return new RegExp('^' + str.replace('*', '.*'));
+}
+
+function createPathFilter(options) {
+  return key =>
+    options.ignoreWildcard
+      ? key.startsWith(options.pathname)
+      : key.match(createKeyRegex(options.pathname));
+}
+
+function filterPaths(paths, options) {
+  return (paths || []).filter(createPathFilter(options));
+}
+
+function createViewFilter(options) {
+  return view => {
+    if (options && options.before && view.time > options.before) return false;
+    if (options && options.after && view.time < options.after) return false;
+    return true;
+  };
+}
+
+function filterViews(views, options) {
+  return (views || []).filter(createViewFilter(options));
+}
+
+module.exports = {
+  createKeyRegex,
+  createPathFilter,
+  filterPaths,
+  createViewFilter,
+  filterViews,
+};

tests/adapter-utils.test.js

@@ -0,0 +1,98 @@
+const {
+  createKeyRegex,
+  createPathFilter,
+  filterPaths,
+  createViewFilter,
+  filterViews,
+} = require('../src/adapter-utils');
+
+test('createKeyRegex', () => {
+  expect(createKeyRegex('/path').test('/pathname')).toBe(true);
+  expect(createKeyRegex('/p*th').test('/pathname')).toBe(true);
+  expect(createKeyRegex('/path').test('/athname')).toBe(false);
+});
+
+test('createPathFilter with ignoreWildcard', () => {
+  const keys = ['/path', '/other-path', '/pathname', '/p-ath'];
+  const filterFunc = createPathFilter({
+    ignoreWildcard: true,
+    pathname: '/path',
+  });
+
+  expect(keys.filter(filterFunc)).toEqual(['/path', '/pathname']);
+});
+
+test('createPathFilter without ignoreWildcard', () => {
+  const keys = ['/path', '/other-path', '/pathname', '/p-ath'];
+  const filterFunc = createPathFilter({
+    ignoreWildcard: false,
+    pathname: '/p*ath',
+  });
+
+  expect(keys.filter(filterFunc)).toEqual(['/path', '/pathname', '/p-ath']);
+});
+
+test('filterPaths should return array when paths is undefined', () => {
+  expect(filterPaths(undefined)).toEqual([]);
+});
+
+test('filterPaths with ignoreWildcard', () => {
+  const keys = ['/path', '/other-path', '/pathname', '/p-ath'];
+  const filtered = filterPaths(keys, {
+    ignoreWildcard: true,
+    pathname: '/path',
+  });
+
+  expect(filtered).toEqual(['/path', '/pathname']);
+});
+
+test('filterPaths without ignoreWildcard', () => {
+  const keys = ['/path', '/other-path', '/pathname', '/p-ath'];
+  const filtered = filterPaths(keys, {
+    ignoreWildcard: false,
+    pathname: '/p*ath',
+  });
+
+  expect(filtered).toEqual(['/path', '/pathname', '/p-ath']);
+});
+
+const one = { time: new Date(2017, 4, 4, 1, 0).getTime() };
+const two = { time: new Date(2017, 4, 4, 2, 0).getTime() };
+const three = { time: new Date(2017, 4, 4, 3, 0).getTime() };
+const four = { time: new Date(2017, 4, 4, 4, 0).getTime() };
+const views = [one, two, three, four];
+
+const after = new Date(2017, 4, 4, 2, 30).getTime();
+const before = new Date(2017, 4, 4, 3, 30).getTime();
+
+test('createViewFilter should with before filter', () => {
+  expect(views.filter(createViewFilter({ before }))).toEqual([one, two, three]);
+});
+
+test('createViewFilter should with after filter', () => {
+  expect(views.filter(createViewFilter({ after }))).toEqual([three, four]);
+});
+
+test('createViewFilter should with after and before filter', () => {
+  expect(views.filter(createViewFilter({ after, before }))).toEqual([three]);
+});
+
+test('filterViews should return array when views is undefined', () => {
+  expect(filterViews(undefined)).toEqual([]);
+});
+
+test('filterViews should not filter without options', () => {
+  expect(filterViews(views)).toEqual([one, two, three, four]);
+});
+
+test('filterViews should with before filter', () => {
+  expect(filterViews(views, { before })).toEqual([one, two, three]);
+});
+
+test('filterViews should with after filter', () => {
+  expect(filterViews(views, { after })).toEqual([three, four]);
+});
+
+test('filterViews should with after and before filter', () => {
+  expect(filterViews(views, { after, before })).toEqual([three]);
+});

writing-adapters.md

@@ -44,6 +44,42 @@ module.exports = {
 }
 ```
 
+## Adapter-utils
+
+Adapters falls mostly into two camps, those who can offload filtering to the database engine and
+those who need to do the filtering in JavaScript. If you are writing an adapter for the last group
+your in luck. We have a set of utils that are well tested which handles filtering. Read on if you
+would like to use or skip to the next section. Keep in mind that you might not need all of these
+depending on the database you are using.
+
+### `createKeyRegex`
+Creates a regex from a wildcard string, e.g. `/p*th`.
+
+Usage: `createKeyRegex(pathname: string): Regex`
+
+
+### `createPathFilter`
+Creates a filter predicate that can be passed into Array.filter based on options. This might be
+useful in `getAll`. See also `filterPaths` below.
+
+Usage: `createPathFilter(options: { ignoreWildcard: boolean, pathname: string }):: (path: string) => boolean`
+
+### `filterPaths`
+Filters a list of paths based on given options. This might be useful in `getAll`.
+
+Usage: `filterPaths(paths: Array<string>, options: { ignoreWildcard: boolean, pathname: string }): Array<string>`
+
+### `createViewFilter`
+Creates a filter predicate that can be passed into Array.filter based on options. It can be used
+with a list of views. This might be useful in `get` and `getAll`. See also `filterViews` below.
+
+Usage: `createViewFilter(options: { before: number, after: number }): (view: View) => boolean`
+
+### `filterViews`
+Filters a list of views based on given options. This migth be useful in `get` and `getAll`.
+
+Usage: `filterViews(views: Array<View>, options: { before: number, after: number }): Array<View>`
+
 ## Tests
 
 There is pre-written tests for adapters that you can use to make sure you adapter is implemented