polystore 0.1.0

package/.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: https://www.paypal.me/franciscopresencia/19

package/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: tests
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x]
+
+    steps:
+      - uses: actions/checkout@v1
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: install dependencies
+        run: npm install
+      - name: npm test
+        run: npm test
+        env:
+          CI: true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Francisco Presencia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -0,0 +1,13 @@
+type Expire = number | string | null;
+
+type Store = {
+  get: (key: string) => Promise<any>;
+  set: (key: string, value: any, opts?: { expire?: Expire }) => Promise<null>;
+  has: (key: string) => Promise<boolean>;
+  del: (key: string) => Promise<null>;
+
+  keys: (prefix?: string) => Promise<string[]>;
+  clear: () => Promise<null>;
+};
+
+export default function (store?: any): Store;

package/index.min.js

@@ -0,0 +1,2 @@
+var l={},g=/(-?(?:\d+\.?\d*|\d*\.?\d+)(?:e[-+]?\d+)?)\s*([\p{L}]*)/iu;t.millisecond=t.ms=1;t.second=t.sec=t.s=t[""]=t.ms*1e3;t.minute=t.min=t.m=t.s*60;t.hour=t.hr=t.h=t.m*60;t.day=t.d=t.h*24;t.week=t.wk=t.w=t.d*7;t.year=t.yr=t.y=t.d*365.25;t.month=t.b=t.y/12;function t(e){if(e==null)return null;if(typeof e=="number")return e;e=e.toLowerCase().replace(/[,_]/g,"");let[u,y,i]=g.exec(e)||[];if(!i)return null;let c=t[i]||t[i.replace(/s$/,"")];if(!c)return null;let d=c*parseFloat(y,10);return Math.abs(Math.round(d))}l.expire=e=>{let u=async n=>{if(!await e.has(n))return null;let{data:a,expire:o}=await e.get(n);return o===null?a:o-new Date().getTime()<=0?null:a},y=async(n,a,{expire:o=null}={})=>{let r=t(o),f=r!==null?new Date().getTime()+r:null;return e.set(n,{expire:f,data:a})},i=async n=>await e.get(n)!==null,c=e.del,d=e.keys,s=e.clear;return{get:u,set:y,has:i,del:c,keys:d,clear:s}};l.memory=e=>({get:async n=>e.get(n)||null,set:async(n,a)=>e.set(n,a),has:async n=>e.has(n),del:async n=>e.delete(n),keys:async(n="")=>[...await e.keys()].filter(a=>a.startsWith(n)),clear:()=>e.clear()});l.localStorage=e=>({get:async n=>e[n]?JSON.parse(e[n]):null,set:async(n,a)=>e.setItem(n,JSON.stringify(a)),has:async n=>n in e,del:async n=>e.removeItem(n),keys:async(n="")=>Object.keys(e).filter(a=>a.startsWith(n)),clear:()=>e.clear()});l.cookie=()=>{let e=async s=>{let n=document.cookie.split("; ").filter(Boolean).find(a=>a.startsWith(s+"="))?.split("=")[1]||null;return JSON.parse(decodeURIComponent(n))},u=async(s,n,{expire:a=null}={})=>{let o=t(a),r=new Date().getTime(),f=o!==null?`; expires=${new Date(r+o).toUTCString()}`:"",p=encodeURIComponent(JSON.stringify(n));document.cookie=s+"="+p+f},y=async s=>(await c()).includes(s),i=async s=>u(s,"",{expire:-100}),c=async(s="")=>document.cookie.split(";").map(n=>n.split("=")[0].trim()).filter(Boolean).filter(n=>n.startsWith(s));return{get:e,set:u,has:y,del:i,keys:c,clear:async()=>{await Promise.all((await c()).map(i))}}};l.redis=e=>{let u=async a=>{let r=await(await e).get(a);return r?JSON.parse(r):null},y=async(a,o,{expire:r=null}={})=>{if(o===null||r===0)return c(a);let f=await e,p=t(r),m=p?Math.round(p/1e3):void 0;return f.set(a,JSON.stringify(o),{EX:m})},i=async a=>!!await(await e).exists(a),c=async a=>(await e).del(a);return{get:u,set:y,has:i,del:c,keys:async(a="")=>(await e).keys(a+"*"),clear:async()=>(await e).flushAll(),close:async()=>(await e).quit()}};function w(e){return!e||e instanceof Map?l.expire(l.memory(e||new Map)):typeof localStorage<"u"&&e===localStorage||typeof sessionStorage<"u"&&e===sessionStorage?l.expire(l.localStorage(e)):e==="cookie"?l.cookie():l.redis(e)}export{w as default};
+//# sourceMappingURL=index.min.js.map

