Merge pull request #14 from prettygoodtech/feature/dot-notation

Add support for dot, bracket notations with a Proxy

Author: matei-radu

.prettierignore

@@ -1,6 +1,7 @@
 # Build artifacts
 lib
 types
+coverage
 
 # Documentation
 *.md

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning][semver].
 ## [Unreleased]
 ### Added
 - "Features" section to README.
+- Support for dot and bracket property accessors.
 
 ### Changed
 - Upgrade `@ava/typescript` from `3.0.1` to `4.0.0`.

README.md

@@ -13,13 +13,10 @@ easily, and safely. Built with [TypeScript][typescript].
 for Node.js.
 - Supports `setItem`, `getItem`, `deleteItem`, `clear`, and `key` methods.
 - Supports `length` property.
-- Small footprint.
+- Supports dot and bracket property accessors.
+- Small footprint with zero dependencies.
 - TypeScript declarations.
 
-### Roadmap to v1
-- Support for dot notation property accessor.
-- Support for bracket notation property accessor.
-
 ## Installation and Usage
 First, install the package:
 
@@ -40,6 +37,14 @@ nsStorage.setItem("preferred-theme", "dark");
 
 // Will retrieve item with key my-prefix:last-accessed-on
 const lastAccessedOn = nsStorage.getItem("last-accessed-on");
