README.md

fpubsub - v1.0.0

fpubsub - v1.0.0

Table of contents

Functions

• topic
• topicFrom
• isTopic
• valueOf
• erase
• publish
• subscribe
• has
• unsubscribe
• unsubscribeAll

Type Aliases

• TopicOptions
• Topic
• ReturnStatus
• Listener
• SubscribeOptions

References

• pub
• sub
• unsub

Functions

topic

▸ topic<DATA, DATA_IN>(options?): Topic<DATA, DATA_IN>

Creates topic to be used in subscribe/publish/… functions. You can use another topis as argument for creating new topic with similar options (for dependent topic use topicFrom).

Use types topi<DATA, DATA_IN>:

• DATA: to add types for (publishign)/subscribing values
• DATA_IN: to describe publishign values if differs to DATA (see TopicOptions.mapper)

In JavaScript:

/** @type {fpubsubTopic<string>} */
const onexample= topic({ cache: true });
//…
publish(onexample, "Test");

In TypeScript:

const onexample= topic<string>({ cache: true });
//…
publish(onexample, "Test");

Type parameters

Name	Type
DATA	extends unknown
DATA_IN	extends unknown = undefined

Parameters

Name	Type	Description
options?	TopicOptions<DATA, DATA_IN>	See TopicOptions

Returns

Topic<DATA, DATA_IN>

Defined in

lib/esm.d.ts:61

---

topicFrom

▸ topicFrom<DATA, DATA_IN>(candidate): Topic<DATA, DATA_IN>

Creates topic from AbortController and maps abort signal as publish and publish as abort signal. Sets topic origin to the AbortController instance.

const onabort= topicFrom(AbortController);
subscribe(onabort, console.log);
fetch("www.example.test", { signal: onabort.origin.signal });
publish(onabort);

FYI: Fetch: Abort

Type parameters

Name	Type
DATA	extends unknown
DATA_IN	extends unknown = undefined

Parameters

Name	Type
candidate	AbortController | () => AbortController

Returns

Topic<DATA, DATA_IN>

Defined in

lib/esm.d.ts:74

▸ topicFrom<DATA, DATA_IN>(candidate): Topic<DATA, DATA_IN>

Creates dependent topic to given topic. All listeners will be called when the original topic is published.

const ontopic= topic();
const onsubtopic= topicFrom(ontopic);
subscribe(onsubtopic, console.log);
publish(ontopic, "For all `ontopic` and `onsubtopic` listeners");
publish(onsubtopic, "For only `onsubtopic` listeners");

Type parameters

Name	Type
DATA	extends unknown
DATA_IN	extends unknown = undefined

Parameters

Name	Type
candidate	Topic<any, undefined>

Returns

Topic<DATA, DATA_IN>

Defined in

lib/esm.d.ts:85

---

isTopic

▸ isTopic<T>(candidate): T extends Topic<any, any> ? true : false

const is_topic= topic();
const not_topic= {};
console.log(
	isTopic(is_topic)===true,
	isTopic(not_topic)===false
);

Type parameters

Name
T

Parameters

Name	Type
candidate	T

Returns

T extends Topic<any, any> ? true : false

Defined in

lib/esm.d.ts:96

---

valueOf

▸ valueOf<T>(topic): TopicOut<T> | undefined

Returns value of given topic. Primarly make sence in case of cached topics, elsewhere always returns undefined.

/** @type {fpubsubTopic<string>} */
const ontest= topic({ cache: true });
publish(topic, "value");
console.log(valueOf(topic)==="value");

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T

Returns

TopicOut<T> | undefined

Defined in

lib/esm.d.ts:106

---

erase

▸ erase(topic): undefined

This function can be use to erase given topic explicitly.

const ontest= topic();
subscribe(ontest, console.log);
erase(ontest);
publish(ontest);// ignored ⇐ no active topic

…but it is not neccesary:

let ontest= topic();
subscribe(ontest, console.log);
ontest= null;// JS auto remove unneeded info
publish(ontest);// throws error ⇐ no topic