package/index.min.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["src/index.js"],
+  "sourcesContent": ["const layers = {};\n\nconst times = /(-?(?:\\d+\\.?\\d*|\\d*\\.?\\d+)(?:e[-+]?\\d+)?)\\s*([\\p{L}]*)/iu;\n\nparse.millisecond = parse.ms = 1;\nparse.second = parse.sec = parse.s = parse[\"\"] = parse.ms * 1000;\nparse.minute = parse.min = parse.m = parse.s * 60;\nparse.hour = parse.hr = parse.h = parse.m * 60;\nparse.day = parse.d = parse.h * 24;\nparse.week = parse.wk = parse.w = parse.d * 7;\nparse.year = parse.yr = parse.y = parse.d * 365.25;\nparse.month = parse.b = parse.y / 12;\n\nfunction parse(str) {\n  if (str === null || str === undefined) return null;\n  if (typeof str === \"number\") return str;\n  // ignore commas/placeholders\n  str = str.toLowerCase().replace(/[,_]/g, \"\");\n  let [_, value, units] = times.exec(str) || [];\n  if (!units) return null;\n  const unitValue = parse[units] || parse[units.replace(/s$/, \"\")];\n  if (!unitValue) return null;\n  const result = unitValue * parseFloat(value, 10);\n  return Math.abs(Math.round(result));\n}\n\nlayers.expire = (store) => {\n  // Item methods\n  const get = async (key) => {\n    if (!(await store.has(key))) return null;\n    const { data, expire } = await store.get(key);\n    if (expire === null) return data;\n    const diff = expire - new Date().getTime();\n    if (diff <= 0) return null;\n    return data;\n  };\n  const set = async (key, data, { expire = null } = {}) => {\n    const time = parse(expire);\n    const expDiff = time !== null ? new Date().getTime() + time : null;\n    return store.set(key, { expire: expDiff, data });\n  };\n  const has = async (key) => (await store.get(key)) !== null;\n  const del = store.del;\n\n  // Group methods\n  const keys = store.keys;\n  const clear = store.clear;\n\n  return { get, set, has, del, keys, clear };\n};\n\nlayers.memory = (store) => {\n  // Item methods\n  const get = async (key) => store.get(key) || null;\n  const set = async (key, data) => store.set(key, data);\n  const has = async (key) => store.has(key);\n  const del = async (key) => store.delete(key);\n\n  // Group methods\n  const keys = async (prefix = \"\") =>\n    [...(await store.keys())].filter((k) => k.startsWith(prefix)); // \uD83E\uDD37\u200D\u2642\uFE0F\n  const clear = () => store.clear();\n\n  return { get, set, has, del, keys, clear };\n};\n\nlayers.localStorage = (store) => {\n  // Item methods\n  const get = async (key) => (store[key] ? JSON.parse(store[key]) : null);\n  const set = async (key, data) => store.setItem(key, JSON.stringify(data));\n  const has = async (key) => key in store;\n  const del = async (key) => store.removeItem(key);\n\n  // Group methods\n  const keys = async (prefix = \"\") =>\n    Object.keys(store).filter((k) => k.startsWith(prefix));\n  const clear = () => store.clear();\n\n  return { get, set, has, del, keys, clear };\n};\n\nlayers.cookie = () => {\n  const get = async (key) => {\n    const value =\n      document.cookie\n        .split(\"; \")\n        .filter(Boolean)\n        .find((row) => row.startsWith(key + \"=\"))\n        ?.split(\"=\")[1] || null;\n    return JSON.parse(decodeURIComponent(value));\n  };\n\n  const set = async (key, data, { expire = null } = {}) => {\n    const time = parse(expire);\n    const now = new Date().getTime();\n    const expireStr =\n      time !== null ? `; expires=${new Date(now + time).toUTCString()}` : \"\";\n    const value = encodeURIComponent(JSON.stringify(data));\n    document.cookie = key + \"=\" + value + expireStr;\n  };\n  const has = async (key) => (await keys()).includes(key);\n  const del = async (key) => set(key, \"\", { expire: -100 });\n\n  // Group methods\n  const keys = async (prefix = \"\") =>\n    document.cookie\n      .split(\";\")\n      .map((l) => l.split(\"=\")[0].trim())\n      .filter(Boolean)\n      .filter((k) => k.startsWith(prefix));\n  const clear = async () => {\n    await Promise.all((await keys()).map(del));\n  };\n\n  return { get, set, has, del, keys, clear };\n};\n\nlayers.redis = (store) => {\n  const get = async (key) => {\n    const client = await store;\n    const value = await client.get(key);\n    if (!value) return null;\n    return JSON.parse(value);\n  };\n  const set = async (key, value, { expire = null } = {}) => {\n    if (value === null || expire === 0) return del(key);\n    const client = await store;\n    const exp = parse(expire);\n    const EX = exp ? Math.round(exp / 1000) : undefined;\n    return client.set(key, JSON.stringify(value), { EX });\n  };\n  const has = async (key) => Boolean(await (await store).exists(key));\n  const del = async (key) => (await store).del(key);\n\n  const keys = async (prefix = \"\") => (await store).keys(prefix + \"*\");\n  const clear = async () => (await store).flushAll();\n  const close = async () => (await store).quit();\n\n  return { get, set, has, del, keys, clear, close };\n};\n\nexport default function compat(store) {\n  if (!store || store instanceof Map) {\n    // Convert it to the normalized kv, then add the expiry layer on top\n    return layers.expire(layers.memory(store || new Map()));\n  }\n  if (typeof localStorage !== \"undefined\" && store === localStorage) {\n    return layers.expire(layers.localStorage(store));\n  }\n  if (typeof sessionStorage !== \"undefined\" && store === sessionStorage) {\n    return layers.expire(layers.localStorage(store));\n  }\n  if (store === \"cookie\") {\n    return layers.cookie();\n  }\n  return layers.redis(store);\n}\n"],
+  "mappings": "AAAA,IAAMA,EAAS,CAAC,EAEVC,EAAQ,2DAEdC,EAAM,YAAcA,EAAM,GAAK,EAC/BA,EAAM,OAASA,EAAM,IAAMA,EAAM,EAAIA,EAAM,EAAE,EAAIA,EAAM,GAAK,IAC5DA,EAAM,OAASA,EAAM,IAAMA,EAAM,EAAIA,EAAM,EAAI,GAC/CA,EAAM,KAAOA,EAAM,GAAKA,EAAM,EAAIA,EAAM,EAAI,GAC5CA,EAAM,IAAMA,EAAM,EAAIA,EAAM,EAAI,GAChCA,EAAM,KAAOA,EAAM,GAAKA,EAAM,EAAIA,EAAM,EAAI,EAC5CA,EAAM,KAAOA,EAAM,GAAKA,EAAM,EAAIA,EAAM,EAAI,OAC5CA,EAAM,MAAQA,EAAM,EAAIA,EAAM,EAAI,GAElC,SAASA,EAAMC,EAAK,CAClB,GAAIA,GAAQ,KAA2B,OAAO,KAC9C,GAAI,OAAOA,GAAQ,SAAU,OAAOA,EAEpCA,EAAMA,EAAI,YAAY,EAAE,QAAQ,QAAS,EAAE,EAC3C,GAAI,CAACC,EAAGC,EAAOC,CAAK,EAAIL,EAAM,KAAKE,CAAG,GAAK,CAAC,EAC5C,GAAI,CAACG,EAAO,OAAO,KACnB,IAAMC,EAAYL,EAAMI,CAAK,GAAKJ,EAAMI,EAAM,QAAQ,KAAM,EAAE,CAAC,EAC/D,GAAI,CAACC,EAAW,OAAO,KACvB,IAAMC,EAASD,EAAY,WAAWF,EAAO,EAAE,EAC/C,OAAO,KAAK,IAAI,KAAK,MAAMG,CAAM,CAAC,CACpC,CAEAR,EAAO,OAAUS,GAAU,CAEzB,IAAMC,EAAM,MAAOC,GAAQ,CACzB,GAAI,CAAE,MAAMF,EAAM,IAAIE,CAAG,EAAI,OAAO,KACpC,GAAM,CAAE,KAAAC,EAAM,OAAAC,CAAO,EAAI,MAAMJ,EAAM,IAAIE,CAAG,EAC5C,OAAIE,IAAW,KAAaD,EACfC,EAAS,IAAI,KAAK,EAAE,QAAQ,GAC7B,EAAU,KACfD,CACT,EACME,EAAM,MAAOH,EAAKC,EAAM,CAAE,OAAAC,EAAS,IAAK,EAAI,CAAC,IAAM,CACvD,IAAME,EAAOb,EAAMW,CAAM,EACnBG,EAAUD,IAAS,KAAO,IAAI,KAAK,EAAE,QAAQ,EAAIA,EAAO,KAC9D,OAAON,EAAM,IAAIE,EAAK,CAAE,OAAQK,EAAS,KAAAJ,CAAK,CAAC,CACjD,EACMK,EAAM,MAAON,GAAS,MAAMF,EAAM,IAAIE,CAAG,IAAO,KAChDO,EAAMT,EAAM,IAGZU,EAAOV,EAAM,KACbW,EAAQX,EAAM,MAEpB,MAAO,CAAE,IAAAC,EAAK,IAAAI,EAAK,IAAAG,EAAK,IAAAC,EAAK,KAAAC,EAAM,MAAAC,CAAM,CAC3C,EAEApB,EAAO,OAAUS,IAYR,CAAE,IAVG,MAAOE,GAAQF,EAAM,IAAIE,CAAG,GAAK,KAU/B,IATF,MAAOA,EAAKC,IAASH,EAAM,IAAIE,EAAKC,CAAI,EASjC,IARP,MAAOD,GAAQF,EAAM,IAAIE,CAAG,EAQhB,IAPZ,MAAOA,GAAQF,EAAM,OAAOE,CAAG,EAOd,KAJhB,MAAOU,EAAS,KAC3B,CAAC,GAAI,MAAMZ,EAAM,KAAK,CAAE,EAAE,OAAQa,GAAMA,EAAE,WAAWD,CAAM,CAAC,EAG3B,MAFrB,IAAMZ,EAAM,MAAM,CAES,GAG3CT,EAAO,aAAgBS,IAYd,CAAE,IAVG,MAAOE,GAASF,EAAME,CAAG,EAAI,KAAK,MAAMF,EAAME,CAAG,CAAC,EAAI,KAUpD,IATF,MAAOA,EAAKC,IAASH,EAAM,QAAQE,EAAK,KAAK,UAAUC,CAAI,CAAC,EASrD,IARP,MAAOD,GAAQA,KAAOF,EAQV,IAPZ,MAAOE,GAAQF,EAAM,WAAWE,CAAG,EAOlB,KAJhB,MAAOU,EAAS,KAC3B,OAAO,KAAKZ,CAAK,EAAE,OAAQa,GAAMA,EAAE,WAAWD,CAAM,CAAC,EAGpB,MAFrB,IAAMZ,EAAM,MAAM,CAES,GAG3CT,EAAO,OAAS,IAAM,CACpB,IAAMU,EAAM,MAAOC,GAAQ,CACzB,IAAMN,EACJ,SAAS,OACN,MAAM,IAAI,EACV,OAAO,OAAO,EACd,KAAMkB,GAAQA,EAAI,WAAWZ,EAAM,GAAG,CAAC,GACtC,MAAM,GAAG,EAAE,CAAC,GAAK,KACvB,OAAO,KAAK,MAAM,mBAAmBN,CAAK,CAAC,CAC7C,EAEMS,EAAM,MAAOH,EAAKC,EAAM,CAAE,OAAAC,EAAS,IAAK,EAAI,CAAC,IAAM,CACvD,IAAME,EAAOb,EAAMW,CAAM,EACnBW,EAAM,IAAI,KAAK,EAAE,QAAQ,EACzBC,EACJV,IAAS,KAAO,aAAa,IAAI,KAAKS,EAAMT,CAAI,EAAE,YAAY,CAAC,GAAK,GAChEV,EAAQ,mBAAmB,KAAK,UAAUO,CAAI,CAAC,EACrD,SAAS,OAASD,EAAM,IAAMN,EAAQoB,CACxC,EACMR,EAAM,MAAON,IAAS,MAAMQ,EAAK,GAAG,SAASR,CAAG,EAChDO,EAAM,MAAOP,GAAQG,EAAIH,EAAK,GAAI,CAAE,OAAQ,IAAK,CAAC,EAGlDQ,EAAO,MAAOE,EAAS,KAC3B,SAAS,OACN,MAAM,GAAG,EACT,IAAKK,GAAMA,EAAE,MAAM,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,EACjC,OAAO,OAAO,EACd,OAAQJ,GAAMA,EAAE,WAAWD,CAAM,CAAC,EAKvC,MAAO,CAAE,IAAAX,EAAK,IAAAI,EAAK,IAAAG,EAAK,IAAAC,EAAK,KAAAC,EAAM,MAJrB,SAAY,CACxB,MAAM,QAAQ,KAAK,MAAMA,EAAK,GAAG,IAAID,CAAG,CAAC,CAC3C,CAEyC,CAC3C,EAEAlB,EAAO,MAASS,GAAU,CACxB,IAAMC,EAAM,MAAOC,GAAQ,CAEzB,IAAMN,EAAQ,MADC,MAAMI,GACM,IAAIE,CAAG,EAClC,OAAKN,EACE,KAAK,MAAMA,CAAK,EADJ,IAErB,EACMS,EAAM,MAAOH,EAAKN,EAAO,CAAE,OAAAQ,EAAS,IAAK,EAAI,CAAC,IAAM,CACxD,GAAIR,IAAU,MAAQQ,IAAW,EAAG,OAAOK,EAAIP,CAAG,EAClD,IAAMgB,EAAS,MAAMlB,EACfmB,EAAM1B,EAAMW,CAAM,EAClBgB,EAAKD,EAAM,KAAK,MAAMA,EAAM,GAAI,EAAI,OAC1C,OAAOD,EAAO,IAAIhB,EAAK,KAAK,UAAUN,CAAK,EAAG,CAAE,GAAAwB,CAAG,CAAC,CACtD,EACMZ,EAAM,MAAON,GAAQ,EAAQ,MAAO,MAAMF,GAAO,OAAOE,CAAG,EAC3DO,EAAM,MAAOP,IAAS,MAAMF,GAAO,IAAIE,CAAG,EAMhD,MAAO,CAAE,IAAAD,EAAK,IAAAI,EAAK,IAAAG,EAAK,IAAAC,EAAK,KAJhB,MAAOG,EAAS,MAAQ,MAAMZ,GAAO,KAAKY,EAAS,GAAG,EAIhC,MAHrB,UAAa,MAAMZ,GAAO,SAAS,EAGP,MAF5B,UAAa,MAAMA,GAAO,KAAK,CAEG,CAClD,EAEe,SAARqB,EAAwBrB,EAAO,CACpC,MAAI,CAACA,GAASA,aAAiB,IAEtBT,EAAO,OAAOA,EAAO,OAAOS,GAAS,IAAI,GAAK,CAAC,EAEpD,OAAO,aAAiB,KAAeA,IAAU,cAGjD,OAAO,eAAmB,KAAeA,IAAU,eAC9CT,EAAO,OAAOA,EAAO,aAAaS,CAAK,CAAC,EAE7CA,IAAU,SACLT,EAAO,OAAO,EAEhBA,EAAO,MAAMS,CAAK,CAC3B",
+  "names": ["layers", "times", "parse", "str", "_", "value", "units", "unitValue", "result", "store", "get", "key", "data", "expire", "set", "time", "expDiff", "has", "del", "keys", "clear", "prefix", "k", "row", "now", "expireStr", "l", "client", "exp", "EX", "compat"]
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "polystore",
+  "version": "0.1.0",
+  "description": "Add a unified API for any KV store like localStorage, Redis, FileSystem, etc.",
+  "homepage": "https://github.com/franciscop/polystore",
+  "repository": "https://github.com/franciscop/polystore.git",
+  "bugs": "https://github.com/franciscop/polystore/issues",
+  "funding": "https://www.paypal.me/franciscopresencia/19",
+  "author": "Francisco Presencia <public@francisco.io> (https://francisco.io/)",
+  "main": "index.min.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "esbuild src/index.js --bundle --minify --sourcemap --outfile=index.min.js --format=esm",
+    "size": "echo $(gzip -c index.min.js | wc -c) bytes",
+    "start": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch --coverage --detectOpenHandles",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --detectOpenHandles && check-dts"
+  },
+  "keywords": [],
+  "license": "MIT",
+  "devDependencies": {
+    "check-dts": "^0.7.2",
+    "dotenv": "^16.3.1",
+    "esbuild": "^0.19.4",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "redis": "^4.6.10"
+  },
+  "jest": {
+    "testEnvironment": "jsdom",
+    "transform": {}
+  }
+}

