yuniqkv

YuniqKV

YuniqKV is a versatile key-value storage library that supports both IndexedDB and LocalStorage with encryption and soft delete capabilities. It is designed to be used in browser environments.

Features

• Multiple Storage Backends: Supports IndexedDB and LocalStorage.
• Encryption: Secure your data with AES encryption.
• Soft Delete: Mark items as deleted without permanently removing them.
• TTL and Expiry: Set time-to-live (TTL) for items.
• Querying: Advanced querying capabilities with filters, sorting, and pagination.
• Batch Operations: Perform bulk operations efficiently.
• Transactions: Support for transactional operations.
• Event-Driven: Emits events for various operations.

Installation

Install the package via npm:

npm install yuniqkv

Usage

Initialization

import { YuniqKV } from 'yuniqkv';

const kv = new YuniqKV({
  storageType: 'indexeddb', // or 'localstorage'
  databaseName: 'myDatabase',
  encryption: true,
  privateKey: 'my-secret-key',
  autoCleanupInterval: 60000, // 1 minute
  version: 1,
});

await kv.init();

Basic Operations

Set Item

await kv.set('myKey', { name: 'John Doe' });

Get Item

const value = await kv.get<{ name: string }>('myKey');
console.log(value); // { name: 'John Doe' }

Delete Item

await kv.delete('myKey');

Advanced Operations

Set Item with Options

await kv.set('myKey', { name: 'John Doe' }, { ttlSeconds: 3600, tags: ['user'] });

Query Items

const result = await kv.query<{ name: string }>({
  tags: ['user'],
  orderBy: 'createdAt',
  order: 'desc',
  limit: 10,
});

console.log(result.items);

Batch Operations

await kv.setMany([
  { key: 'key1', value: { name: 'Alice' } },
  { key: 'key2', value: { name: 'Bob' } },
]);

const values = await kv.getMany(['key1', 'key2']);
console.log(values);

Transactions

await kv.transaction(async (txn) => {
  await txn.set('key1', { name: 'Alice' });
  await txn.set('key2', { name: 'Bob' });
  const value = await txn.get<{ name: string }>('key1');
  console.log(value);
});

Events

kv.on('set', (key, value, id) => {
  console.log(`Item set: ${key} = ${value}, id = ${id}`);
});

kv.on('delete', (key, id) => {
  console.log(`Item deleted: ${key}, id = ${id}`);
});

Backup and Restore

Backup

const backup = await kv.backup();
console.log(backup);

Restore

await kv.restore(backup);

Optimization

await kv.optimize();

API Reference

YuniqKV

Methods

• init(): Promise<void>
• dispose(): void
• set<T>(key: string, value: T, options?: SetOptions): Promise<number>
• get<T>(key: string, options?: GetOptions): Promise<T | undefined>
• delete(key: string, options?: DeleteOptions): Promise<boolean>
• setMany<T>(items: Array<{ key: string; value: T }>, options?: SetOptions): Promise<number[]>
• getMany<T>(keys: string[], options?: GetOptions): Promise<(T | undefined)[]>
• deleteMany(keys: string[], options?: DeleteOptions): Promise<boolean[]>
• query<T>(options: QueryOptions): Promise<QueryResult<T>>
• queryKeys(options: QueryOptions): Promise<string[]>
• queryCount(options: QueryOptions): Promise<number>
• clear(): Promise<void>
• clearItems(): Promise<void>
• getKeys(options?: QueryOptions): Promise<string[]>
• hasItem(key: string): Promise<boolean>
• bulk<T>(operations: Array<{ type: 'set' | 'delete'; key: string; value?: T; options?: SetOptions | DeleteOptions }>): Promise<Array<{ success: boolean; id?: number }>>
• transaction<T>(callback: (transaction: { get: <U>(key: string) => Promise<U | undefined>; set: <U>(key: string, value: U, options?: SetOptions) => Promise<number>; delete: (key: string, options?: DeleteOptions) => Promise<boolean> }) => Promise<T>): Promise<T>
• batchGet<T>(options: { prefix?: string; suffix?: string; tags?: string[]; batchSize?: number; callback: (batch: Array<{ key: string; value: T }>) => Promise<void> }): Promise<void>
• watch<T>(key: string, callback: (value: T | undefined) => void): () => void
• watchPattern<T>(pattern: { prefix?: string; suffix?: string; tags?: string[] }, callback: (changes: Array<{ key: string; value: T | undefined; type: 'set' | 'delete' }>) => void): () => void
• getFirstItem<T>(options?: { ascending?: boolean }): Promise<{ key: string; value: T } | undefined>
• isKeyFirst(key: string, ascending?: boolean): Promise<boolean>
• getExpiredItems(): Promise<Array<{ key: string; expiry: number }>>
• optimize(): Promise<void>
• getStats(): Promise<StorageStats>
• backup(): Promise<string>
• restore(backup: string): Promise<void>
• migrate(version: number, migrations: Array<{ version: number; migrate: (data: Map<string, StoreItem>) => Promise<Map<string, StoreItem>> }>): Promise<void>

Types

SetOptions

interface SetOptions {
  ttlSeconds?: number;
  prefix?: string;
  suffix?: string;
  expiry?: Date;
  tags?: string[];
  upsert?: boolean;
  returnOld?: boolean;
}

GetOptions

interface GetOptions {
  defaultValue?: any;
  throwIfNotFound?: boolean;
}

DeleteOptions

interface DeleteOptions {
  force?: boolean;
  soft?: boolean;
}

QueryOptions

interface QueryOptions {
  prefix?: string;
  suffix?: string;
  tags?: string[];
  expiryState?: 'valid' | 'expired' | 'all';
  limit?: number;
  offset?: number;
  orderBy?: 'id' | 'key' | 'createdAt' | 'updatedAt' | 'expiry' | 'deletedAt';
  order?: 'asc' | 'desc';
  includeSoftDeleted?: boolean;
}

QueryResult

interface QueryResult<T = any> {
  items: T[];
  total: number;
  hasMore: boolean;
}

StorageStats

interface StorageStats {
  totalItems: number;
  expiredItems: number;
  softDeletedItems: number;
  averageKeySize: number;
  averageValueSize: number;
  totalSize: number;
  storageUsage: number;
  storageQuota: number;
  compressionRatio: number;
  details: {
    itemsByPrefix: Record<string, number>;
    itemsBySuffix: Record<string, number>;
    itemsByTag: Record<string, number>;
    sizeByPrefix: Record<string, number>;
    sizeBySuffix: Record<string, number>;
    sizeByTag: Record<string, number>;
    ageStats: {
      newest: number;
      oldest: number;
      averageAge: number;
    };
    expiryStats: {
      soonestExpiry: number | null;
      latestExpiry: number | null;
      averageTimeToExpiry: number | null;
    };
    performanceStats: {
      averageReadTime: number;
      averageWriteTime: number;
      estimatedOperationsPerSecond: number;
    };
  };
}

License

MIT License. See LICENSE for more details.