device-storage sharable records

A local collection of records, stored in the device (browser), where any record can be shared as a URL.

As an example of usage, this module can be used to store personal preference settings, like a view setup (e.g. dashboard), but also be able to share this setup with someone else, and when doing so the receiver will get a copy of the setup stored in his/her local collection and own that piece of data in his/her device/browser.

Use this when:

• You're OK with letting the users own and handle certain settings instead of storing it centrally in a server.
• You don't control the backend but need to persist some (non-critical) dynamic dataset at the user.

To create a device storage sharable records manager, or local collection, it is recommended to input some settings like such:

const recordSchema = { title: '', items: [] };
const shallowProjection = ['title'];
const recordPrefix = 'ITEM.';

const localCollection = createLocalCollection({
  recordSchema,
  shallowProjection,
  recordPrefix,
});

• recordSchema: This is used when creating new records. (id is added internaly)
• shallowProjection: The properties that are needed to present the collection of possible records to the user. (Read about records part of the manager state, below)
• recordPrefix: This prefix makes it possible to have several separate local collections. (Since localStorage is shared among all websites on the same domain, this can ensure that each site uses a unique prefix)

The object that is returned from createLocalCollection contains first and foremost:

• useLocalCollection: The main hook for the (zustand) internal state. See below for what the internal state contains.
• useCurrentRecord: A helper hook for the current record.
• useRecords: A helper hook for the shallow records array.

Also, for non-React environments or integrations, some util functions are returned. Look below.

The internal (zustand) state contains:

• current: The entire record currently selected.
• records: Array of all records in storage, with only properties id plus what's in shallowProjection.
• dUrl: The generated URL from current record.

And the actions available are:

• init: Must be run, e.g. at application startup. Reads the persistant local storage and populates current & records. Give this function a URL (or only the search/arguments part of it) to import an exported record.
• updateCurrent: Takes a record object and updates the current record.
• createRecord: Creates a new record and sets it as current.
• switchRecord: Give this function an id and it will search for it in the storage and set it as current. If it is given the NEW_RECORD_KEY exported from this module, it will instead create a new record (same as createRecord).
• deleteRecord: Given an id this will remove that record (from storage and records) and if that record is the current it will select a random record as current, or create a new one if no other exists.
• exportToUrl: Export the current record to a URL, that will be put in dUrl.

API

Options input

See description about these above.

• recordSchema: object
• shallowProjection: array
• recordPrefix: string

It is also possible to replace the default localStorage use, by providing storageFns as option:

• storageFns: An object with
  • storageGet: (key: string) => string
  • storageSet: (key: string, value: string) => bool
  • storageRemove: (key: string) => bool
  • storageGetAll: () => object

And lastly, if globalThis.location?.href.split('?')[0] is not the way to get the base URL for your environment (if you want to use the share feature), add this to options:

• getBaseUrl: () => string,

createLocalCollection return

See description about these above.

• useLocalCollection: (selector: function) => any (See zustand docs for details).
• useCurrentRecord: () => object
• useRecords: () => records

For non-React environments or integrations, some util functions are returned:

• getStore: () => useLocalCollection.getState()
• setState: (updater) => useLocalCollection.setState(updater)
• subscribe: useLocalCollection.subscribe
• destroy: useLocalCollection.destroy
• getNewRecord: reducer.getNewRecord
• getSelectedRecordId: reducer.getSelectedRecordId

To integrate this into other state managers, you could use some listener. Here is an example for binding to an XState (v5+) machine:

import { createLocalCollection } from 'device-storage-sharable-records';

export const localCollection = createLocalCollection(/* As above */);

const localCollectionListener = fromCallback(({ sendBack }) => {
  localCollection.subscribe(({ current = {}, dUrl } = {}, prevState = {}) => {
    console.log('localCollectionListener event:', current.id, dUrl);
    // A record is imported:
    if (current.id !== prevState.current?.id) return sendBack({ type: 'init', output: current });
    // A record is exported:
    if (dUrl && dUrl !== prevState.dUrl) return (globalThis.location = dUrl);
    return undefined;
  });
  localCollection.getStore().init(globalThis.location.search);
  return localCollection.destroy;
});

Licence

MIT