+
+// Dot notation, will use key my-prefix:favorite
+nsStorage.favorite = "sport-section"; 
+delete nsStorage.favorite;
+
+// Bracket notation, will use key my-prefix:favorite
+nsStorage["favorite"] = "sport-section";
+delete nsStorage["favorite"];
 ```
 
 ### Caveats

src/index.test.ts

@@ -32,26 +32,26 @@ test.beforeEach((t) => {
   t.context.storage.clear();
 });
 
-test("NamespacedStorage - constructor", (t) => {
+test.serial("NamespacedStorage - constructor", (t) => {
   t.notThrows(() => new NamespacedStorage(t.context.storage, "foo"));
 });
 
-test("NamespacedStorage - setItem", (t) => {
+test.serial("NamespacedStorage - setItem", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   nsStorage.setItem("user-id", "1234");
 
   t.is(t.context.storage.getItem("foo:user-id"), "1234");
 });
 
-test("NamespacedStorage - getItem", (t) => {
+test.serial("NamespacedStorage - getItem", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   t.context.storage.setItem("foo:user-id", "1234");
   t.context.storage.setItem("user-id", "5678");
 
   t.is(nsStorage.getItem("user-id"), "1234");
 });
 
-test("NamespacedStorage - removeItem", (t) => {
+test.serial("NamespacedStorage - removeItem", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   t.context.storage.setItem("foo:user-id", "1234");
   t.context.storage.setItem("user-id", "5678");
@@ -62,7 +62,7 @@ test("NamespacedStorage - removeItem", (t) => {
   t.is(t.context.storage.getItem("user-id"), "5678");
 });
 
-test("NamespacedStorage - clear", (t) => {
+test.serial("NamespacedStorage - clear", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   t.context.storage.setItem("foo:user-id", "1234");
   t.context.storage.setItem("foo:preferred-theme", "dark");
@@ -76,7 +76,7 @@ test("NamespacedStorage - clear", (t) => {
   t.is(t.context.storage.getItem("user-id"), "5678");
 });
 
-test("NamespacedStorage - length", (t) => {
+test.serial("NamespacedStorage - length", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   t.context.storage.setItem("foo:user-id", "1234");
   t.context.storage.setItem("foo:preferred-theme", "dark");
@@ -85,7 +85,7 @@ test("NamespacedStorage - length", (t) => {
   t.is(nsStorage.length, 2);
 });
 
-test("NamespacedStorage - key", (t) => {
+test.serial("NamespacedStorage - key", (t) => {
   const nsStorage = new NamespacedStorage(t.context.storage, "foo");
   t.context.storage.setItem("foo:user-id", "1234"); // idx 0, ns_idx 0
   t.context.storage.setItem("user-id", "5678"); // idx 1, ns_idx -
@@ -94,3 +94,122 @@ test("NamespacedStorage - key", (t) => {
   t.is(nsStorage.key(0), "user-id");
   t.is(nsStorage.key(1), "preferred-theme");
 });
+
+test.serial("NamespacedStorage - dot notation - assignment", (t) => {
+  const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+  nsStorage.user_id = "1234";
+
+  t.is(t.context.storage.getItem("foo:user_id"), "1234");
+});
+
+test.serial(
+  "NamespacedStorage - dot notation - don't overwrite methods",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+    // @ts-ignore, TypeScript already prevents overwriting methods because of type
+    // mismatch, but a test is necessary for plain JS use.
+    nsStorage.setItem = "1234";
+
+    t.is(typeof nsStorage.setItem, "function");
+  }
+);
+
+test.serial("NamespacedStorage - dot notation - access key/value pair", (t) => {
+  const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+  t.context.storage.setItem("foo:user_id", "5678");
+
+  t.is(nsStorage.user_id, "5678");
+});
+
+test.serial("NamespacedStorage - dot notation - access storage method", (t) => {
+  const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+  t.is(typeof nsStorage.setItem, "function");
+});
+
+test.serial("NamespacedStorage - dot notation - delete key/value pair", (t) => {
+  const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+  t.context.storage.setItem("foo:user_id", "5678");
+
+  // Check key/value pair is actually available
+  t.is(nsStorage.user_id, "5678");
+  delete nsStorage.user_id;
+  t.is(nsStorage.user_id, null);
+});
+
+test.serial(
+  "NamespacedStorage - dot notation - don't delete storage method",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+    // @ts-ignore, TypeScript already prevents deleting explicitly defined,
+    // non-optional properties, but a test is necessary for plain JS use.
+    delete nsStorage.setItem;
+    t.is(typeof nsStorage.setItem, "function");
+  }
+);
+
+test.serial("NamespacedStorage - bracket notation - assignment", (t) => {
+  const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+  nsStorage["user_id"] = "1234";
+
+  t.is(t.context.storage.getItem("foo:user_id"), "1234");
+});
+
+test.serial(
+  "NamespacedStorage - bracket notation - don't overwrite methods",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+    // @ts-ignore, TypeScript already prevents overwriting methods because of type
+    // mismatch, but a test is necessary for plain JS use.
+    nsStorage["setItem"] = "1234";
+
+    t.is(typeof nsStorage["setItem"], "function");
+  }
+);
+
+test.serial(
+  "NamespacedStorage - bracket notation - access key/value pair",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+    t.context.storage.setItem("foo:user_id", "5678");
+
+    t.is(nsStorage["user_id"], "5678");
+  }
+);
+
+test.serial(
+  "NamespacedStorage - bracket notation - access storage method",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+    t.is(typeof nsStorage["setItem"], "function");
+  }
+);
+
+test.serial(
+  "NamespacedStorage - bracket notation - delete key/value pair",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+    t.context.storage.setItem("foo:user_id", "5678");
+
+    // Check key/value pair is actually available
+    t.is(nsStorage["user_id"], "5678");
+    delete nsStorage["user_id"];
+    t.is(nsStorage["user_id"], null);
+  }
+);
+
+test.serial(
+  "NamespacedStorage - bracket notation - don't delete storage method",
+  (t) => {
+    const nsStorage = new NamespacedStorage(t.context.storage, "foo");
+
+    // @ts-ignore, TypeScript already prevents deleting explicitly defined,
+    // non-optional properties, but a test is necessary for plain JS use.
+    delete nsStorage["setItem"];
+    t.is(typeof nsStorage["setItem"], "function");
+  }
+);

src/index.ts

@@ -30,15 +30,73 @@ const isKeyPrefixed = (key: string, prefix: string): boolean => {
   return key.startsWith(prefix + PREFIX_SEPARATOR);
 };
 
+const RESERVED_PROPERTIES = [
+  // Storage properties
+  "length",
+  "key",
+  "setItem",
+  "getItem",
+  "removeItem",
+  "clear",
+  // Private properties
+  "storage",
+  "prefix",
+  // Private custom methods
+  "getNamespacedEntries",
+];
+
+const propertyAccessorHandler: ProxyHandler<NamespacedStorage> = {
+  // Necessary for:
+  //  - nsStorage.foo = "bar"
+  //  - nsStorage["foo"] = "bar"
+  set: (target, property: string, value: string) => {
+    if (RESERVED_PROPERTIES.includes(property)) {
+      return true;
+    }
+
+    target.setItem(property, value);
+    return true;
+  },
+
+  // Necessary for:
+  //  - const foo = nsStorage.foo
+  //  - const foo = nsStorage["foo"]
+  get: (target, property: string): string | null => {
+    if (RESERVED_PROPERTIES.includes(property)) {
+      return target[property];
+    }
+
+    return target.getItem(property);
+  },
+
+  // Necessary for:
+  //  - delete nsStorage.foo
+  //  - delete nsStorage["foo"]
+  deleteProperty: (target, property: string): boolean => {
+    if (RESERVED_PROPERTIES.includes(property)) {
+      // Storage seems to return true when attempting to delete a reserved
+      // property, even if this property is never really removed.
+      return true;
+    }
+
+    target.removeItem(property);
+    return true;
+  },
+};
+
 export class NamespacedStorage implements Storage {
+  [key: string]: any;
+
   /**
    * Creates a new instance of `NamespacedStorage` based on the given
    * `storage` implementation.
    *
    * All methods will operate on the given `storage` object using the given
    * `prefix` to create a namespace for keys.
    */
-  constructor(private storage: Storage, private prefix: string) {}
+  constructor(private storage: Storage, private prefix: string) {
+    return new Proxy(this, propertyAccessorHandler);
+  }
 
   /** Returns the number of key/value pairs in the namespace. */
   public get length(): number {