@kzkymur/storage

This is a super lightweight library to handle WebStorage more easily.

What you can do

• To access flexibly to WebStorage with JSON structure and Layered-String-Key
• To register event listener with Layered-String-Key

What is Layered-String-Key?

• Layered-String-Key is a very simple way to access object or primitive in JSON.

• Layered-String-Key is composed with Separotor and KeyValueSeparotor

• For example, you have a JSON object like this

1{
2  "users": [
3    {
4      "id": 1,
5      "name": "kzkymur",
6      "job": "student"
7    },
8    {
9      "id": 2,
10      "name": "ringring",
11      "job": "student"
12    }
13  ]
14}

and '-' Separotor, ':' KeyValueSeparotor.

• if you wanna get a user's name id = 1, Layered-String-Key will be users-id:1-name

Install

1npm i @kzkymur/storage

How to use

Assume that your localStorage is registered with the previous example JSON.

Vanilla Js

1import StorageJs from "@kzkymur/storage";
2
3const storage = new StorageJs({
4  storage: winodw.localStorage || window.sessionStorage, // or your original instance implement localStorage interface
5  name: "test",
6
7  // These are optional. A comlex value will be better if you set.
8  separotor: "-",
9  keyValueSeparator: ":",
10});
11
12// get method
13const [name] = storage.get("users", "id:1", "name");
14const [nameByJoinedStringKey] = storage.get("users-id:1-name");
15const [nameByIndex] = storage.get("users-0-name");
16console.log(name); // "kzkymur".
17console.log(name === nameByJoinedStringKey); // true.
18console.log(name === nameByIndex); // true.
19console.log(storage.get("users-job:student-name")); // ['kzkymur', 'ringring']
20
21// set method
22storage.set("kzkymur2", "users", "0", "name");
23console.log(storage.get("users", "id:1", "name")[0]); // "kzkymur2"
24storage.set("teacher", "users-job:student-job");
25console.log(storage.get("users-job:teacher-name")); // ['kzkymur', 'ringring']
26
27// push method
28storage.push({ id: 3, name: "ta1ch" }, "users");
29console.log(storage.get("users", "id:3", "name")); // ['ta1ch']
30
31// remove method
32storage.remove("users", "0");
33console.log(storage.get("users", "id:1")); // []
34
35// eventListener
36const handler = console.log;
37storage.addEventListener("users-id:1", handler, {
38  parent: false,
39  children: true,
40});
41storage.set("kzkymur2", storage.concatLayeredKeys("users", "id:1", "name")); // console.log({ id: 1, name: "kzkymur2" }); is fired because children flag true
42storage.removeEventListener(handler);
43
44const unregister = storage.registerEventListener("users-id:2-name", handler, {
45  parent: true,
46  children: false,
47});
48storage.set(
49  { id: 2, name: "ringring2" },
50  storage.concatLayeredKeys("users", "id:2")
51); // console.log("ringring2"); is fired because parent flag true
52unregister();

more information is written in test/index.test.ts so plz refer to it.

React Custom Hooks

1import StorageJs from "@kzkymur/storage";
2import { useStorageUnique } from "@kzkymur/storage/react";
3// or
4// import { useStorageUnique } from "@kzkymur/storage/dist/react";
5
6// We recommend to be outside of Component
7const storage = new StorageJs({
8  storage: winodw.localStorage || window.sessionStorage,
9  name: "test",
10});
11
12const MyComponent = (props) => {
13  const [user, setUser] = useStorageUnique(storage, `users-id:${props.id}`);
14  const updateUserName = (name: string) => {
15    setUser({ ...user, name });
16  };
17
18  return (
19    <div>
20      <p> id : ${user.id} </p>
21      <p> name: ${user.name} </p>
22    </div>
23  );
24};

Future work

• Strong Type Gaured
• Error Handle
• More Test cases and Examples
• More React custom hooks
• Optimization for Event Listener
• Function to Get and Set root JSON

I'll be happy if you contribute this!

Author

kzkymur

LICENSE

MIT