package/readme.md

@@ -0,0 +1,256 @@
+# Polystore [![npm install polystore](https://img.shields.io/badge/npm%20install-polystore-blue.svg)](https://www.npmjs.com/package/polystore) [![test badge](https://github.com/franciscop/fetch/workflows/tests/badge.svg "test badge")](https://github.com/franciscop/fetch/blob/master/.github/workflows/tests.yml) [![gzip size](https://img.badgesize.io/franciscop/fetch/master/index.min.js.svg?compression=gzip)](https://github.com/franciscop/fetch/blob/master/index.min.js)
+
+Add a unified API for any KV store like localStorage, Redis, FileSystem, etc:
+
+```js
+import kv from "polystore";
+const store = kv(new Map()); // in-memory
+const store1 = kv(localStorage); // Persist in the browser
+const store2 = kv(redisClient); // Use a Redis client for backend persistence
+// etc.
+```
+
+This is the [API](#api) with all of the methods (they are all `async`):
+
+- `.get(key): any`: retrieve a single value, or `null` if it doesn't exist or is expired.
+- `.set(key, value, options?)`: save a single value, which can be anything that is serializable.
+- `.has(key): boolean`: check whether the key is in the store or not.
+- `.del(key): void`: delete a single value from the store.
+- `.keys(prefix?): string[]`: get a list of all the available strings in the store.
+- `.clear()`: delete ALL of the data in the store, effectively resetting it.
+
+Available stores:
+
+- **Memory** `new Map()` (fe+be): an in-memory API to keep your KV store
+- **Local Storage** `localStorage` (fe): persist the data in the browser's localStorage
+- **Session Storage** `sessionStorage` (fe): persist the data in the browser's sessionStorage
+- **Cookies** `"cookie"` (fe): persist the data using cookies
+- (WIP) **LocalForage** `localForage` (fe): persist the data on IndexedDB
+- **Redis Client** `redisClient` (be): persist the data in the Redis instance that you connect to.
+- (WIP) **FS File** `fs.open(pathToFile)` (be): store the data in a single file
+- (WIP) **FS Folder** `fs.opendir(pathToFolder)` (be): store the data in files inside the folder
+- (WIP) **Cloudflare KV** `env.KV_NAMESPACE` (be): use Cloudflare's KV store
+
+It main usage is for _libraries using this library_, so that _your_ library can easily accept many cache stores! For example, let's say you create an API library, then you can accept the stores from your client:
+
+```js
+import MyApi from "my-api";
+
+MyApi({ cache: new Map() });
+// OR
+MyApi({ cache: localStorage });
+// OR
+MyApi({ cache: fs.opendir("./data/") });
+// OR
+MyApi({ cache: redisClient });
+// OR
+MyApi({ cache: env.KV_NAMESPACE });
+```
+
+## API
+
+See how to initialize each store [in the Stores list documentation](#stores). But basically for every store, it's like this:
+
+```js
+import kv from "polystore";
+
+// Initialize it
+const store = kv(MyClientOrStoreInstance);
+
+// use the store
+```
+
+While you can keep a reference and access it directly, we strongly recommend if you are going to use a store, to only access it through `polystore`, since we do add custom serialization, etc:
+
+```js
+const map = new Map();
+const store = kv(map);
+
+// Works as expected
+await store.set("a", "b");
+console.log(await store.get("a"));
+
+// DON'T DO THIS; this will break the app since we apply more
+// advanced serialization to the values stored in memory
+map.set("a", "b");
+console.log(await store.get("a")); // THROWS ERROR
+```
+
+### .get()
+
+Retrieve a single value from the store. Will return `null` if the value is not set in the store, or if it was set but has already expired:
+
+```js
+const value = await store.get(key: string);
+
+console.log(await store.get("key1"));  // "Hello World"
+console.log(await store.get("key2"));  // ["my", "grocery", "list"]
+console.log(await store.get("key3"));  // { name: "Francisco" }
+```
+
+If the value is returned, it can be a simple type like `boolean`, `string` or `number`, or it can be a plain Object or Array, or a combination of those.
+
+> The value cannot be more complex or non-serializable values like a `Date()`, `Infinity`, `undefined` (casted to `null`), a Symbol, etc.
+
+### .set()
+
+Create or update a value in the store. Will return a promise that resolves when the value has been saved. The value needs to be serializable:
+
+```js
+await store.set(key: string, value: any, options?: { expire: number|string });
+
+await store.set("key1", "Hello World");
+await store.set("key2", ["my", "grocery", "list"], { expire: "1h" });
+await store.set("key3", { name: "Francisco" }, { expire: 60 * 60 * 1000  });
+```
+
+The value can be a simple type like `boolean`, `string` or `number`, or it can be a plain Object or Array, or a combination of those. It **cannot** be a more complex or non-serializable values like a `Date()`, `Infinity`, `undefined` (casted to `null`), a `Symbol`, etc.
+
+- By default the keys _don't expire_.
+- Setting the `value` to `null`, or the `expire` to `0` is the equivalent of deleting the key+value.
+- Conversely, setting `expire` to `null` or `undefined` will make the value never to expire.
+
+#### Expire
+
+When the expire is set, it can be a number (ms) or a string representing some time:
+
+```js
+// Valid "expire" values:
+0 - expire immediately
+100 - expire after 100ms
+3_600_000 - expire after 1h
+60 * 60 * 1000 - expire after 1h
+"10s" - expire after 10 seconds
+"2minutes" - expire after 2 minutes
+"5d" - expire after 5 days
+```
+
+These are all the units available:
+
+> "ms", "millisecond", "s", "sec", "second", "m", "min", "minute", "h", "hr", "hour", "d", "day", "w", "wk", "week", "b" (month), "month", "y", "yr", "year"
+
+### .has()
+
+Check whether the key is available in the store and not expired:
+
+```js
+await store.has(key: string);
+```
+
+### .del()
+
+Remove a single key from the store:
+
+```js
+await store.del(key: string);
+```
+
+### .keys()
+
+Get all of the keys in the store, optionally filtered by a prefix:
+
+```js
+await store.keys(filter?: string);
+```
+
+### .clear()
+
+Remove all of the data from the store:
+
+```js
+await store.clear();
+```
+
+## Stores
+
+Accepts directly the store, or a promise that resolves into a store:
+
+### Memory
+
+```js
+import kv from "polystore";
+
+// This already works, by default if there's nothing it'll use
+// a new Map()
+const store = kv();
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+
+// Or you can be explicit:
+const store = kv(new Map());
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+```
+
+### Local Storage
+
+```js
+import kv from "polystore";
+
+const store = kv(localStorage);
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+```
+
+### Session Storage
+
+```js
+import kv from "polystore";
+
+const store = kv(sessionStorage);
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+```
+
+### Cookies
+
+```js
+import kv from "polystore";
+
+const store = kv("cookie"); // yes, just a plain string
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+```
+
+> Note: the cookie expire resolution is unfortunately in the seconds. While it still expects you to pass the number of ms as with the other methods (or a string like `1h`), times shorter than 1 second like `expire: 200` (ms) don't make sense for this storage method and won't properly save them.
+
+### Local Forage
+
+```js
+import kv from "polystore";
+// TODO
+```
+
+### Redis Client
+
+```js
+import kv from "polystore";
+import { createClient } from "redis";
+
+const store = kv(createClient().connect());
+await store.set("key1", "Hello world");
+console.log(await store.get("key1"));
+```
+
+> Note: the Redis client expire resolution is unfortunately in the seconds. While it still expects you to pass the number of ms as with the other methods (or a string like `1h`), times shorter than 1 second like `expire: 200` (ms) don't make sense for this storage method and won't properly save them.
+
+### FS File
+
+```js
+import kv from "polystore";
+// TODO
+```
+
+### FS Folder
+
+```js
+import kv from "polystore";
+// TODO
+```
+
+### Cloudflare KV
+
+```js
+import kv from "polystore";
+// TODO
+```

package/src/index.js

@@ -0,0 +1,157 @@
+const layers = {};
+
+const times = /(-?(?:\d+\.?\d*|\d*\.?\d+)(?:e[-+]?\d+)?)\s*([\p{L}]*)/iu;
+
+parse.millisecond = parse.ms = 1;
+parse.second = parse.sec = parse.s = parse[""] = parse.ms * 1000;
+parse.minute = parse.min = parse.m = parse.s * 60;
+parse.hour = parse.hr = parse.h = parse.m * 60;
+parse.day = parse.d = parse.h * 24;
+parse.week = parse.wk = parse.w = parse.d * 7;
+parse.year = parse.yr = parse.y = parse.d * 365.25;
+parse.month = parse.b = parse.y / 12;
+
+function parse(str) {
+  if (str === null || str === undefined) return null;
+  if (typeof str === "number") return str;
+  // ignore commas/placeholders
+  str = str.toLowerCase().replace(/[,_]/g, "");
+  let [_, value, units] = times.exec(str) || [];
+  if (!units) return null;
+  const unitValue = parse[units] || parse[units.replace(/s$/, "")];
+  if (!unitValue) return null;
+  const result = unitValue * parseFloat(value, 10);
+  return Math.abs(Math.round(result));
+}
+
+layers.expire = (store) => {
+  // Item methods
+  const get = async (key) => {
+    if (!(await store.has(key))) return null;
+    const { data, expire } = await store.get(key);
+    if (expire === null) return data;
+    const diff = expire - new Date().getTime();
+    if (diff <= 0) return null;
+    return data;
+  };
+  const set = async (key, data, { expire = null } = {}) => {
+    const time = parse(expire);
+    const expDiff = time !== null ? new Date().getTime() + time : null;
+    return store.set(key, { expire: expDiff, data });
+  };
+  const has = async (key) => (await store.get(key)) !== null;
+  const del = store.del;
+
+  // Group methods
+  const keys = store.keys;
+  const clear = store.clear;
+
+  return { get, set, has, del, keys, clear };
+};
+
+layers.memory = (store) => {
+  // Item methods
+  const get = async (key) => store.get(key) || null;
+  const set = async (key, data) => store.set(key, data);
+  const has = async (key) => store.has(key);
+  const del = async (key) => store.delete(key);
+
+  // Group methods
+  const keys = async (prefix = "") =>
+    [...(await store.keys())].filter((k) => k.startsWith(prefix)); // 🤷‍♂️
+  const clear = () => store.clear();
+
+  return { get, set, has, del, keys, clear };
+};
+
+layers.localStorage = (store) => {
+  // Item methods
+  const get = async (key) => (store[key] ? JSON.parse(store[key]) : null);
+  const set = async (key, data) => store.setItem(key, JSON.stringify(data));
+  const has = async (key) => key in store;
+  const del = async (key) => store.removeItem(key);
+
+  // Group methods
+  const keys = async (prefix = "") =>
+    Object.keys(store).filter((k) => k.startsWith(prefix));
+  const clear = () => store.clear();
+
+  return { get, set, has, del, keys, clear };
+};
+
+layers.cookie = () => {
+  const get = async (key) => {
+    const value =
+      document.cookie
+        .split("; ")
+        .filter(Boolean)
+        .find((row) => row.startsWith(key + "="))
+        ?.split("=")[1] || null;
+    return JSON.parse(decodeURIComponent(value));
+  };
+
+  const set = async (key, data, { expire = null } = {}) => {
+    const time = parse(expire);
+    const now = new Date().getTime();
+    const expireStr =
+      time !== null ? `; expires=${new Date(now + time).toUTCString()}` : "";
+    const value = encodeURIComponent(JSON.stringify(data));
+    document.cookie = key + "=" + value + expireStr;
+  };
+  const has = async (key) => (await keys()).includes(key);
+  const del = async (key) => set(key, "", { expire: -100 });
+
+  // Group methods
+  const keys = async (prefix = "") =>
+    document.cookie
+      .split(";")
+      .map((l) => l.split("=")[0].trim())
+      .filter(Boolean)
+      .filter((k) => k.startsWith(prefix));
+  const clear = async () => {
+    await Promise.all((await keys()).map(del));
+  };
+
+  return { get, set, has, del, keys, clear };
+};
+
+layers.redis = (store) => {
+  const get = async (key) => {
+    const client = await store;
+    const value = await client.get(key);
+    if (!value) return null;
+    return JSON.parse(value);
+  };
+  const set = async (key, value, { expire = null } = {}) => {
+    if (value === null || expire === 0) return del(key);
+    const client = await store;
+    const exp = parse(expire);
+    const EX = exp ? Math.round(exp / 1000) : undefined;
+    return client.set(key, JSON.stringify(value), { EX });
+  };
+  const has = async (key) => Boolean(await (await store).exists(key));
+  const del = async (key) => (await store).del(key);
+
+  const keys = async (prefix = "") => (await store).keys(prefix + "*");
+  const clear = async () => (await store).flushAll();
+  const close = async () => (await store).quit();
+
+  return { get, set, has, del, keys, clear, close };
+};
+
+export default function compat(store) {
+  if (!store || store instanceof Map) {
+    // Convert it to the normalized kv, then add the expiry layer on top
+    return layers.expire(layers.memory(store || new Map()));
+  }
+  if (typeof localStorage !== "undefined" && store === localStorage) {
+    return layers.expire(layers.localStorage(store));
+  }
+  if (typeof sessionStorage !== "undefined" && store === sessionStorage) {
+    return layers.expire(layers.localStorage(store));
+  }
+  if (store === "cookie") {
+    return layers.cookie();
+  }
+  return layers.redis(store);
+}

package/src/index.test.js

@@ -0,0 +1,182 @@
+import "dotenv/config";
+
+import { createClient } from "redis";
+
+import kv from "./";
+
+global.setImmediate = global.setImmediate || ((cb) => setTimeout(cb, 0));
+
+const stores = [];
+stores.push(["kv()", kv()]);
+stores.push(["kv(new Map())", kv(new Map())]);
+stores.push(["kv(localStorage)", kv(localStorage)]);
+stores.push(["kv(sessionStorage)", kv(sessionStorage)]);
+if (process.env.REDIS) {
+  stores.push(["kv(redis)", kv(createClient().connect())]);
+}
+stores.push(["kv('cookie')", kv("cookie")]);
+
+const delay = (t) => new Promise((done) => setTimeout(done, t));
+
+for (let [name, store] of stores) {
+  describe(name, () => {
+    beforeEach(async () => {
+      await store.clear();
+    });
+
+    afterAll(async () => {
+      if (store.close) {
+        await store.close();
+      }
+    });
+
+    it("is empty on the start", async () => {
+      expect(await store.get("a")).toBe(null);
+      expect(await store.has("a")).toBe(false);
+    });
+
+    it("can store values", async () => {
+      await store.set("a", "b");
+      expect(await store.get("a")).toBe("b");
+      expect(await store.has("a")).toBe(true);
+    });
+
+    it("can store basic types", async () => {
+      await store.set("a", 10);
+      expect(await store.get("a")).toEqual(10);
+      await store.set("a", "b");
+      expect(await store.get("a")).toEqual("b");
+      await store.set("a", true);
+      expect(await store.get("a")).toEqual(true);
+    });
+
+    it("can store arrays of JSON values", async () => {
+      await store.set("a", ["b"]);
+      expect(await store.get("a")).toEqual(["b"]);
+      expect(await store.has("a")).toBe(true);
+    });
+
+    it("can store objects", async () => {
+      await store.set("a", { b: "c" });
+      expect(await store.get("a")).toEqual({ b: "c" });
+      expect(await store.has("a")).toBe(true);
+    });
+
+    it("can retrieve the prefixed keys with colon", async () => {
+      await store.set("a:0", "a0");
+      await store.set("a:1", "a1");
+      await store.set("b:0", "b0");
+      await store.set("a:2", "b2");
+      expect((await store.keys("a:")).sort()).toEqual(["a:0", "a:1", "a:2"]);
+    });
+
+    it("can retrieve the prefixed keys with dash", async () => {
+      await store.set("a-0", "a0");
+      await store.set("a-1", "a1");
+      await store.set("b-0", "b0");
+      await store.set("a-2", "b2");
+      expect((await store.keys("a-")).sort()).toEqual(["a-0", "a-1", "a-2"]);
+    });
+
+    it("can delete the data", async () => {
+      await store.set("a", "b");
+      expect(await store.get("a")).toBe("b");
+      await store.del("a");
+      expect(await store.get("a")).toBe(null);
+    });
+
+    it("can get the keys", async () => {
+      await store.set("a", "b");
+      await store.set("c", "d");
+      expect(await store.keys()).toEqual(["a", "c"]);
+    });
+
+    it("can clear all the values", async () => {
+      await store.set("a", "b");
+      await store.set("c", "d");
+      expect(await store.get("a")).toBe("b");
+      await store.clear();
+      expect(await store.get("a")).toBe(null);
+      await store.set("a", "b");
+      expect(await store.get("a")).toBe("b");
+    });
+
+    describe("expires", () => {
+      it("expire = 0 means immediately", async () => {
+        await store.set("a", "b", { expire: 0 });
+        expect(await store.get("a")).toBe(null);
+      });
+
+      it("expire = potato means undefined = forever", async () => {
+        await store.set("a", "b", { expire: "potato" });
+        expect(await store.get("a")).toBe("b");
+        await delay(100);
+        expect(await store.get("a")).toBe("b");
+      });
+
+      it("expire = 5potato means undefined = forever", async () => {
+        await store.set("a", "b", { expire: "5potato" });
+        expect(await store.get("a")).toBe("b");
+        await delay(100);
+        expect(await store.get("a")).toBe("b");
+      });
+
+      it("expire = null means never to expire it", async () => {
+        await store.set("a", "b", { expire: null });
+        expect(await store.get("a")).toBe("b");
+        await delay(100);
+        expect(await store.get("a")).toBe("b");
+      });
+
+      it("expire = undefined means never to expire it", async () => {
+        await store.set("a", "b");
+        expect(await store.get("a")).toBe("b");
+        await delay(100);
+        expect(await store.get("a")).toBe("b");
+      });
+
+      if (name !== "kv('cookie')" && name !== "kv(redis)") {
+        it("can use 10 expire", async () => {
+          await store.set("a", "b", { expire: 10 });
+          expect(await store.get("a")).toBe("b");
+          await delay(100);
+          expect(await store.get("a")).toBe(null);
+        });
+
+        it("can use 0.01s expire", async () => {
+          await store.set("a", "b", { expire: "0.01s" });
+          expect(await store.get("a")).toBe("b");
+          await delay(100);
+          expect(await store.get("a")).toBe(null);
+        });
+
+        it("can use 0.01seconds expire", async () => {
+          await store.set("a", "b", { expire: "0.01seconds" });
+          expect(await store.get("a")).toBe("b");
+          await delay(100);
+          expect(await store.get("a")).toBe(null);
+        });
+
+        it("can use 10ms expire", async () => {
+          await store.set("a", "b", { expire: "10ms" });
+          expect(await store.get("a")).toBe("b");
+          await delay(100);
+          expect(await store.get("a")).toBe(null);
+        });
+      } else {
+        it("can use 1000 expire", async () => {
+          await store.set("a", "b", { expire: 1000 });
+          expect(await store.get("a")).toBe("b");
+          await delay(2000);
+          expect(await store.get("a")).toBe(null);
+        });
+        it("can use 1s expire", async () => {
+          await store.set("a", "b", { expire: "1s" });
+          expect(await store.get("a")).toBe("b");
+          await delay(2000);
+          expect(await store.get("a")).toBe(null);
+        });
+      }
+    });
+  });
+}

package/src/index.types.ts

@@ -0,0 +1,13 @@
+import kv from "..";
+
+const store = kv();
+
+(async () => {
+  const val = await store.get("key");
+  await store.set("key", "value");
+  await store.set("key", "value", {});
+  await store.set("key", "value", { expire: 100 });
+  await store.set("key", "value", { expire: "100s" });
+  if (await store.has("key")) {
+  }
+})();

package/tsconfig.json

@@ -0,0 +1 @@
+{ "exclude": ["node_modules"] }