storage: add localforage support (#668)

.changeset/cold-mangos-film.md

@@ -0,0 +1,5 @@
+---
+"@solid-primitives/storage": major
+---
+
+storage: remove deprecated primitives, simplify types, add makeObjectStorage

packages/event-props/package.json

@@ -38,8 +38,6 @@
     }
   },
   "scripts": {
-    "prebuild": "npm run clean",
-    "clean": "rimraf dist/",
     "dev": "tsx ../../scripts/dev.ts",
     "build": "tsx ../../scripts/build.ts",
     "typecheck": "tsc --noEmit src/* test/*;",

packages/fullscreen/package.json

@@ -38,8 +38,6 @@
     }
   },
   "scripts": {
-    "prebuild": "npm run clean",
-    "clean": "rimraf dist/",
     "dev": "tsx ../../scripts/dev.ts",
     "build": "tsx ../../scripts/build.ts",
     "vitest": "vitest -c ../../configs/vitest.config.ts",

packages/storage/README.md

@@ -29,7 +29,7 @@ const [signal, setSignal] = makePersisted(createSignal("initial"), {storage: ses
 const [store, setStore] = makePersisted(createStore({test: true}), {name: "testing"});
 type PersistedOptions<Type, StorageOptions> = {
   // localStorage is default
-  storage?: Storage | StorageWithOptions | AsyncStorage | AsyncStorageWithOptions,
+  storage?: Storage | StorageWithOptions | AsyncStorage | AsyncStorageWithOptions | LocalForage,
   // only required for storage APIs with options
   storageOptions?: StorageOptions,
   // key in the storage API
@@ -99,6 +99,22 @@ const [state, setState] = makePersisted(createSignal(), {
 });
 ```
 
+#### LocalForage
+
+LocalForage uses indexedDB or WebSQL if available to greatly increase the size of what can be stored. Just drop it in as a storage (only supported in the client):
+
+```ts
+import { isServer } from "solid-js/web";
+import { makePersisted } from "@solid-primtives/storage";
+import localforage from "localforage";
+
+const [state, setState] = makePersisted(createSignal(), {
+  storage: !isServer ? localforage : undefined
+});
+```
+
+Keep in mind that it will only run on the client, so unless you have 
+
 #### TauriStorage
 
 [Tauri](https://tauri.app) is a lightweight run-time for desktop (and soon also mobile) applications utilizing web front-end frameworks. While it supports `localStorage` and `sessionStorage`, it also has its own store plugin with the benefit of improved stability. To use it, install the required modules both on the side of JavaScript and Rust after setting up the project with the help of their command-line interface:
@@ -143,11 +159,15 @@ import { tauriStorage } from "@solid-primitives/storage/tauri";
 const storage = window.__TAURI_INTERNALS__ ? tauriStorage() : localStorage;
 ```
 
-#### IndexedDB, WebSQL
+#### Object storage
+
+This package also provides a way to create a storage API wrapper for an object called `makeObjectStorage(object)`. This is especially useful as a server fallback if you want to store the data in your user session or database object:
 
-There is also [`localForage`](https://localforage.github.io/localForage/), which uses `IndexedDB`, `WebSQL`
-or `localStorage` to provide an asynchronous Storage API that can ideally store much more than the few Megabytes that
-are available in most browsers.
+```ts
+const [state, setState] = createPersisted(createSignal(), {
+  storage: globalThis.localStorage ?? makeObjectStorage(session.userState)
+});
+```
 
 #### Multiplexed storages
 
@@ -250,179 +270,6 @@ const customStorage = addWithOptionsMethod(storage_supporting_options);
 const boundCustomStorage = customStorage.withOptions(myOptions);
 ```
 
----
-
-### Deprecated primitives:
-
-The previous implementation proved to be confusing and cumbersome for most people who just wanted to persist their
-signals and stores, so they are now deprecated and will soon be removed from this package.
-
-`createStorage` is meant to wrap any `localStorage`-like API to be as accessible as
-a [Solid Store](https://www.solidjs.com/docs/latest/api#createstore). The main differences are
-
-- that this store is persisted in whatever API is used,
-- that you can only use the topmost layer of the object and
-- that you have additional methods in an object as the third part of the returned tuple:
-
-```ts
-const [store, setStore, {
-  remove: (key: string) => void;
-  clear: () => void;
-  toJSON: () => ({[key: string]: string });
-}]
-= createStorage({api: sessionStorage, prefix: 'my-app'});
-
-setStore('key', 'value');
-store.key; // 'value'
-```
-
-The props object support the following parameters:
-
-`api`
-: An array of or a single `localStorage`-like storage API; default will be `localStorage` if it exists; an empty array
-or no API will not throw an error, but only ever get `null` and not actually persist anything
-
-`prefix`
-: A string that will be prefixed every key inside the API on set and get operations
-
-`serializer / deserializer`
-: A set of function to filter the input and output; the `serializer` takes an arbitrary object and returns a string,
-e.g. `JSON.stringify`, whereas the `deserializer` takes a string and returns the requested object again.
-
-`options`
-: For APIs that support options as third argument in the `getItem` and `setItem` method (see helper
-type `StorageWithOptions<O>`), you can add options they will receive on every operation.
-
----
-
-There are a number of convenience Methods primed with common storage APIs and our own version to use cookies:
-
-```ts
-createLocalStorage();
-createSessionStorage();
-createCookieStorage();
-```
-
----
-
-#### Asynchronous storage APIs
-
-In case you have APIs that persist data on the server or via `ServiceWorker` in
-a [`CookieStore`](https://wicg.github.io/cookie-store/#CookieStore), you can wrap them into an asynchronous
-storage (`AsyncStorage` or `AsyncStorageWithOptions` API) and use them with `createAsyncStorage`:
-
-```ts
-type CookieStoreOptions = {
-  path: string;
-  domain: string;
-  expires: DOMTimeStamp;
-  sameSite: "None" | "Lax" | "Strict"
-}
-const CookieStoreAPI: AsyncStorageWithOptions<CookieStoreOptions> = {
-  getItem: (key) => cookieStore.get(key),
-  getAll: () => cookieStore.getAll(),
-  setItem: (key: string, value: string, options: CookieStoreOptions = {}) => cookieStore.set({
-    ...options, name, value
-  }),
-  removeItem: (key) => cookieStore.delete(key),
-  clear: async () => {
-    const all = await cookieStore.getAll();
-    for (const key of all) {
-      await cookieStore.delete(key);
-    }
-  },
-  key: async (index: number) => {
-    const all = await cookieStore.getAll();
-    return Object.keys(all)[index];
-  }
-}
-)
-;
-
-const [cookies, setCookie, {
-  remove: (key: string) => void;
-  clear: () => void;
-  toJSON: () => ({[key: string]: string
-})
-;
-}]
-= createAsyncStorage({api: CookieStoreAPI, prefix: 'my-app', sync: false});
-
-await setStore('key', 'value');
-await store.key; // 'value'
-```
-
-It works exactly like a synchronous storage, with the exception that you have to `await` every single return value. Once
-the `CookieStore` API becomes more prevalent, we will integrate support out of the box.
-
-If you cannot use `document.cookie`, you can overwrite the entry point using the following tuple:
-
-```ts
-import {cookieStorage} from '@solid-primitives/storage';
-
-cookieStorage._cookies = [object
-:
-{
-  [name
-:
-  string
-]:
-  CookieProxy
-}
-,
-name: string
-]
-;
-```
-
-If you need to abstract an API yourself, you can use a getter and a setter:
-
-```ts
-const CookieAbstraction = {
-  get cookie() {
-    return myCookieJar.toString()
-  }
-  set cookie(cookie) {
-    const data = {};
-    cookie.replace(/([^=]+)=(?:([^;]+);?)/g, (_, key, value) => {
-      data[key] = value
-    });
-    myCookieJar.set(data);
-  }
-}
-cookieStorage._cookies = [CookieAbstraction, 'cookie'];
-```
-
----
-
-`createStorageSignal` is meant for those cases when you only need to conveniently access a single value instead of full
-access to the storage API:
-
-```ts
-const [value, setValue] = createStorageSignal("value", { api: cookieStorage });
-
-setValue("value");
-value(); // 'value'
-```
-
-As a convenient additional method, you can also use `createCookieStorageSignal(key, initialValue, options)`.
-
----
-
-### Options
-
-The properties of your `createStorage`/`createAsyncStorage`/`createStorageSignal` props are:
-
-- `api`: the (synchronous or
-  asynchronous) [Storage-like API](https://developer.mozilla.org/de/docs/Web/API/Web_Storage_API), default
-  is `localStorage`
-- `deserializer` (optional): a `deserializer` or parser for the stored data
-- `serializer` (optional): a `serializer` or string converter for the stored data
-- `options` (optional): default options for the set-call of Storage-like API, if supported
-- `prefix` (optional): a prefix for the Storage keys
-- `sync` (optional): if set to
-  false, [event synchronization](https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent) is disabled
-
 ## Demo
 
 [Live Demo](https://primitives.solidjs.community/playground/storage) - [Sources](https://github.com/solidjs-community/solid-primitives/tree/main/packages/storage/dev)

packages/storage/package.json

@@ -25,7 +25,8 @@
       "wsSync",
       "multiplexSync",
       "addClearMethod",
-      "addWithOptionsMethod"
+      "addWithOptionsMethod",
+      "makeObjectStorage"
     ],
     "category": "Browser APIs"
   },
@@ -86,8 +87,8 @@
     "@solid-primitives/utils": "workspace:^"
   },
   "peerDependencies": {
-    "solid-js": "^1.6.12",
-    "@tauri-apps/plugin-store": "*"
+    "@tauri-apps/plugin-store": "*",
+    "solid-js": "^1.6.12"
   },
   "peerDependenciesMeta": {
     "solid-start": {

packages/storage/src/cookies.ts

@@ -1,12 +1,11 @@
 import { getRequestEvent, isServer, type RequestEvent } from "solid-js/web";
-import { StorageProps, StorageSignalProps, StorageWithOptions } from "./types.js";
+import { SyncStorageWithOptions } from "./persisted.js";
 import { addClearMethod, addWithOptionsMethod } from "./tools.js";
-import { createStorage, createStorageSignal } from "./storage.js";
 
 export type CookieOptions = CookieProperties & {
   getRequestHeaders?: () => Headers;
   getResponseHeaders?: () => Headers;
-};
+} | undefined;
 
 type CookiePropertyTypes = {
   domain?: string;
@@ -78,7 +77,7 @@ const getResponseHeaders = isServer
  * ```
  * Also, you can use its _read and _write properties to change reading and writing
  */
-export const cookieStorage: StorageWithOptions<CookieOptions> = addWithOptionsMethod(
+export const cookieStorage: SyncStorageWithOptions<CookieOptions> = addWithOptionsMethod(
   addClearMethod({
     _read: isServer
       ? (options?: CookieOptions) => {
@@ -147,25 +146,3 @@ export const cookieStorage: StorageWithOptions<CookieOptions> = addWithOptionsMe
     },
   }),
 );
-
-/**
- * creates a reactive store but bound to document.cookie
- * @deprecated in favor of makePersisted
- */
-export const createCookieStorage = <T, O = CookieOptions, A = StorageWithOptions<CookieOptions>>(
-  props?: Omit<StorageProps<T, A, O>, "api">,
-) => createStorage<O, T>({ ...props, api: cookieStorage } as any);
-
-/**
- * creates a reactive signal, but bound to document.cookie
- * @deprecated in favor of makePersisted
- */
-export const createCookieStorageSignal = <
-  T,
-  O = CookieOptions,
-  A = StorageWithOptions<CookieOptions>,
->(
-  key: string,
-  initialValue?: T,
-  props?: Omit<StorageSignalProps<T, A, O>, "api">,
-) => createStorageSignal<T, O>(key, initialValue, { ...props, api: cookieStorage } as any);

packages/storage/src/index.ts

@@ -1,29 +1,10 @@
-export type {
-  StorageWithOptions,
-  StorageDeserializer,
-  StorageSerializer,
-  StringStorageProps,
-  AnyStorageProps,
-  StorageProps,
-  StorageObject,
-  StorageSetter,
-  AsyncStorage,
-  AsyncStorageWithOptions,
-  AsyncStorageObject,
-  AsyncStorageSetter,
-  StorageSignalProps,
-} from "./types.js";
-
-import {
-  createStorage,
-  createAsyncStorage,
-  createStorageSignal,
-  createLocalStorage,
-  createSessionStorage,
-} from "./storage.js";
-import { type CookieOptions, cookieStorage, createCookieStorage } from "./cookies.js";
-import { addClearMethod, addWithOptionsMethod, multiplexStorage } from "./tools.js";
+import { type CookieOptions, cookieStorage } from "./cookies.js";
+import { addClearMethod, addWithOptionsMethod, multiplexStorage, makeObjectStorage } from "./tools.js";
 import {
+  type SyncStorage,
+  type SyncStorageWithOptions,
+  type AsyncStorage,
+  type AsyncStorageWithOptions,
   type PersistenceOptions,
   type PersistenceSyncAPI,
   type PersistenceSyncData,
@@ -35,17 +16,16 @@ import {
   wsSync,
 } from "./persisted.js";
 export {
-  createStorage,
-  createAsyncStorage,
-  createStorageSignal,
-  createLocalStorage,
-  createCookieStorage,
-  createSessionStorage,
   type CookieOptions,
   cookieStorage,
   addClearMethod,
   addWithOptionsMethod,
   multiplexStorage,
+  makeObjectStorage,
+  type SyncStorage,
+  type SyncStorageWithOptions,
+  type AsyncStorage,
+  type AsyncStorageWithOptions,
   type PersistenceOptions,
   type PersistenceSyncCallback,
   type PersistenceSyncData,