npm - vanilla-create-storage - Versions diffs - 0.2.0 - Mend

vanilla-create-storage 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,130 @@
+# vanilla-storage
+A small async storage abstraction for browser storage drivers.
+## Install
+npm:
+```bash
+npm install vanilla-create-storage
+```
+script:
+```javascript
+// umd: GlobalName: storage
+<script src="https://unpkg.com/vanilla-create-storage/dist/index.umd.js"></script>
+const { createStorage } = storage;
+// es module
+import { createStorage } from 'https://unpkg.com/vanilla-create-storage/dist/index.mjs';
+```
+## Usage
+```js
+import { createStorage } from 'vanilla-create-storage';
+const storage = createStorage({
+  driver: 'indexedDB',
+  namespace: 'my-app',
+  fallback: ['localStorage', 'memory'],
+  ttl: 60_000,
+});
+await storage.set('user', { id: 1, name: 'Ada' });
+await storage.set('token', 'abc', { ttl: 5 * 60_000 });
+const user = await storage.get('user');
+const token = await storage.get('token', { defaultValue: null });
+await storage.delete('token');
+await storage.clear();
+```
+## API
+```js
+const storage = createStorage(options);
+await storage.set(key, value, options);
+await storage.get(key, options);
+await storage.has(key);
+await storage.delete(key);
+await storage.clear();
+await storage.keys();
+await storage.values();
+await storage.entries();
+await storage.size();
+await storage.prune();
+await storage.close();
+```
+## Options
+```js
+createStorage({
+  driver: 'localStorage',
+  namespace: 'vanilla-storage',
+  keySeparator: '::',
+  fallback: [],
+  ttl: null,
+  codec: 'json',
+  driverOptions: {},
+});
+```
+- `driver`: `'localStorage'`, `'sessionStorage'`, `'indexedDB'`, `'cookie'`, `'memory'`, an adapter, or an adapter factory.
+- `namespace`: key prefix used to isolate data. Set `null` to disable namespacing.
+- `fallback`: explicit fallback driver list. The library does not silently downgrade unless configured.
+- `ttl`: default time to live in milliseconds.
+- `codec`: `'json'`, `'raw-string'`, or a custom codec.
+- `driverOptions`: options passed to adapters.
+## Driver Options
+```js
+createStorage({
+  driver: 'cookie',
+  driverOptions: {
+    path: '/',
+    sameSite: 'lax',
+    secure: true,
+  },
+});
+createStorage({
+  driver: 'indexedDB',
+  driverOptions: {
+    dbName: 'MyAppStorage',
+    storeName: 'records',
+    version: 1,
+  },
+});
+```
+You can also scope options per driver:
+```js
+createStorage({
+  driver: 'indexedDB',
+  fallback: ['localStorage'],
+  driverOptions: {
+    indexedDB: { dbName: 'MyAppStorage' },
+    cookie: { path: '/', sameSite: 'lax' },
+  },
+});
+```
+## Design
+- All public methods are async, including synchronous browser storage drivers.
+- Stored records use a consistent envelope across drivers.
+- `clear()` only removes keys inside the configured namespace.
+- Expired records are lazily removed on read and can be eagerly removed with `prune()`.
+- Fallbacks are explicit so capacity and persistence semantics do not change silently.
+## Translations
+- [中文](README_zh.md)

package/dist/index.mjs ADDED Viewed

@@ -0,0 +1 @@

