store.md

Namespace store

Table of Contents

• Introduction
• API
  • create(id: string): Store
  • get(id: string): Store
  • getOrCreate(id: string): Store
  • count: number
  • Interface Store
    • store.id: string
    • store.set(key: string, value: any): void
    • store.get(key: string): any
    • store.has(key: string): boolean
    • store.size: number

Introduction

Store API is a necessary complement of sharing transportable objects across JavaScript threads, on top of passing objects via arguments. During store.set, values marshalled into JSON and stored in process heap, so all threads can access it, and unmarshalled while users retrieve them via store.get.

Though very convenient, it's not recommended to use store to pass values within a transaction or request, since its overhead is more than passing objects by arguments (there are extra locking, etc.). Besides, developers have the obligation to delete the key after usage, while it's automatically managed by reference counting in passing arguments.

API

Following APIs are exposed to create, get and operate upon stores.

create(id: string): Store

It creates a store by a string identifer that can be used to get the store later. When all references to the store from all JavaScript VMs are cleared, the store will be destroyed. Thus always keep a reference at global or module scope is usually a good practice using Store. Error will be thrown if the id already exists.

Example:

var store = napa.store.create('store1');

get(id: string): Store

It gets a reference of store by a string identifier. undefined will be returned if the id doesn't exist.

Example:

var store = napa.store.get('store1');

getOrCreate(id: string): Store

It gets a reference of store by a string identifier, or creates it if the id doesn't exist. This API is handy when you want to create a store in code that is executed by every worker of a zone, since it doesn't break symmetry.

Example:

var store = napa.store.getOrCreate('store1');

count: number

It returns count of living stores.

Interface Store

Interface that let user to put and get objects across multiple JavaScript VMs.

store.id: string

It gets the string identifier for the store.

store.set(key: string, value: any): void

It puts a transportable value into store with a string key. If key already exists, new value will override existing value.

Example:

store.set('status', 1);

store.get(key: string): any

It gets a transportable value from the store by a string key. If key doesn't exist, undefined will be returned.

Example:

var value = store.get('status');
assert(value === 1);

store.has(key: string): boolean

It tells if a key exists in current store.

Example:

assert(store.has('status'))

store.size: number

It tells how many keys are stored in current store.