@ad-execute-manager/storage 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 singcl
+
+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/README.md

@@ -0,0 +1,276 @@
+# @ad-execute-manager/storage
+
+A flexible storage utility for JavaScript applications with expiration support, user-specific storage, and customizable prefixes.
+
+## Installation
+
+```bash
+npm install @ad-execute-manager/storage
+```
+
+## Features
+
+- **Expiration Support**: Set expiration times for stored items, including 'today' option for day-bound data
+- **User-specific Storage**: Store data per user with automatic userId prefixing
+- **Customizable Prefix**: Add a prefix to identify the source of storage items
+- **Synchronous Operations**: Uses synchronous storage methods for simple integration
+- **Error Handling**: Built-in error handling for storage operations
+- **TypeScript Support**: Includes TypeScript type definitions
+- **Logger Integration**: Uses @ad-execute-manager/logger for logging storage operations
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create a storage instance
+const storage = new Storage({
+  prefix: 'myapp_',
+  expire: null // Default expiration (null = never expire)
+});
+
+// Set data with different expiration options
+
+// Set data that expires today
+storage.setItem('dailyTask', { completed: false }, 'today');
+
+// Set data with custom expiration (2 hours)
+storage.setItem('tempData', { value: 123 }, 2 * 60 * 60 * 1000);
+
+// Set permanent data
+storage.setItem('userSettings', { theme: 'dark' });
+
+// Get data
+const dailyTask = storage.getItem('dailyTask');
+const tempData = storage.getItem('tempData');
+const userSettings = storage.getItem('userSettings');
+
+console.log('Daily Task:', dailyTask);
+console.log('Temp Data:', tempData);
+console.log('User Settings:', userSettings);
+```
+
+### User-specific Storage
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create storage instance with userId
+const userStorage = new Storage({
+  prefix: 'app_',
+  userId: 'user123'
+});
+
+// Set user-specific data
+userStorage.setUserItem('preferences', { theme: 'light', language: 'en' });
+userStorage.setUserItem('lastLogin', new Date().toISOString());
+
+// Get user-specific data
+const preferences = userStorage.getUserItem('preferences');
+const lastLogin = userStorage.getUserItem('lastLogin');
+
+console.log('User Preferences:', preferences);
+console.log('Last Login:', lastLogin);
+```
+
+### Advanced Usage
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create storage instance
+const storage = new Storage({
+  prefix: 'app_',
+  expire: 24 * 60 * 60 * 1000 // Default to 24 hours
+});
+
+// Set data
+storage.setItem('session', { token: 'abc123' });
+
+// Get all keys
+const allKeys = storage.keys();
+console.log('All stored keys:', allKeys);
+
+// Remove an item
+storage.removeItem('tempData');
+
+// Clear all storage
+// storage.clear(); // Uncomment to clear all storage
+
+// Using the static new method
+const anotherStorage = Storage.new({
+  prefix: 'another_'
+});
+
+anotherStorage.setItem('test', { value: 'hello' });
+```
+
+## API
+
+### Constructor
+
+```javascript
+new Storage(options)
+```
+
+- **options** (Object): Configuration options
+  - **prefix** (String): Storage key prefix, defaults to 'storage_'
+  - **expire** (Number|null): Default expiration time in milliseconds, null for never expire, defaults to null
+  - **userId** (String|Number): User ID for user-specific storage
+
+### Methods
+
+#### Basic Storage
+
+- **setItem(key, value, expire)**: Set a storage item
+  - **key** (String): Storage key
+  - **value** (Any): Value to store (will be JSON stringified)
+  - **expire** (Number|'today'|null): Expiration time in milliseconds, 'today' for day-bound, or null for no expiration
+
+- **getItem(key)**: Get a storage item
+  - **key** (String): Storage key
+  - **returns** (Any|null): Stored value or null if expired/non-existent
+
+- **removeItem(key)**: Remove a storage item
+  - **key** (String): Storage key
+
+- **clear()**: Clear all storage items
+
+- **keys()**: Get all non-expired storage keys
+  - **returns** (Array): Array of storage keys without prefix
+
+#### User-specific Storage
+
+- **setUserItem(key, value, expire)**: Set a user-specific storage item
+  - **key** (String): Storage key
+  - **value** (Any): Value to store
+  - **expire** (Number|'today'|null): Expiration time
+
+- **getUserItem(key)**: Get a user-specific storage item
+  - **key** (String): Storage key
+  - **returns** (Any|null): Stored value or null if expired/non-existent
+
+#### Static Methods
+
+- **Storage.new(options)**: Create a new Storage instance
+  - **options** (Object): Same as constructor options
+  - **returns** (Storage): New Storage instance
+
+## Examples
+
+### Example 1: Daily Task Management
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create storage for daily tasks
+const taskStorage = new Storage({
+  prefix: 'tasks_',
+  expire: null
+});
+
+// Set daily task (expires today)
+taskStorage.setItem('dailyTask', {
+  id: 1,
+  title: 'Complete tutorial',
+  completed: false
+}, 'today');
+
+// Get daily task
+const dailyTask = taskStorage.getItem('dailyTask');
+
+if (dailyTask) {
+  console.log('Daily task:', dailyTask);
+  
+  // Mark task as completed
+  dailyTask.completed = true;
+  taskStorage.setItem('dailyTask', dailyTask, 'today');
+  
+  console.log('Task marked as completed');
+} else {
+  console.log('No active daily task');
+}
+```
+
+### Example 2: User Preferences
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create user-specific storage
+const userStorage = new Storage({
+  prefix: 'user_',
+  userId: 'user123',
+  expire: null
+});
+
+// Set user preferences
+userStorage.setUserItem('preferences', {
+  theme: 'dark',
+  language: 'en',
+  notifications: true
+});
+
+// Get user preferences
+const preferences = userStorage.getUserItem('preferences');
+console.log('User preferences:', preferences);
+
+// Update preferences
+if (preferences) {
+  preferences.theme = 'light';
+  userStorage.setUserItem('preferences', preferences);
+  console.log('Preferences updated');
+}
+```
+
+### Example 3: Session Management
+
+```javascript
+import { Storage } from '@ad-execute-manager/storage';
+
+// Create session storage with 1-hour expiration
+const sessionStorage = new Storage({
+  prefix: 'session_',
+  expire: 60 * 60 * 1000 // 1 hour
+});
+
+// Set session data
+sessionStorage.setItem('session', {
+  token: 'abc123xyz789',
+  userId: 'user123',
+  timestamp: Date.now()
+});
+
+// Check if session is valid
+function checkSession() {
+  const session = sessionStorage.getItem('session');
+  
+  if (session) {
+    console.log('Session is valid:', session);
+    return true;
+  } else {
+    console.log('Session expired or not found');
+    return false;
+  }
+}
+
+// Refresh session
+sessionStorage.setItem('session', {
+  token: 'newToken123',
+  userId: 'user123',
+  timestamp: Date.now()
+});
+
+console.log('Session refreshed');
+checkSession();
+```
+
+## Dependencies
+
+- **@ad-execute-manager/logger**: For logging storage operations
+
+## License
+
+MIT

package/dist/Storage.d.ts

@@ -0,0 +1,124 @@
+export default Storage;
+export type StorageOptions = {
+    /**
+     * 存储key的前缀
+     */
+    prefix?: string;
+    /**
+     * 默认过期时间（毫秒），null表示永不过期
+     */
+    expire?: number | null;
+    /**
+     * 用户ID
+     */
+    userId?: string | number;
+};
+/**
+ * @example
+const storage = new Storage({
+  prefix: 'myapp_',
+});
+
+// 设置当天有效的数据
+*storage.setItem('dailyTask', { completed: false }, 'today');
+
+// 设置普通带过期时间的数据（2小时）
+storage.setItem('tempData', { value: 123 }, 2 * 60 * 60 * 1000);
+
+// 设置永久有效的数据
+storage.setItem('userSettings', { theme: 'dark' });
+
+// 获取数据
+const dailyTask = storage.getStorageSync('dailyTask');
+const tempData = storage.getStorageSync('tempData');
+const userSettings = storage.getStorageSync('userSettings');
+
+console.log('Daily Task:', dailyTask);
+console.log('Temp Data:', tempData);
+console.log('User Settings:', userSettings);
+ */
+declare class Storage {
+    /**
+     * @param {StorageOptions=} args
+     * @returns
+     */
+    static "new"(args?: StorageOptions | undefined): Storage;
+    /**
+     * @param {StorageOptions} [options]
+     */
+    constructor(options?: StorageOptions);
+    config: {
+        /**
+         * 存储key的前缀
+         */
+        prefix: string;
+        /**
+         * 默认过期时间（毫秒），null表示永不过期
+         */
+        expire: number | null;
+        /**
+         * 用户ID
+         */
+        userId?: string | number;
+    };
+    logger: Logger;
+    /**
+     * 获取当天结束时间的时间戳
+     * @returns {number} 当天23:59:59的时间戳
+     */
+    getTodayEndTimestamp(): number;
+    /**
+     * 设置存储项 - 内部使用
+     * @param {string} key 存储键
+     * @param {any} value 存储值
+     * @param {number|'today'} expire 过期时间（毫秒）或'today'表示当天有效，可选
+     */
+    _setItem(storageKey: any, value: any, expire: number | "today"): void;
+    /**
+     * 获取存储项 - 内部使用
+     * @param {string} key 存储键
+     * @returns {any} 存储的值，如果过期或不存在则返回null
+     */
+    _getItem(storageKey: any): any;
+    /**
+     * 设置存储项
+     * @param {string} key 存储键
+     * @param {any} value 存储值
+     * @param {number|'today'} expire 过期时间（毫秒）或'today'表示当天有效，可选
+     */
+    setItem(key: string, value: any, expire: number | "today"): void;
+    /**
+     * 获取存储项
+     * @param {string} key 存储键
+     * @returns {any} 存储的值，如果过期或不存在则返回null
+     */
+    getItem(key: string): any;
+    /**
+     * 获取存储项 - 用户维度
+     * @param {string} key 存储键
+     * @returns {any} 存储的值，如果过期或不存在则返回null
+     */
+    getUserItem(key: string): any;
+    /**
+     * 设置存储项 - 用户维度
+     * @param {string} key 存储键
+     * @param {any} value 存储值
+     * @param {number|'today'} expire 过期时间（毫秒）或'today'表示当天有效，可选
+     */
+    setUserItem(key: string, value: any, expire: number | "today"): void;
+    /**
+     * 删除存储项
+     * @param {string} key 存储键
+     */
+    removeItem(key: string): void;
+    /**
+     * 清空所有存储项
+     */
+    clear(): void;
+    /**
+     * 获取所有未过期的存储键
+     * @returns {string[]} 键数组
+     */
+    keys(): string[];
+}
+import { Logger } from '@ad-execute-manager/logger';

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";const __rslib_import_meta_url__="u"<typeof document?new(require("url".replace("",""))).URL("file:"+__filename).href:document.currentScript&&document.currentScript.src||new URL("main.js",document.baseURI).href;var __webpack_require__={};__webpack_require__.d=(e,r)=>{for(var t in r)__webpack_require__.o(r,t)&&!__webpack_require__.o(e,t)&&Object.defineProperty(e,t,{enumerable:!0,get:r[t]})},__webpack_require__.o=(e,r)=>Object.prototype.hasOwnProperty.call(e,r),__webpack_require__.r=e=>{"u">typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})};var __webpack_exports__={};__webpack_require__.r(__webpack_exports__),__webpack_require__.d(__webpack_exports__,{Storage:()=>src_Storage});const logger_namespaceObject=require("@ad-execute-manager/logger");class Storage{constructor(e={}){this.config={prefix:"storage_",expire:null,...e},this.logger=new logger_namespaceObject.Logger({prefix:"Storage"})}getTodayEndTimestamp(){let e=new Date;return new Date(e.getFullYear(),e.getMonth(),e.getDate(),23,59,59,999).getTime()}_setItem(e,r,t){let o=void 0!==t?t:this.config.expire;"today"===o&&(o=this.getTodayEndTimestamp()-Date.now());let _={value:r,expire:o,timestamp:Date.now()};try{tt.setStorageSync(e,JSON.stringify(_))}catch(e){console.error("Storage setItem error:",e)}}_getItem(e){try{let r=tt.getStorageSync(e);if(!r)return null;let t=JSON.parse(r);if(t.expire&&Date.now()-t.timestamp>t.expire)return this.removeItem(e),null;return t.value}catch(e){return console.error("Storage getItem error:",e),null}}setItem(e,r,t){let o=this.config.prefix+e;return this._setItem(o,r,t)}getItem(e){let r=this.config.prefix+e;return this._getItem(r)}getUserItem(e){let r=this.config.userId??"null";if("null"===r)return this.logger.error("userId is required"),null;let t=`${this.config.prefix}_${r}_${e}`;return this._getItem(t)}setUserItem(e,r,t){let o=this.config.userId??"null";if("null"===o)return void this.logger.error("userId is required");let _=`${this.config.prefix}_${o}_${e}`;return this._setItem(_,r,t)}removeItem(e){try{tt.removeStorageSync(e)}catch(e){console.error("Storage removeItem error:",e)}}clear(){try{tt.clearStorageSync()}catch(e){console.error("Storage clear error:",e)}}keys(){try{let e=[];return(tt.getStorageInfoSync().keys??[]).forEach(r=>{if(r.startsWith(this.config.prefix)){let t=JSON.parse(tt.getStorageSync(r));(!t.expire||Date.now()-t.timestamp<=t.expire)&&e.push(r.replace(this.config.prefix,""))}}),e}catch(e){return console.error("Storage keys error:",e),[]}}static new(e){return new Storage(e)}}const src_Storage=Storage;for(var __rspack_i in exports.Storage=__webpack_exports__.Storage,__webpack_exports__)-1===["Storage"].indexOf(__rspack_i)&&(exports[__rspack_i]=__webpack_exports__[__rspack_i]);Object.defineProperty(exports,"__esModule",{value:!0});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { default as Storage } from "./Storage.js";

package/dist/index.js

@@ -0,0 +1 @@
+import{Logger as e}from"@ad-execute-manager/logger";class t{constructor(t={}){this.config={prefix:"storage_",expire:null,...t},this.logger=new e({prefix:"Storage"})}getTodayEndTimestamp(){let e=new Date;return new Date(e.getFullYear(),e.getMonth(),e.getDate(),23,59,59,999).getTime()}_setItem(e,t,r){let o=void 0!==r?r:this.config.expire;"today"===o&&(o=this.getTodayEndTimestamp()-Date.now());let i={value:t,expire:o,timestamp:Date.now()};try{tt.setStorageSync(e,JSON.stringify(i))}catch(e){console.error("Storage setItem error:",e)}}_getItem(e){try{let t=tt.getStorageSync(e);if(!t)return null;let r=JSON.parse(t);if(r.expire&&Date.now()-r.timestamp>r.expire)return this.removeItem(e),null;return r.value}catch(e){return console.error("Storage getItem error:",e),null}}setItem(e,t,r){let o=this.config.prefix+e;return this._setItem(o,t,r)}getItem(e){let t=this.config.prefix+e;return this._getItem(t)}getUserItem(e){let t=this.config.userId??"null";if("null"===t)return this.logger.error("userId is required"),null;let r=`${this.config.prefix}_${t}_${e}`;return this._getItem(r)}setUserItem(e,t,r){let o=this.config.userId??"null";if("null"===o)return void this.logger.error("userId is required");let i=`${this.config.prefix}_${o}_${e}`;return this._setItem(i,t,r)}removeItem(e){try{tt.removeStorageSync(e)}catch(e){console.error("Storage removeItem error:",e)}}clear(){try{tt.clearStorageSync()}catch(e){console.error("Storage clear error:",e)}}keys(){try{let e=[];return(tt.getStorageInfoSync().keys??[]).forEach(t=>{if(t.startsWith(this.config.prefix)){let r=JSON.parse(tt.getStorageSync(t));(!r.expire||Date.now()-r.timestamp<=r.expire)&&e.push(t.replace(this.config.prefix,""))}}),e}catch(e){return console.error("Storage keys error:",e),[]}}static new(e){return new t(e)}}let r=t;export{r as Storage};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@ad-execute-manager/storage",
+  "version": "2.0.1",
+  "description": "A flexible storage utility for JavaScript applications with expiration support, user-specific storage, and customizable prefixes.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "author": {
+    "name": "singcl",
+    "email": "iambabyer@gmail.com",
+    "url": "https://github.com/singcl"
+  },
+  "license": "MIT",
+  "homepage": "https://npmjs.com/package/@ad-execute-manager/storage",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/singcl/ad-execute-manager.git",
+    "directory": "packages/storage"
+  },
+  "bugs": {
+    "url": "https://github.com/singcl/ad-execute-manager/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "keywords": [
+    "storage",
+    "localstorage",
+    "expiration",
+    "user-storage",
+    "javascript",
+    "nodejs",
+    "typescript",
+    "prefix",
+    "session",
+    "cache"
+  ],
+  "scripts": {
+    "build": "rslib build && tsc",
+    "dev": "rslib build --watch",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "rstest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@ad-execute-manager/logger": "^2.0.1"
+  },
+  "devDependencies": {
+    "@babel/eslint-parser": "^7.28.5",
+    "@babel/preset-env": "^7.28.5",
+    "@eslint/js": "^9.39.1",
+    "@rslib/core": "^0.18.5",
+    "@rstest/core": "^0.7.2",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "globals": "^16.5.0",
+    "prettier": "^3.7.3",
+    "typescript": "^5.9.3"
+  }
+}