+ var e=class extends Error{constructor(e,t={}){super(e),this.name=this.constructor.name,this.code=t.code||`STORAGE_ERROR`,t.driver&&(this.driver=t.driver),t.key&&(this.key=t.key),t.details&&(this.details=t.details),t.cause&&(this.cause=t.cause)}},t=class extends e{constructor(e,t={}){super(e,{...t,code:`DRIVER_UNAVAILABLE`})}},n=class extends e{constructor(e,t={}){super(e,{...t,code:`QUOTA_EXCEEDED`})}},r=class extends e{constructor(e,t={}){super(e,{...t,code:`SERIALIZATION_FAILED`})}},i=class extends e{constructor(e,t={}){super(e,{...t,code:`INVALID_RECORD`})}};function a(e){return e?.name===`QuotaExceededError`||e?.name===`NS_ERROR_DOM_QUOTA_REACHED`||e?.code===22||e?.code===1014}function o(t,r={}){return t instanceof e?t:a(t)?new n(`Storage quota exceeded.`,{...r,cause:t}):new e(t?.message||`Storage operation failed.`,{...r,cause:t})}const s=new Set([`expires`,`max-age`,`domain`,`path`,`secure`,`httponly`,`samesite`]);var c=class{constructor(e={}){this.name=`cookie`,this.document=e.document,this.defaults={path:`/`,sameSite:void 0,secure:void 0,domain:void 0,...e},delete this.defaults.document}_getDocument(){let e=this.document||(typeof globalThis<`u`?globalThis.document:void 0);if(!e?.cookie&&e?.cookie!==``)throw new t(`document.cookie is not available.`,{driver:this.name});return e}async isAvailable(){let e=`__vanilla_storage_test__${Date.now()}_${Math.random()}`;try{await this.setRaw(e,`1`);let t=await this.getRaw(e)===`1`;return await this.deleteRaw(e),t}catch{return!1}}async getRaw(e){try{let t=encodeURIComponent(e),n=this._getDocument().cookie.split(`;`);for(let e of n){let n=e.indexOf(`=`);if(n<0)continue;let r=e.slice(0,n).trim(),i=e.slice(n+1);if(r===t)return decodeURIComponent(i)}return}catch(t){throw o(t,{driver:this.name,key:e})}}async setRaw(e,t){try{this._setCookie(e,t,this.defaults)}catch(t){throw o(t,{driver:this.name,key:e})}}async deleteRaw(e){try{this._setCookie(e,``,{...this.defaults,expires:new Date(0),maxAge:0})}catch(t){throw o(t,{driver:this.name,key:e})}}async clearRaw(e=``){let t=await this.keysRaw(e);for(let e of t)await this.deleteRaw(e)}async keysRaw(e=``){try{let t=[],n=this._getDocument().cookie.split(`;`);for(let r of n){let n=r.indexOf(`=`);if(n<0)continue;let i=r.slice(0,n).trim(),a=decodeURIComponent(i);(!e||a.startsWith(e))&&t.push(a)}return t}catch(e){throw o(e,{driver:this.name})}}_setCookie(e,t,n){this._validateCookieKey(e);let r=`${encodeURIComponent(e)}=${encodeURIComponent(t)}`;if(n.expires){let e=n.expires instanceof Date?n.expires:new Date(n.expires);r+=`; Expires=${e.toUTCString()}`}if(n.maxAge!==void 0&&(r+=`; Max-Age=${Math.floor(n.maxAge)}`),n.domain&&(r+=`; Domain=${n.domain}`),n.path&&(r+=`; Path=${n.path}`),n.sameSite){let e=l(n.sameSite);r+=`; SameSite=${e}`}n.secure&&(r+=`; Secure`),this._getDocument().cookie=r}_validateCookieKey(e){if(s.has(e.toLowerCase()))throw new i(`Cookie key "${e}" is reserved.`,{driver:this.name,key:e});if(/[\s=;,]/.test(e))throw new i(`Cookie key cannot contain whitespace, equals, comma, or semicolon.`,{driver:this.name,key:e})}};function l(e){let t=String(e).toLowerCase();if(t===`strict`)return`Strict`;if(t===`lax`)return`Lax`;if(t===`none`)return`None`;throw new i(`Cookie sameSite must be "strict", "lax", or "none".`,{driver:`cookie`})}var u=class{constructor(e={}){this.name=`indexedDB`,this.dbName=e.dbName||`VanillaStorage`,this.storeName=e.storeName||`records`,this.version=e.version||1,this.indexedDB=e.indexedDB||d(),this.db=null,this.openPromise=null}async isAvailable(){if(!this.indexedDB)return!1;try{return await this._open(),!0}catch{return!1}}async getRaw(e){try{return await this._getRecordValue(e)}catch(t){throw o(t,{driver:this.name,key:e})}}async setRaw(e,t){try{await this._writeRecord(n=>n.put({key:e,value:t}))}catch(t){throw o(t,{driver:this.name,key:e})}}async deleteRaw(e){try{await this._writeRecord(t=>t.delete(e))}catch(t){throw o(t,{driver:this.name,key:e})}}async clearRaw(e=``){if(!e){await this._writeRecord(e=>e.clear());return}let t=await this.keysRaw(e);await this._writeRecord(e=>{for(let n of t)e.delete(n)})}async keysRaw(e=``){let t=await this._readAllKeys();return e?t.filter(t=>t.startsWith(e)):t}async close(){this.db&&(this.db.close(),this.db=null,this.openPromise=null)}async _open(){if(this.db)return this.db;if(!this.indexedDB)throw new t(`indexedDB is not available.`,{driver:this.name});return this.openPromise||(this.openPromise=new Promise((e,t)=>{let n=this.indexedDB.open(this.dbName,this.version);n.onupgradeneeded=()=>{let e=n.result;e.objectStoreNames.contains(this.storeName)||e.createObjectStore(this.storeName,{keyPath:`key`})},n.onsuccess=()=>{this.db=n.result,this.db.onversionchange=()=>{this.close()},e(this.db)},n.onerror=()=>{t(n.error)},n.onblocked=()=>{t(new i(`IndexedDB upgrade is blocked by another open connection.`,{driver:this.name}))}})),this.openPromise}async _getRecordValue(e){let t=await this._open();return await new Promise((n,r)=>{let i=t.transaction(this.storeName,`readonly`),a=i.objectStore(this.storeName).get(e),o;i.oncomplete=()=>{n(o)},i.onerror=()=>r(i.error),i.onabort=()=>r(i.error),a.onsuccess=()=>{o=a.result&&a.result.value!==void 0?a.result.value:void 0},a.onerror=()=>r(a.error)})}async _writeRecord(e){let t=await this._open();return await new Promise((n,r)=>{let i=t.transaction(this.storeName,`readwrite`),a=i.objectStore(this.storeName);i.oncomplete=()=>n(void 0),i.onerror=()=>r(i.error),i.onabort=()=>r(i.error);try{let t=e(a);t&&(t.onerror=()=>r(t.error))}catch(e){i.abort(),r(e)}})}async _readAllKeys(){return typeof IDBObjectStore<`u`&&IDBObjectStore.prototype.getAllKeys?await this._requestKeysWithGetAllKeys():await this._requestKeysWithCursor()}async _requestKeysWithGetAllKeys(){let e=await this._open();return await new Promise((t,n)=>{let r=e.transaction(this.storeName,`readonly`),i=r.objectStore(this.storeName).getAllKeys(),a=[];r.oncomplete=()=>t(a),r.onerror=()=>n(r.error),r.onabort=()=>n(r.error),i.onsuccess=()=>{a=i.result.filter(e=>typeof e==`string`)},i.onerror=()=>n(i.error)})}async _requestKeysWithCursor(){let e=await this._open();return await new Promise((t,n)=>{let r=e.transaction(this.storeName,`readonly`),i=r.objectStore(this.storeName),a=[],o=i.openCursor();r.oncomplete=()=>t(a),r.onerror=()=>n(r.error),r.onabort=()=>n(r.error),o.onsuccess=()=>{let e=o.result;e&&(typeof e.key==`string`&&a.push(e.key),e.continue())},o.onerror=()=>n(o.error)})}};function d(){if(!(typeof globalThis>`u`))return globalThis.indexedDB}var f=class{constructor(e={}){this.name=`memory`,this.map=e.map||new Map}async isAvailable(){return!0}async getRaw(e){return this.map.has(e)?this.map.get(e):void 0}async setRaw(e,t){this.map.set(e,t)}async deleteRaw(e){this.map.delete(e)}async clearRaw(e=``){for(let t of this.map.keys())(!e||t.startsWith(e))&&this.map.delete(t)}async keysRaw(e=``){return Array.from(this.map.keys()).filter(t=>!e||t.startsWith(e))}};function p(){return`__vanilla_storage_test__${Date.now()}_${Math.random()}`}var m=class{constructor(e=`localStorage`,t={}){this.name=e,this.type=e,this.storage=t.storage||null,this.window=t.window}_getStorage(){if(this.storage)return this.storage;let e=(this.window||(typeof globalThis<`u`?globalThis:void 0))?.[this.type];if(!e)throw new t(`${this.type} is not available.`,{driver:this.name});return e}async isAvailable(){let e=p();try{let t=this._getStorage();return t.setItem(e,`1`),t.removeItem(e),!0}catch{return!1}}async getRaw(e){try{let t=this._getStorage().getItem(e);return t===null?void 0:t}catch(t){throw o(t,{driver:this.name,key:e})}}async setRaw(e,t){try{this._getStorage().setItem(e,t)}catch(t){throw o(t,{driver:this.name,key:e})}}async deleteRaw(e){try{this._getStorage().removeItem(e)}catch(t){throw o(t,{driver:this.name,key:e})}}async clearRaw(e=``){let t=this._getStorage(),n=await this.keysRaw(e);try{for(let e of n)t.removeItem(e)}catch(e){throw o(e,{driver:this.name})}}async keysRaw(e=``){let t=this._getStorage(),n=[];try{for(let r=0;r<t.length;r+=1){let i=t.key(r);i&&(!e||i.startsWith(e))&&n.push(i)}}catch(e){throw o(e,{driver:this.name})}return n}},h=class extends m{constructor(e={}){super(`localStorage`,e)}},g=class extends m{constructor(e={}){super(`sessionStorage`,e)}};const _={name:`json`,serialize(e){if(typeof e==`function`||typeof e==`symbol`)throw new r(`JSON codec cannot serialize functions or symbols.`);if(e===void 0)return`{"type":"undefined"}`;try{return JSON.stringify({type:`json`,value:e})}catch(e){throw new r(`Failed to serialize value with JSON codec.`,{cause:e})}},deserialize(e){try{let t=JSON.parse(e);if(t?.type===`undefined`)return;if(t?.type===`json`)return t.value;throw Error(`Invalid JSON codec payload.`)}catch(e){throw new r(`Failed to deserialize value with JSON codec.`,{cause:e})}}},v={name:`raw-string`,serialize(e){if(typeof e!=`string`)throw new r(`Raw string codec can only serialize string values.`);return e},deserialize(e){return e}},y=Symbol(`vanilla-storage.missing`);function b(e,t){return Object.prototype.hasOwnProperty.call(e,t)}function x(e){return typeof e==`object`&&!!e}function S(e){if(typeof e!=`string`||e.length===0)throw TypeError(`Storage key must be a non-empty string.`);return e}function C(e){if(e===void 0)return`vanilla-storage`;if(e===null||e===!1)return``;if(typeof e!=`string`)throw TypeError(`Storage namespace must be a string.`);return e}function w(e){if(e===void 0)return`::`;if(typeof e!=`string`)throw TypeError(`Storage keySeparator must be a string.`);return e}function T(e,t){let n=e instanceof Date?e.getTime():e;if(!Number.isFinite(n))throw TypeError(`${t} must be a finite timestamp or Date.`);return n}function E(e,t=`ttl`){if(e==null||e===!1||e===1/0)return null;if(!Number.isFinite(e)||e<0)throw TypeError(`${t} must be a non-negative number.`);return e}function D(e){let t=new Set,n=[];for(let r of e){let e=typeof r==`string`?r:r?.name||r;t.has(e)||(t.add(e),n.push(r))}return n}const O={cookie:e=>new c(e),indexedDB:e=>new u(e),localStorage:e=>new h(e),memory:e=>new f(e),sessionStorage:e=>new g(e)},k={json:_,"raw-string":v};var A=class{constructor(e={}){let t=typeof e==`string`?{driver:e}:{...e};this.driver=t.driver||`localStorage`,this.fallback=M(t.fallback),this.namespace=C(t.namespace),this.keySeparator=w(t.keySeparator),this.defaultTtl=E(t.ttl),this.clock=t.clock||Date.now,this.driverOptions=t.driverOptions||{},this.adapters=t.adapters||{},this.codec=N(t.codec||_),this.codecs=P(t.codecs,this.codec),this.onDriverError=t.onDriverError,this._adapter=null,this._adapterPromise=null}get prefix(){return this.namespace?`${this.namespace}${this.keySeparator}`:``}get activeDriver(){return this._adapter?.name||null}get ready(){return this._getAdapter()}async set(e,t,n={}){let r=this._fullKey(e),i=await this._getAdapter(),a=this._encodeRecord(t,n);await i.setRaw(r,a)}async get(e,t={}){let n=await this._read(e,{deserialize:!0});return n===y?b(t,`defaultValue`)?t.defaultValue:void 0:n}async has(e){return await this._read(e,{deserialize:!1})!==y}async delete(e){await(await this._getAdapter()).deleteRaw(this._fullKey(e))}async remove(e){await this.delete(e)}async clear(){await(await this._getAdapter()).clearRaw(this.prefix)}async keys(){return await this._liveKeys()}async rawKeys(){return(await(await this._getAdapter()).keysRaw(this.prefix)).map(e=>e.slice(this.prefix.length))}async values(){return(await this.entries()).map(e=>e[1])}async entries(){let e=await this.keys(),t=[];for(let n of e){let e=await this._read(n,{deserialize:!0});e!==y&&t.push([n,e])}return t}async size(){return(await this.keys()).length}async prune(e={}){let t=await this._getAdapter(),n=await t.keysRaw(this.prefix),r=0;for(let i of n){let n=await t.getRaw(i);n!==void 0&&this._inspectRaw(n,i,{removeInvalid:e.removeInvalid===!0})===`delete`&&(await t.deleteRaw(i),r+=1)}return r}async close(){this._adapter?.close&&await this._adapter.close(),this._adapter=null,this._adapterPromise=null}async _read(e,t){let n=this._fullKey(e),r=await this._getAdapter(),i=await r.getRaw(n);if(i===void 0)return y;let a=this._decodeRecord(i,n);return this._isExpired(a)?(await r.deleteRaw(n),y):t.deserialize?this._deserializeRecord(a,n):!0}_encodeRecord(e,t){let n=N(t.codec||this.codec),i=this._resolveExpiresAt(t),a;this.codecs.set(n.name,n);try{a=n.serialize(e)}catch(e){throw e instanceof r?e:new r(`Failed to serialize value.`,{cause:e})}if(typeof a!=`string`)throw new r(`Storage codec serialize() must return a string.`);return JSON.stringify({v:1,codec:n.name||`custom`,expiresAt:i,value:a})}_decodeRecord(e,t){let n;try{n=JSON.parse(e)}catch(e){throw new i(`Stored record is not valid JSON.`,{key:t,cause:e})}if(!x(n)||n.v!==1||typeof n.value!=`string`||!b(n,`expiresAt`))throw new i(`Stored record has an unsupported format.`,{key:t,details:n});return n}_deserializeRecord(e,t){let n=this.codecs.get(e.codec);if(!n)throw new r(`No codec registered for stored record codec "${e.codec}".`,{key:t});try{return n.deserialize(e.value)}catch(e){throw e instanceof r?e:new r(`Failed to deserialize value.`,{key:t,cause:e})}}_inspectRaw(e,t,n){try{let n=this._decodeRecord(e,t);return this._isExpired(n)?`delete`:`keep`}catch(e){if(n.removeInvalid)return`delete`;throw e}}_isExpired(e){return e.expiresAt!==null&&e.expiresAt<=this.clock()}_resolveExpiresAt(e){if(b(e,`expiresAt`))return e.expiresAt===null||e.expiresAt===!1?null:T(e.expiresAt,`expiresAt`);let t=b(e,`ttl`)?E(e.ttl):this.defaultTtl;return t===null?null:this.clock()+t}_fullKey(e){return`${this.prefix}${S(e)}`}async _getAdapter(){return this._adapter?this._adapter:(this._adapterPromise||(this._adapterPromise=this._selectAdapter()),this._adapter=await this._adapterPromise,this._adapter)}async _selectAdapter(){let e=D([this.driver,...this.fallback]),n=[];for(let t of e)try{let e=this._createAdapter(t);if(typeof e.isAvailable!=`function`||await e.isAvailable())return e;n.push({driver:e.name,error:`Driver reported unavailable.`})}catch(e){let r=typeof t==`string`?t:t?.name||`custom`;n.push({driver:r,error:e}),this.onDriverError?.(e,r)}throw new t(`No configured storage driver is usable.`,{details:n})}_createAdapter(e){if(F(e))return e;if(typeof e==`function`){let t=e({driverOptions:this.driverOptions,storage:this});if(!F(t))throw TypeError(`Custom storage driver must return an adapter.`);return t}if(typeof e!=`string`)throw TypeError(`Storage driver must be a string, adapter, or factory.`);let n=this.adapters[e];if(n)return this._createAdapter(n);let r=O[e];if(!r)throw new t(`Unsupported storage driver: ${e}`,{driver:e});return r(this._driverOptions(e))}_driverOptions(e){let t=this.driverOptions||{};return[`cookie`,`indexedDB`,`localStorage`,`memory`,`sessionStorage`,`shared`].some(e=>b(t,e))?{...t.shared,...t[e]}:t}async _liveKeys(){let e=await this._getAdapter(),t=await e.keysRaw(this.prefix),n=[];for(let r of t){let t=await e.getRaw(r);if(t===void 0)continue;let i=this._decodeRecord(t,r);if(this._isExpired(i)){await e.deleteRaw(r);continue}n.push(r.slice(this.prefix.length))}return n}};function j(e){return new A(e)}function M(e){if(e==null||e===!1)return[];if(typeof e==`string`||F(e)||typeof e==`function`)return[e];if(!Array.isArray(e))throw TypeError(`Storage fallback must be a driver or an array.`);return e}function N(e){if(typeof e==`string`){let t=k[e];if(!t)throw new r(`Unsupported storage codec: ${e}`);return t}if(!e||typeof e.serialize!=`function`||typeof e.deserialize!=`function`)throw TypeError(`Storage codec must provide serialize(value) and deserialize(value).`);return{name:e.name||`custom`,serialize:e.serialize.bind(e),deserialize:e.deserialize.bind(e)}}function P(e,t){let n=new Map;for(let e of Object.values(k))n.set(e.name,e);if(n.set(t.name,t),!e)return n;let r=Array.isArray(e)?e:Object.values(e);for(let e of r){let t=N(e);n.set(t.name,t)}return n}function F(e){return e&&typeof e.getRaw==`function`&&typeof e.setRaw==`function`&&typeof e.deleteRaw==`function`&&typeof e.clearRaw==`function`&&typeof e.keysRaw==`function`}export{c as CookieAdapter,u as IndexedDBAdapter,h as LocalStorageAdapter,f as MemoryAdapter,g as SessionStorageAdapter,A as Storage,i as StorageDataError,n as StorageQuotaError,r as StorageSerializationError,t as StorageUnavailableError,e as VanillaStorageError,m as WebStorageAdapter,j as createStorage,_ as jsonCodec,v as rawStringCodec};

package/dist/index.umd.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "name": "vanilla-create-storage",
+  "version": "0.2.0",
+  "private": false,
+  "description": "A small async storage abstraction for browser storage drivers.",
+  "keywords": [
+    "cookie",
+    "indexedDB",
+    "javascript",
+    "localStorage",
+    "ttl",
+    "vanilla"
+  ],
+  "homepage": "https://github.com/WangShai123/vanilla-storage",
+  "bugs": {
+    "url": "https://github.com/WangShai123/vanilla-storage/issues"
+  },
+  "license": "ISC",
+  "author": "Wang Shai <hiwangshai@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WangShai123/vanilla-storage.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "browser": "./dist/index.umd.js",
+  "unpkg": "./dist/index.umd.js",
+  "exports": {
+    ".": {
+      "browser": "./dist/index.umd.js",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp dev",
+    "test": "vp test",
+    "check": "vp check",
+    "lint": "vp lint",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "vite-plus": "^0.1.23"
+  },
+  "fullname": "vanilla-create-storage"
+}