feat: persist extension

README.md

@@ -1190,6 +1190,31 @@ const server = setupServer(...handlers)
 server.listen()
 ```
 
+## Extensions
+
+### persist
+
+To persist database state and hydrate on page reload you can use persist extention. By default this one save database snapshoot in `sessionStorage` every time when any action was fired (like create new entity, update or delete).
+
+```ts
+import { factory, persist, primaryKey } from '@mswjs/data'
+
+const db = factory({
+ user: {
+ id: primaryKey(String),
+ firstName: String,
+ },
+})
+
+persist(db)
+```
+
+You can pass any key-value storage with `getItem` and `setItem` methods (like `localStorage`) by second argument:
+
+```
+persist(db, { storage: localStorage })
+```
+
 ## Honorable mentions
 
 - [Prisma](https://www.prisma.io) for inspiring the querying client.

src/db/Database.ts

@@ -9,6 +9,7 @@ import {
  PrimaryKeyType,
  PRIMARY_KEY,
 } from '../glossary'
+import { inheritInternalProperties } from '../utils/inheritInternalProperties'
 
 export const SERIALIZED_INTERNAL_PROPERTIES_KEY =
  'SERIALIZED_INTERNAL_PROPERTIES'
@@ -85,6 +86,26 @@ export class Database<Dictionary extends ModelDictionary> {
  return md5(salt)
  }
 
+ /**
+ * Sets the serialized internal properties as symbols
+ * on the given entity.
+ * @note `Symbol` properties are stripped off when sending
+ * an object over an event emitter.
+ */
+ deserializeEntity(entity: SerializedEntity): Entity<any, any> {
+ const {
+ [SERIALIZED_INTERNAL_PROPERTIES_KEY]: internalProperties,
+ ...publicProperties
+ } = entity
+
+ inheritInternalProperties(publicProperties, {
+ [ENTITY_TYPE]: internalProperties.entityType,
+ [PRIMARY_KEY]: internalProperties.primaryKey,
+ })
+
+ return publicProperties
+ }
+
  private serializeEntity(entity: Entity<Dictionary, any>): SerializedEntity {
  return {
  ...entity,
@@ -95,6 +116,31 @@ export class Database<Dictionary extends ModelDictionary> {
  }
  }
 
+ hydrate(data: Record<string, any>) {
+ Object.entries(data).forEach(([modelName, entities]) => {
+ for (const [, entity] of entities.entries()) {
+ this.create(modelName, this.deserializeEntity(entity))
+ }
+ })
+ }
+
+ toJson() {
+ return Object.entries(this.models).reduce<Record<string, any>>(
+ (json, [modelName, entities]) => {
+ const modelJson: Entity<any, any>[] = []
+
+ for (const [, entity] of entities.entries()) {
+ modelJson.push(this.serializeEntity(entity))
+ }
+
+ json[modelName] = modelJson
+
+ return json
+ },
+ {},
+ )
+ }
+
  getModel<ModelName extends keyof Dictionary>(name: ModelName) {
  return this.models[name]
  }

src/extensions/persist.ts

@@ -0,0 +1,56 @@
+import debounce from 'lodash/debounce'
+import { DATABASE_INSTANCE, FactoryAPI } from '../glossary'
+import { isBrowser, supports } from '../utils/env'
+
+type ExtensionOption = {
+ storage?: Pick<Storage, 'getItem' | 'setItem'>
+ keyPrefix?: string
+}
+
+const STORAGE_KEY_PREFIX = 'mswjs-data'
+
+// Timout to persist state with some delay
+const DEBOUNCE_PERSIST_TIME_MS = 10
+
+/**
+ * Persist database in session storage
+ */
+export function persist(
+ factory: FactoryAPI<any>,
+ options: ExtensionOption = {},
+) {
+ if (!isBrowser() || (!options.storage && !supports.sessionStorage())) {
+ return
+ }
+
+ const storage = options.storage || sessionStorage
+ const keyPrefix = options.keyPrefix || STORAGE_KEY_PREFIX
+
+ const db = factory[DATABASE_INSTANCE]
+
+ const key = `${keyPrefix}/${db.id}`
+
+ const persistState = debounce(function persistState() {
+ const json = db.toJson()
+ storage.setItem(key, JSON.stringify(json))
+ }, DEBOUNCE_PERSIST_TIME_MS)
+
+ function hydrateState() {
+ const initialState = storage.getItem(key)
+
+ if (initialState) {
+ db.hydrate(JSON.parse(initialState))
+ }
+
+ // Add event listeners only after hydration
+ db.events.on('create', persistState)
+ db.events.on('update', persistState)
+ db.events.on('delete', persistState)
+ }
+
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', hydrateState)
+ } else {
+ hydrateState()
+ }
+}

src/extensions/sync.ts

@@ -1,11 +1,5 @@
-import { ENTITY_TYPE, PRIMARY_KEY, Entity } from '../glossary'
-import {
- Database,
- DatabaseEventsMap,
- SerializedEntity,
- SERIALIZED_INTERNAL_PROPERTIES_KEY,
-} from '../db/Database'
-import { inheritInternalProperties } from '../utils/inheritInternalProperties'
+import { isBrowser, supports } from '../utils/env'
+import { Database, DatabaseEventsMap } from '../db/Database'
 
 export type DatabaseMessageEventData =
  | {
@@ -38,34 +32,11 @@ function removeListeners<Event extends keyof DatabaseEventsMap>(
  }
 }
 
-/**
- * Sets the serialized internal properties as symbols
- * on the given entity.
- * @note `Symbol` properties are stripped off when sending
- * an object over an event emitter.
- */
-function deserializeEntity(entity: SerializedEntity): Entity<any, any> {
- const {
- [SERIALIZED_INTERNAL_PROPERTIES_KEY]: internalProperties,
- ...publicProperties
- } = entity
-
- inheritInternalProperties(publicProperties, {
- [ENTITY_TYPE]: internalProperties.entityType,
- [PRIMARY_KEY]: internalProperties.primaryKey,
- })
-
- return publicProperties
-}
-
 /**
  * Synchronizes database operations across multiple clients.
  */
 export function sync(db: Database<any>) {
- const IS_BROWSER = typeof window !== 'undefined'
- const SUPPORTS_BROADCAST_CHANNEL = typeof BroadcastChannel !== 'undefined'
-
- if (!IS_BROWSER || !SUPPORTS_BROADCAST_CHANNEL) {
+ if (!isBrowser() || !supports.broadcastChannel()) {
  return
  }
 
@@ -91,16 +62,16 @@ export function sync(db: Database<any>) {
  switch (event.data.operationType) {
  case 'create': {
  const [modelName, entity, customPrimaryKey] = event.data.payload[1]
- db.create(modelName, deserializeEntity(entity), customPrimaryKey)
+ db.create(modelName, db.deserializeEntity(entity), customPrimaryKey)
  break
  }
 
  case 'update': {
  const [modelName, prevEntity, nextEntity] = event.data.payload[1]
  db.update(
  modelName,
- deserializeEntity(prevEntity),
- deserializeEntity(nextEntity),
+ db.deserializeEntity(prevEntity),
+ db.deserializeEntity(nextEntity),
  )
  break
  }

src/index.ts

@@ -1,4 +1,5 @@
 export { factory } from './factory'
+export { persist } from './extensions/persist'
 export { primaryKey } from './primaryKey'
 export { nullable } from './nullable'
 export { oneOf } from './relations/oneOf'

src/utils/env.ts

@@ -0,0 +1,12 @@
+export function isBrowser() {
+ return typeof window !== 'undefined'
+}
+
+export const supports = {
+ sessionStorage() {
+ return typeof sessionStorage !== 'undefined'
+ },
+ broadcastChannel() {
+ return typeof BroadcastChannel !== 'undefined'
+ },
+}

yarn.lock

@@ -814,7 +814,7 @@
  resolved "https://registry.yarnpkg.com/@types/cookie/-/cookie-0.4.1.tgz#bfd02c1f2224567676c1545199f87c3a861d878d"
  integrity sha512-XW/Aa8APYr6jSVVA1y/DEIZX0/GMKLEVekNG727R8cs56ahETkRAy/3DR7+fJyh7oUgGwNQaRfXCun0+KbWY7Q==
 
-"@types/debug@^4.1.5", "@types/debug@^4.1.7":
+"@types/debug@^4.1.7":
  version "4.1.7"
  resolved "https://registry.yarnpkg.com/@types/debug/-/debug-4.1.7.tgz#7cc0ea761509124709b8b2d1090d8f6c17aadb82"
  integrity sha512-9AonUzyTjXXhEOa0DnqpzZi6VHlqKMswga9EXjpXnnqxwLtdvPPtlO8evrI5D9S6asFRCQ6v+wpiUKbw+vKqyg==