Initial Commit

Author: shaunburdick

.editorconfig

@@ -0,0 +1,14 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+# 2 space indentation
+[**.*]
+indent_style = space
+indent_size = 2

.gitignore

@@ -59,3 +59,6 @@ typings/
 
 # next.js build output
 .next
+
+# dist
+dist/

.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "printWidth": 120
+}

README.md

@@ -1,2 +1,33 @@
-# pythagoreancache
+# Pythagorean Cache
+
 🍷A cache that dumps when full or at an interval
+
+[![cup](https://upload.wikimedia.org/wikipedia/commons/a/a9/Physagorian_Pythagoras_Greedy_Tantalus_cup_05.svg)](https://en.wikipedia.org/wiki/Pythagorean_cup)
+
+## Example
+
+```typescript
+import { PythagoreanCache } from 'pythagorean-cache';
+
+// dump when size reaches 10
+const cache = new PythagoreanCache<string>({ size: 10 });
+
+cache.on('dump', () => {
+  /* do something with 10 items */
+});
+
+for (let x = 0; x < 10; x++) {
+  cache.push(`Hello ${x}`);
+}
+```
+
+## Options
+
+- size: The size of the cache. When the size is reached, a `dump` event is fired with all the items in the cache and then emptied
+- interval: The number of microseconds to wait before firing a `dump` event. This can be used to dump the cache at regular intervals.
+
+These options can be combined, allowing you to create a cache that dumps at a certain size _or_ at a certain interval.
+
+## Inspired Use Case
+
+I was receiving a bursting stream of events I needed to add to a database. Instead of inserting each one as they come in, it was more efficient to do bulk inserts at intervals/sizes. This way that database was protected from burst events and I could expect the events to be inserted within a certain amount of time regardless.

jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  collectCoverage: true
+};

package-lock.json

@@ -0,0 +1,43 @@
+{
+  "name": "pythagorean-cache",
+  "version": "1.0.0",
+  "description": "A cache that empties when full or at an interval",
+  "main": "dist/index.js",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "test": "npm-run-all test:*",
+    "test:unit": "jest",
+    "test:prettier": "prettier -c \"src/**/*.ts\"",
+    "build": "npm-run-all build:*",
+    "build:clean": "rimraf dist/*",
+    "build:transpile": "tsc"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shaunburdick/pythagorean-cache.git"
+  },
+  "keywords": [
+    "cache",
+    "interval",
+    "pythagorean",
+    "dump"
+  ],
+  "author": "Shaun Burdick <npm@shaunburdick.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/shaunburdick/pythagorean-cache/issues"
+  },
+  "homepage": "https://github.com/shaunburdick/pythagorean-cache#readme",
+  "devDependencies": {
+    "@types/jest": "^24.0.11",
+    "@types/node": "^11.13.7",
+    "jest": "^24.7.1",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^1.17.0",
+    "rimraf": "^2.6.3",
+    "ts-jest": "^24.0.2",
+    "typescript": "^3.4.5"
+  }
+}

package.json

@@ -0,0 +1,45 @@
+import { PythagoreanCache } from '..';
+
+describe('PythagoreanCache', () => {
+  it('should throw an error if you do not specify a size or interval', done => {
+    expect(() => new PythagoreanCache({})).toThrow(/You must specify either a size or interval \(or both\)/);
+    done();
+  });
+
+  it('dump(): should emit items', done => {
+    const cq = new PythagoreanCache<string>({ size: 10 });
+    cq.push('foo');
+
+    cq.once('dump', items => {
+      expect(items).toEqual(['foo']);
+      done();
+    });
+
+    cq.dump();
+  });
+
+  it('should emit items when size is reached', done => {
+    const pushItems = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+    const cq = new PythagoreanCache<number>({ size: pushItems.length });
+
+    cq.once('dump', items => {
+      expect(items).toEqual(pushItems);
+      done();
+    });
+
+    pushItems.forEach(item => cq.push(item));
+  });
+
+  it('should emit items when interval is reached', done => {
+    const pushItems = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+    const cq = new PythagoreanCache<number>({ interval: 10 });
+
+    cq.once('dump', items => {
+      cq.stopInterval();
+      expect(items).toEqual(pushItems);
+      done();
+    });
+
+    pushItems.forEach(item => cq.push(item));
+  });
+});

src/__tests__/index.test.ts

@@ -0,0 +1,117 @@
+import { EventEmitter } from 'events';
+
+export interface PythagoreanCacheOpts {
+  /**
+   * Dump cache when queue reaches this size
+   */
+  size?: number;
+
+  /**
+   * Dump cache every X milliseconds
+   */
+  interval?: number;
+}
+
+/**
+ * @link https://en.wikipedia.org/wiki/Pythagorean_cup
+ *
+ * Creates a cache that will emit its items on:
+ * - size: When the cache grows to this size, it will emit the items and reset
+ * - interval: Every X milliseconds it will emit the items (if any) and reset
+ *
+ * @emits dump When the size/interval is met, it will emit the items in the cache and reset
+ *
+ * @class PythagoreanCache
+ * @template T
+ */
+export class PythagoreanCache<T = any> extends EventEmitter {
+  private queue: T[] = [];
+  private interval: NodeJS.Timer;
+
+  get length() {
+    return this.queue.length;
+  }
+
+  constructor(private opts: PythagoreanCacheOpts) {
+    super();
+
+    if (!opts.size && !opts.interval) {
+      throw new Error('You must specify either a size or interval (or both)');
+    }
+
+    this.startInterval();
+  }
+
+  /**
+   * Push an item onto the cache
+   *
+   * @param items The items to push onto the cache
+   * @returns the new size of the cache
+   */
+  push(...items: T[]): number {
+    this.queue.push(...items);
+    if (this.checkLimit()) this.dump();
+    return this.length;
+  }
+
+  /**
+   * Check of the cache has reached its size limit
+   *
+   * @returns true if limit is reached
+   */
+  checkLimit(): boolean {
+    return this.opts.size ? this.length >= this.opts.size : false;
+  }
+
+  /**
+   * Emit the items in the cache, it will do nothing if there are no items in cache
+   */
+  dump(): void {
+    if (this.length > 0) {
+      const items = this.queue.splice(0, this.opts.size || this.length);
+      this.emit('dump', items);
+    }
+  }
+
+  /**
+   * Change the size. This will trigger a dump event if newSize is smaller than the current length
+   *
+   * @param newSize The new size
+   */
+  setSize(newSize: number): void {
+    this.opts.size = newSize;
+    if (this.checkLimit()) this.dump();
+  }
+
+  /**
+   * Change the interval. This will cause the interval job to restart at zero.
+   *
+   * @param newInterval The new interval
+   */
+  setInterval(newInterval: number): void {
+    this.opts.interval = newInterval;
+    this.startInterval();
+  }
+
+  /**
+   * Start the interval dump (if set)
+   */
+  startInterval() {
+    this.stopInterval();
+
+    if (this.opts.interval) {
+      this.interval = setInterval(() => {
+        this.dump();
+      }, this.opts.interval);
+    }
+  }
+
+  /**
+   * Stop the interval check
+   */
+  stopInterval(): void {
+    if (this.interval) {
+      clearInterval(this.interval);
+    }
+  }
+}

src/index.ts

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2015",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "declaration": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "removeComments": false,
+    "pretty": true,
+    "strictNullChecks": true,
+    "lib": ["es2015", "es2016"],
+    "outDir": "dist",
+    "sourceRoot": "src/"
+  },
+  "exclude": ["**/__tests__/*"],
+  "compileOnSave": false,
+  "buildOnSave": false
+}