feature/local-storage (#17)

* feat: add `LocalStorage` Class

* tests: add `LocalStorage` unit tests

Author: alessiofrittoli

__tests__/storage/index.test.ts

@@ -1,3 +1,6 @@
+/**
+ * @jest-environment jsdom
+ */
 import { Storage } from '@/storage/Storage'
 
 describe( 'Storage', () => {

__tests__/storage/local.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @jest-environment jsdom
+ */
+import { LocalStorage } from '@/storage/LocalStorage'
+
+describe( 'LocalStorage', () => {
+
+	beforeEach( () => {
+		localStorage.clear()
+	} )
+
+
+	describe( 'LocalStorage.set()', () => {
+
+		it( 'sets an item', () => {
+			LocalStorage.set( 'key', 'value' )
+			expect( LocalStorage.get( 'key' ) ).toBe( 'value' )
+		} )
+
+	} )
+	
+	
+	describe( 'LocalStorage.get()', () => {
+
+		it( 'gets an item', () => {
+			LocalStorage.set( 'key', 'value' )
+			expect( LocalStorage.get( 'key' ) ).toBe( 'value' )
+		} )
+
+		it( 'returns `undefined` for non-existing key', () => {
+			expect( LocalStorage.get( 'nonExistingKey' ) ).toBeUndefined()
+		} )
+
+	} )
+
+
+	describe( 'LocalStorage.delete()', () => {
+
+		it( 'removes an item', () => {
+			LocalStorage.set( 'key', 'value' )
+			LocalStorage.delete( 'key' )
+			expect( LocalStorage.get( 'key' ) ).toBeUndefined()
+		} )
+
+	} )
+
+
+	describe( 'LocalStorage.clear()', () => {
+
+		it( 'clears all items', () => {
+			LocalStorage.set( 'key1', 'value1' )
+			LocalStorage.set( 'key2', 'value2' )
+			LocalStorage.clear()
+			expect( LocalStorage.get( 'key1' ) ).toBeUndefined()
+			expect( LocalStorage.get( 'key2' ) ).toBeUndefined()
+		} )
+
+	} )
+
+	describe( 'LocalStorage.key()', () => {
+
+		it( 'returns the correct key for a given index', () => {
+			LocalStorage.set( 'key1', 'value1' )
+			LocalStorage.set( 'key2', 'value2' )
+			expect( LocalStorage.key( 0 ) ).toBe( 'key1' )
+			expect( LocalStorage.key( 1 ) ).toBe( 'key2' )
+		} )
+
+	} )
+
+	describe( 'LocalStorage.getLength()', () => {
+
+		it( 'returns the correct length', () => {
+			expect( LocalStorage.getLength() ).toBe( 0 )
+			LocalStorage.set( 'key1', 'value1' )
+			expect( LocalStorage.getLength() ).toBe( 1 )
+			LocalStorage.set( 'key2', 'value2' )
+			expect( LocalStorage.getLength() ).toBe( 2 )
+			LocalStorage.clear()
+			expect( LocalStorage.getLength() ).toBe( 0 )
+		} )
+
+	} )
+
+} )

package.json

@@ -92,7 +92,8 @@
 		"test:validation": "pnpm test:watch validation.test.ts",
 		"test:storage": "pnpm test:watch storage/index.test.ts",
 		"test:cookie": "pnpm test:watch storage/cookie.test.ts",
-		"test:cookie:jsdom": "pnpm test:watch storage/cookie-jsdom.test.ts"
+		"test:cookie:jsdom": "pnpm test:watch storage/cookie-jsdom.test.ts",
+		"test:local": "pnpm test:watch storage/local.test.ts"
 	},
 	"devDependencies": {
 		"@alessiofrittoli/node-scripts": "^2.2.1",

src/storage/LocalStorage.ts

@@ -0,0 +1,89 @@
+import { Storage } from './Storage'
+
+
+/**
+ * A browser-compatible implementation of [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage). Data is stored
+ * unencrypted in the file specified by the `--localstorage-file` CLI flag.
+ * The maximum amount of data that can be stored is 10 MB.
+ * Any modification of this data outside of the Web Storage API is not supported.
+ * Enable this API with the `--experimental-webstorage` CLI flag.
+ * `localStorage` data is not stored per user or per request when used in the context
+ * of a server, it is shared across all users and requests.
+ */
+export class LocalStorage
+{
+	/**
+	 * Removes all key/value pairs, if there are any.
+	 *
+	 * Dispatches a storage event on Window objects holding an equivalent Storage object.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/clear)
+	 */
+	static clear()
+	{
+		return localStorage.clear()
+	}
+
+
+	/**
+	 * Returns the current value associated with the given key, or undefined if the given key does not exist.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/getItem)
+	 */
+	static get<T>( name: string )
+	{
+		return (
+			Storage.parseValue<T>( localStorage.getItem( name ) || undefined )
+		)
+	}
+
+
+	/**
+	 * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+	 *
+	 * Throws a "QuotaExceededError" DOMException exception if the new value couldn't be set. (Setting could fail if, e.g., the user has disabled storage for the site, or if the quota has been exceeded.)
+	 *
+	 * Dispatches a storage event on Window objects holding an equivalent Storage object.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/setItem)
+	 */
+	static set<T>( name: string, value: T )
+	{
+		return localStorage.setItem( name, Storage.stringifyValue( value ) )
+	}
+	
+
+	/**
+	 * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
+	 *
+	 * Dispatches a storage event on Window objects holding an equivalent Storage object.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/removeItem)
+	 */
+	static delete( name: string )
+	{
+		return localStorage.removeItem( name )
+	}
+	
+	
+	/**
+	 * Returns the name of the nth key, or null if n is greater than or equal to the number of key/value pairs.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/key)
+	 */
+	static key( index: number )
+	{
+		return localStorage.key( index )
+	}
+
+	
+	/**
+	 * Returns the number of key/value pairs.
+	 *
+	 * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Storage/length)
+	 */
+	static getLength()
+	{
+		return localStorage.length
+	}
+}

src/storage/Storage.ts

@@ -5,6 +5,7 @@ import { isPromise, isString } from '@/types'
 import { isEmpty } from '@/validation'
 
 import { Cookie } from './Cookie'
+import { LocalStorage } from './LocalStorage'
 
 
 /**
@@ -78,9 +79,14 @@ export class Storage
 		}
 	}
 
-
 	/**
 	 * Reference to the {@link Cookie} utility.
 	 */
 	static cookie = Cookie
+
+
+	/**
+	 * Reference to the {@link LocalStorage} storage utility.
+	 */
+	static local = LocalStorage
 }