https://github.com/unadlib/origin-storage
A same-origin storage(IndexedDB/WebSQL/localStorage) for cross-domain access
https://github.com/unadlib/origin-storage
cross-database indexeddb localforage localstorage websql
Last synced: about 1 year ago
JSON representation
A same-origin storage(IndexedDB/WebSQL/localStorage) for cross-domain access
- Host: GitHub
- URL: https://github.com/unadlib/origin-storage
- Owner: unadlib
- License: mit
- Created: 2020-07-22T17:43:10.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-08T15:19:47.000Z (about 1 year ago)
- Last Synced: 2025-04-08T16:28:07.612Z (about 1 year ago)
- Topics: cross-database, indexeddb, localforage, localstorage, websql
- Language: TypeScript
- Homepage:
- Size: 778 KB
- Stars: 22
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# origin-storage
[](http://badge.fury.io/js/origin-storage)
A same-origin storage for cross-domain access, it is based on localForage and supports IndexedDB, WebSQL and localStorage.
> `origin-storage` uses localStorage in browsers with no IndexedDB or WebSQL support. And Safari is not supported.
## Table of Contents
- [Motivation](#motivation)
- [Installation](#installation)
- [Usage and Example](#usage-and-example)
- [API](#api)
- [OriginStorage](#originstorage)
- [OriginStorageClient](#originstorageclient)
## Motivation
When different Website domains need a same-origin storage container, we have to use iframe's same-origin policy Web local storage solution. `localForage` is an excellent storage library, it supports IndexedDB, WebSQL and localStorage, but it can't solve this problem directly.
That's why we have this library for same-origin storage based on `localForage`.
## Installation
```sh
yarn add origin-storage
```
## Usage and Example
- Use `OriginStorage` on `http://localhost:9000/storage.js`:
```ts
import { OriginStorage } from 'origin-storage';
const originStorage = new OriginStorage();
```
> If you need to set up a more secure origin control, you can set `targetOrigin` like this.
```ts
const originStorage = new OriginStorage({
targetOrigin: 'http://example.com',
});
```
- Create and host a Web page(`http://localhost:9000/storage.html`) containing JavaScript file `storage.js`.
- Use `OriginStorageClient` on a cross-domain page:
```ts
import { OriginStorageClient } from 'origin-storage';
const originStorageClient = new OriginStorageClient({
uri: 'http://localhost:9000/storage.html',
});
```
## API
### `OriginStorage`
- `new OriginStorage(options)`
```ts
interface OriginStorageOptions extends IFrameTransportInternalOptions {
/**
* Enable read access to OriginStorage.
*/
read?: boolean;
/**
* Enable write access to OriginStorage.
*/
write?: boolean;
/**
* Enable broadcast data changes on OriginStorage.
*/
broadcastChanges?: boolean;
/**
* Specify broadcastChannel name.
*/
broadcastChannelName?: string;
}
```
### `OriginStorageClient`
- `new OriginStorageClient(options)`
```ts
interface OriginStorageClientOptions extends IFrameMainTransportOptions {
/**
* Specify the uri of an OriginStorage container.
*/
uri: string;
/**
* Set storage options for localforage.
*/
storageOptions?: LocalForageOptions;
}
```
- `OriginStorageClient` instance methods.
```ts
interface IOriginStorageClient {
/**
* The callback will be called when the iframe is connected.
*/
onConnect(callback: () => void): void;
/**
* The callback will be called when the storage is changed.
*/
onChange(callback: (data: IChangeData) => void): Promise<{
off: () => void;
broadcastChanges: boolean;
}>;
/**
* Get the value of the specified key.
*/
getItem(key: string): Promise;
/**
* Set the value of the specified key.
*/
setItem(key: string, value: any): Promise;
/**
* Remove the value of the specified key.
*/
removeItem(key: string): Promise;
/**
* Clear all key/value pairs in the storage.
*/
clear(): Promise;
/**
* Get the number of key/value pairs in the storage.
*/
length(): Promise;
/**
* Get the name of the nth key in the storage.
*/
key(index: number): Promise;
/**
* Get all keys in the storage.
*/
keys(): Promise;
}
```