…but keep in mind the topics are objects (e.g. https://stackoverflow.com/a/6326813)

Parameters

Name	Type
topic	Topic<any, any>

Returns

undefined

Defined in

lib/esm.d.ts:124

---

publish

▸ publish<T>(topic, value?): Promise<ReturnStatus>

Publishes value for given topic. Process all synchronous listeners synchronously, so if there is no async listener there is no need to await to publish.

/** @type {fpubsubTopic<string>} */
const onexample= topic({ cache: true });
publish(onexample, "Test");
publish(onexample, "Test").then(console.log).catch(console.error);

const publishExample= publish.bind(null, onexample);
publishExample("Test 2");

const publishText= publish("Test 3");
publishText(onexample);

Throws

Given topic is not Topic!

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T
value?	TopicIn<T>

Returns

Promise<ReturnStatus>

0= done, else see ReturnStatus

Defined in

lib/esm.d.ts:154

▸ publish<T>(value?): (topic: T) => Promise<ReturnStatus>

Curried version of publish.

publish("value")(onexample);
publish()(onexample);

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
value?	TopicIn<T>

Returns

fn

▸ (topic): Promise<ReturnStatus>

Parameters

Name	Type
topic	T

Returns

Promise<ReturnStatus>

Defined in

lib/esm.d.ts:162

---

subscribe

▸ subscribe<T>(topic, listener, options?): ReturnStatus

Register listener function (subscriber) to be called when topic will be emitted.

/** @type {fpubsubTopic<string>} */
const onexample= topic({ cache: true });
subscribe(onexample, console.log);

const options= {};
const subscribeExample= subscribe(onexample, options);
subscribeExample(console.error);

const subscribeInfo= subscribe(console.info, options);
subscribeInfo(onexample);

Throws

Given topic is not Topic!

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T
listener	Listener<T>
options?	SubscribeOptions

Returns

ReturnStatus

0= done, else see ReturnStatus

Defined in

lib/esm.d.ts:194

▸ subscribe<T>(topic, options?): (listener: Listener<T>) => ReturnStatus

Curried version of subscribe.

subscribe(onexample)(console.log);
subscribe(onexample, { once: true })(console.log);

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T
options?	SubscribeOptions

Returns

fn

▸ (listener): ReturnStatus

Parameters

Name	Type
listener	Listener<T>

Returns

ReturnStatus

Defined in

lib/esm.d.ts:202

▸ subscribe<T>(listener, options?): (topic: T) => ReturnStatus

Curried version of subscribe.

subscribe(console.log)(onexample);
subscribe(console.log, { once: true })(onexample);

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
listener	Listener<T>
options?	SubscribeOptions

Returns

fn

▸ (topic): ReturnStatus

Parameters

Name	Type
topic	T

Returns

ReturnStatus

Defined in

lib/esm.d.ts:210

---

has

▸ has<T>(topic, listener): boolean

Is listener listening to the given topic?

const onexample= topic();
subscribe(onexample, console.log);
console.log(
	has(onexample, console.log)===true,
	has(onexample, console.error)===false,
);

Throws

Given topic is not Topic!

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T
listener	Listener<T>

Returns

boolean

Defined in

lib/esm.d.ts:225

---

unsubscribe

▸ unsubscribe<T>(topic, listener): ReturnStatus

Unregister listener function (subscriber) to be called when topic will be emitted.

const onexample= topic();
subscribe(onexample, console.log);
unsubscribe(onexample, console.log);

Throws

Given topic is not Topic!

Type parameters

Name	Type
T	extends Topic<any, any>

Parameters

Name	Type
topic	T
listener	(value: TopicOut<T>, topic: T) => void | Promise<void>

Returns

ReturnStatus

0= done, else see ReturnStatus

Defined in

lib/esm.d.ts:237

---

unsubscribeAll

▸ unsubscribeAll(topic): ReturnStatus

Unregister all listeners for given topic.

const onexample= topic();
subscribe(onexample, console.log);
unsubscribeAll(onexample);

Throws

Given topic is not Topic!

Parameters

Name	Type
topic	Topic<any, any>

Returns

ReturnStatus

0= done, else see ReturnStatus

Defined in

lib/esm.d.ts:249

Type Aliases

TopicOptions

Ƭ TopicOptions<DATA, DATA_IN>: Object

Type parameters

Name	Type
DATA	extends any
DATA_IN	extends any = undefined

Type declaration

Name	Type	Description
cache?	boolean	Keep last published value and when new listener is registered call this function with kept value. Default false
initial?	any	This force cache= true and sets initial value.
mapper?	(value: DATA_IN) => DATA	Converts topic value from publish function to what listeners are expecting.
once?	boolean	Topic can be published only one time. Default false
origin?	any	Topic origin

Defined in

lib/esm.d.ts:1

---

Topic

Ƭ Topic<DATA, DATA_IN>: { origin: any ; is_live: boolean } & TopicOptions<DATA, DATA_IN>

Topic reference to be used in subscribe/publish/… functions. For using in JSDoc, you can use global type fpubsubTopic.

Type parameters

Name	Type
DATA	extends any
DATA_IN	extends any = undefined

Defined in

lib/esm.d.ts:22

---

ReturnStatus

Ƭ ReturnStatus: 0 | 1 | 2

Return type of functions:

• 0: operation successfully processed
• 1: given topic is not “live” (once event already published) → nothing to do
• 2, …: another non-error issue → nothing to do

…functions typically throws Error if given topic is not Topic.

Defined in

lib/esm.d.ts:134

---

Listener

Ƭ Listener<T>: (value: TopicOut<T>, topic: T) => void | Promise<void> | { handleEvent: (value: TopicOut<T>, topic: T) => void | Promise<void> }

Follows EventTarget.addEventListener() - Web APIs | MDN.

Type parameters

Name	Type
T	extends Topic<any, any>

Defined in

lib/esm.d.ts:166

---

SubscribeOptions

Ƭ SubscribeOptions: Object

Type declaration

Name	Type	Description
once?	boolean	Call only once
signal?	AbortSignal	An AbortSignal. The listener will be removed when the given AbortSignal object's abort() method is called. If not specified, no AbortSignal is associated with the listener.

Defined in

lib/esm.d.ts:170

References

pub

Renames and re-exports publish

---

sub

Renames and re-exports subscribe

---

unsub

Renames and re-exports unsubscribe