@acoustic-content-sdk/redux-utils

Implementation of utility functions that help working with redux state.

Immutability

One of the core principals of the redux pattern is to keep all state immutable. This implies that when updating a value we need to make a copy of the affected objects. The following functions help to limit the size of these copies.

Updater

The createUpdater creates an wrapper around an object. This wrapper allows to set or remove (deep) properties of the wrapped object without mutating it. The updater makes sure to only create the minimum set of shallow copies.

Example:

const myObject={...};
const updater = createUpdater(myObject);

updater.set('elements.text.value', 'newValue');

const newObject = updater.get();

The updater works similar to immer but without the overhead.

Invariance Checks

During development it is important to verify that objects are not getting mutated. Use the invariance checker to test this, but make sure to not include these checks in production builds for performance reasons.

Example:

const inv = invarianceChecker(myObject);
// do some operations

// validate that myObject has not been mutated
assert(inv());

API Documentation

API Documentation

Home > @acoustic-content-sdk/redux-utils

redux-utils package

Implementation of utility functions that help working with redux state.

Functions

Function	Description
createBreadcrumb(aId, aSelParent, aSelId)	Constructs a breadcrumb trail starting at a particular ID
createUpdater(aValue, aLogSvc)	Constructs a function that updates one or more values in a json object.
equalsByRevision(aLeft, aRight)
getNavSelectors(aJson$, aLogSvc)	Returns selectors that access parent and child nodes from a navigation structure
invarianceChecker(aValue)	Creates a function that validates that an object has not changed. Note that this should only be used for debugging purposes, since it makes a deep copy of the value to test for the invariance
isDraftId(aAuthoringId)	Tests if the authoring ID has a draft suffix
isNotFromDataBase(aValue)	Tests if a value is not from a database
isNotRoot(aId)
markAsFromDataBase(aValue)	Adds a key to the item marking it as coming from the local data base
removeArrayItemByAccessor(aAccessor, aItem, aUser)
removeDataBaseMarker(aValue)	Removes the database marker from the object
removeRecord()	Creates a reducer that removes a key from a record
rxElementType(aTypeResolver, aLogSvc, aScheduler)	Resolves the element type, either directly from the element or from the authoring type
rxLogDiff(aLogger)
rxResolveAuthoringItems(idOrItem, resolveItem, resolveAsset, aLogSvc, scheduler)	Resolves the item and all referenced items and assets
selectByDeliveryId(aId)	Constructs a selector that validates that the ID is a delivery ID (not a draft ID) and selects based on that ID from the state
serializeDiff(aOld, aNew, aSameStyle, aNewStyle, aDeletedStyle)	Serializes the differences between two JSON objects
sortAuthoringItems(aResult)	Performs a topological sort on a set of resolved items
updateGenericProperties(aItem, aUser)	Updates properties of the item that depend on the environment
updateImageElement(aAccessor, aItem, aAsset)
updateRecord(aKey, aPredicate)	Creates a reducer that adds an item to a record
updateSingleItem(aPredicate)
updateValueByAccessor(aAccessor, aValue, aItem, aUser)	Updates a single property based on the accessor expression.

Interfaces

Interface	Description
ItemWithId
ItemWithLinkedDocId
ItemWithRevision
NavigationJson
NavSelectors	Interface that exposes selectors to the navigation structure
ResolvedNode
Updater	Facade that offers the modification functions for a json object. The original JSON object will not be modified and the modified object will only contain the minimum number of modifications.

Variables

Variable	Description
addToSetEpic	Constructs an epic that convers an ADD action to a SET action
cloneAuthoringItems	Basically a re-export of the clone functionality to have it all clean inside this one function
DB_KEY
DB_VALUE
ensureDraftId	Makes sure to end the ID with a draft suffix
getDeliveryId	Returns the delivery ID from an authoring ID, i.e. strips off the ':draft' suffix from the ID
getDeliveryIdFromAuthoringItem	Returns the delivery ID from an authoring item.
getValueByAccessor	Retrieves a property value by accessor
keyById	Extract the delivery ID of the draft
ROOT_ID
selectClassification	Extracts the classification property
updateItemsWithRevision

Type Aliases

Type Alias	Description
AddRecordReducer	Reducer function that adds an item to a record
AuthoringItem
ItemReducer	Reducer function that updates an item
RemoveRecordReducer	Reducer function that adds an item to a record
ResolutionResult
ResolveAuthoringAsset
ResolveAuthoringContentItem

Home > @acoustic-content-sdk/redux-utils > createBreadcrumb

createBreadcrumb() function

Constructs a breadcrumb trail starting at a particular ID

Signature:

export declare function createBreadcrumb<T>(aId: string, aSelParent: UnaryFunction<string, Observable<T>>, aSelId: UnaryFunction<T, string>): Observable<T[]>;

Parameters

Parameter	Type	Description
aId	string	the start ID
aSelParent	UnaryFunction<string, Observable<T>>	selector function for the parent node
aSelId	UnaryFunction<T, string>	selector function for the ID from a parent node

Returns:

Observable<T[]>

the breadcrumb trail

Home > @acoustic-content-sdk/redux-utils > createUpdater

createUpdater() function

Constructs a function that updates one or more values in a json object.

Signature:

export declare function createUpdater<T>(aValue: T, aLogSvc?: LoggerService): Updater<T>;

Parameters

Parameter	Type	Description
aValue	T	the JSON structure to update
aLogSvc	LoggerService

Returns:

Updater<T>

updater functions

Home > @acoustic-content-sdk/redux-utils > equalsByRevision

equalsByRevision() function

Signature:

export declare function equalsByRevision(aLeft: ItemWithRevision, aRight: ItemWithRevision): boolean;

Parameters

Parameter	Type	Description
aLeft	ItemWithRevision
aRight	ItemWithRevision

Returns:

boolean

Home > @acoustic-content-sdk/redux-utils > getNavSelectors

getNavSelectors() function

Returns selectors that access parent and child nodes from a navigation structure

Signature:

export declare function getNavSelectors(aJson$: Observable<NavigationJson>, aLogSvc?: LoggerService): NavSelectors;

Parameters

Parameter	Type	Description
aJson$	Observable<NavigationJson>	the JSON that represents the navigation
aLogSvc	LoggerService	optional logger service

Returns:

NavSelectors

the selectors

Home > @acoustic-content-sdk/redux-utils > invarianceChecker

invarianceChecker() function

Creates a function that validates that an object has not changed. Note that this should only be used for debugging purposes, since it makes a deep copy of the value to test for the invariance

Signature:

export declare function invarianceChecker(aValue: any): Generator<boolean>;

Parameters

Parameter	Type	Description
aValue	any	the value to test

Returns:

Generator<boolean>

the validator

Home > @acoustic-content-sdk/redux-utils > isDraftId

isDraftId() function

Tests if the authoring ID has a draft suffix

Signature:

export declare function isDraftId(aAuthoringId: string): boolean;

Parameters

Parameter	Type	Description
aAuthoringId	string	the ID

Returns:

boolean

true if we have a draft suffix, else false

Home > @acoustic-content-sdk/redux-utils > isNotFromDataBase

isNotFromDataBase() function

Tests if a value is not from a database

Signature:

export declare function isNotFromDataBase(aValue: any): boolean;

Parameters

Parameter	Type	Description
aValue	any	the value

Returns:

boolean

true if the value exists and if it is not from the database, else false

Home > @acoustic-content-sdk/redux-utils > isNotRoot

isNotRoot() function

Signature:

export declare function isNotRoot(aId: string): boolean;

Parameters

Parameter	Type	Description
aId	string

Returns:

boolean

Home > @acoustic-content-sdk/redux-utils > markAsFromDataBase

markAsFromDataBase() function

Adds a key to the item marking it as coming from the local data base

Signature:

export declare function markAsFromDataBase<T>(aValue: T): T;

Parameters

Parameter	Type	Description
aValue	T	the value to work with

Returns:

T

a value with the marker

Home > @acoustic-content-sdk/redux-utils > removeArrayItemByAccessor

removeArrayItemByAccessor() function

Signature:

export declare function removeArrayItemByAccessor<T extends BaseAuthoringItem>(aAccessor: AccessorType, aItem: T, aUser?: User): Updater<T>;

Parameters

Parameter	Type	Description
aAccessor	AccessorType
aItem	T
aUser	User

Returns:

Updater<T>

Home > @acoustic-content-sdk/redux-utils > removeDataBaseMarker

removeDataBaseMarker() function

Removes the database marker from the object

Signature:

export declare function removeDataBaseMarker<T>(aValue: T): T;

Parameters

Parameter	Type	Description
aValue	T	the value to work with

Returns:

T

a value without the marker

Home > @acoustic-content-sdk/redux-utils > removeRecord

removeRecord() function

Creates a reducer that removes a key from a record

Signature:

export declare function removeRecord<T>(): RemoveRecordReducer<T>;

Returns:

RemoveRecordReducer<T>

the reducer

Home > @acoustic-content-sdk/redux-utils > rxElementType

rxElementType() function

Resolves the element type, either directly from the element or from the authoring type

Signature:

export declare function rxElementType(aTypeResolver: UnaryFunction<string, Observable<AuthoringType>>, aLogSvc?: LoggerService, aScheduler?: SchedulerLike): UnaryFunction<AccessorType, OperatorFunction<RenderingContext, ELEMENT_TYPE>>;

Parameters

Parameter	Type	Description
aTypeResolver	UnaryFunction<string, Observable<AuthoringType>>
aLogSvc	LoggerService	logger service
aScheduler	SchedulerLike	optional scheduler

Returns:

UnaryFunction<AccessorType, OperatorFunction<RenderingContext, ELEMENT_TYPE>>

the resolved type or undefined if the type could not be determined

Home > @acoustic-content-sdk/redux-utils > rxLogDiff

rxLogDiff() function

Signature:

export declare function rxLogDiff<T>(aLogger: Logger): MonoTypeOperatorFunction<T>;

Parameters

Parameter	Type	Description
aLogger	Logger

Returns:

MonoTypeOperatorFunction<T>

Home > @acoustic-content-sdk/redux-utils > rxResolveAuthoringItems

rxResolveAuthoringItems() function

Resolves the item and all referenced items and assets

Signature:

export declare function rxResolveAuthoringItems(idOrItem: IdOrItem, resolveItem: ResolveAuthoringContentItem, resolveAsset: ResolveAuthoringAsset, aLogSvc?: LoggerService, scheduler?: SchedulerLike): Observable<ResolutionResult>;

Parameters

Parameter	Type	Description
idOrItem	IdOrItem
resolveItem	ResolveAuthoringContentItem	callback to resolve a content item
resolveAsset	ResolveAuthoringAsset	callback to resolve an asset
aLogSvc	LoggerService
scheduler	SchedulerLike	scheduler for recursive calls

Returns:

Observable<ResolutionResult>

the observable containing the resolution result

Home > @acoustic-content-sdk/redux-utils > selectByDeliveryId

selectByDeliveryId() function

Constructs a selector that validates that the ID is a delivery ID (not a draft ID) and selects based on that ID from the state

Signature:

export declare function selectByDeliveryId<T>(aId?: string): UnaryFunction<Record<string, T>, T>;

Parameters

Parameter	Type	Description
aId	string	the ID

Returns:

UnaryFunction<Record<string, T>, T>

a selector for that ID based on some state

Home > @acoustic-content-sdk/redux-utils > serializeDiff

serializeDiff() function

Serializes the differences between two JSON objects

Signature:

export declare function serializeDiff(aOld: any, aNew: any, aSameStyle?: UnaryFunction<string, string>, aNewStyle?: UnaryFunction<string, string>, aDeletedStyle?: UnaryFunction<string, string>): string;

Parameters

Parameter	Type	Description
aOld	any	old object
aNew	any	new objects
aSameStyle	UnaryFunction<string, string>	styling callback for identical style
aNewStyle	UnaryFunction<string, string>	styling callback for new style
aDeletedStyle	UnaryFunction<string, string>	styling callback for deleted style

Returns:

string

the serialized string

Home > @acoustic-content-sdk/redux-utils > sortAuthoringItems

sortAuthoringItems() function

Performs a topological sort on a set of resolved items

Signature:

export declare function sortAuthoringItems(aResult: ResolutionResult): AuthoringItem[];

Parameters

Parameter	Type	Description
aResult	ResolutionResult	the resolution result, basically a graph of nodes

Returns:

AuthoringItem[]

the items in toplogical order, i.e. parents before children

Home > @acoustic-content-sdk/redux-utils > updateGenericProperties

updateGenericProperties() function

Updates properties of the item that depend on the environment

Signature:

export declare function updateGenericProperties<T extends BaseAuthoringItem>(aItem: Updater<T>, aUser?: User): Updater<T>;

Parameters

Parameter	Type	Description
aItem	Updater<T>	updater for the item
aUser	User	optionally the current user

Returns:

Updater<T>

the updater after the item has been modified

Home > @acoustic-content-sdk/redux-utils > updateImageElement

updateImageElement() function

Signature:

export declare function updateImageElement(aAccessor: AccessorType, aItem: Updater<AuthoringContentItem>, aAsset: AuthoringAsset): Updater<AuthoringContentItem>;

Parameters

Parameter	Type	Description
aAccessor	AccessorType
aItem	Updater<AuthoringContentItem>
aAsset	AuthoringAsset

Returns:

Updater<AuthoringContentItem>

Home > @acoustic-content-sdk/redux-utils > updateRecord

updateRecord() function

Creates a reducer that adds an item to a record

Signature:

export declare function updateRecord<T>(aKey: UnaryFunction<T, string>, aPredicate?: EqualsPredicate<T>): AddRecordReducer<T>;

Parameters

Parameter	Type	Description
aKey	UnaryFunction<T, string>	function to extract the key from the item
aPredicate	EqualsPredicate<T>	predicate to check if two items are equal

Returns:

AddRecordReducer<T>

the reducer

Home > @acoustic-content-sdk/redux-utils > updateSingleItem

updateSingleItem() function

Signature:

export declare function updateSingleItem<T>(aPredicate?: EqualsPredicate<T>): ItemReducer<T>;

Parameters

Parameter	Type	Description
aPredicate	EqualsPredicate<T>

Returns:

ItemReducer<T>

Home > @acoustic-content-sdk/redux-utils > updateValueByAccessor

updateValueByAccessor() function

Updates a single property based on the accessor expression.

Signature:

export declare function updateValueByAccessor<T extends BaseAuthoringItem>(aAccessor: AccessorType, aValue: any, aItem: T, aUser?: User): Updater<T>;

Parameters

Parameter	Type	Description
aAccessor	AccessorType	the accessor expression that points
aValue	any	the new value
aItem	T	the item to update
aUser	User

Returns:

Updater<T>

a copy of the item with the modified value

Home > @acoustic-content-sdk/redux-utils > ItemWithId

ItemWithId interface

Signature:

export interface ItemWithId 

Properties

Property	Type	Description
id	string

Home > @acoustic-content-sdk/redux-utils > ItemWithLinkedDocId

ItemWithLinkedDocId interface

Signature:

export interface ItemWithLinkedDocId 

Properties

Property	Type	Description
id	string
linkedDocId	string

Home > @acoustic-content-sdk/redux-utils > ItemWithRevision

ItemWithRevision interface

Signature:

export interface ItemWithRevision extends ItemWithId 

Properties

Property	Type	Description
rev	string

Home > @acoustic-content-sdk/redux-utils > NavigationJson

NavigationJson interface

Signature:

export interface NavigationJson 

Properties

Property	Type	Description
children	NavigationJson[]
id	string

Home > @acoustic-content-sdk/redux-utils > NavSelectors

NavSelectors interface

Interface that exposes selectors to the navigation structure

Signature:

export interface NavSelectors 

Properties

Property	Type	Description
root	string	ID of the (virtual) root item of the navigation
selectChildren	UnaryFunction<string, Observable<string[]>>	Selects the children of a particular item
selectParent	UnaryFunction<string, Observable<string>>	Selects the parent of a particular item

Home > @acoustic-content-sdk/redux-utils > ResolvedNode

ResolvedNode interface

Signature:

export interface ResolvedNode<T> 

Properties

Property	Type	Description
id	string
item	T
parentId	string

Home > @acoustic-content-sdk/redux-utils > Updater

Updater interface

Facade that offers the modification functions for a json object. The original JSON object will not be modified and the modified object will only contain the minimum number of modifications.

Signature:

export interface Updater<T> 

Properties

Property	Type	Description
add	BiFunction<string, any, T>	Inserts a new value into an array pointed to by the accessor. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.Pass undefined as the new value to delete the value.Returns the modified version of the top level object.
del	UnaryFunction<string, T>	Removes the value pointed to by the accessor. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.Returns the modified version of the top level object.
get	Generator<T>	Returns the top level, modified object
set	BiFunction<string, any, T>	Replaces the value pointed to by the accessor with a new value. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.Pass undefined as the new value to delete the value.Returns the modified version of the top level object.

Home > @acoustic-content-sdk/redux-utils > addToSetEpic

addToSetEpic variable

Constructs an epic that convers an ADD action to a SET action

Signature:

addToSetEpic: <T>(aAddAction: string, aSetAction: string) => Epic<any, any, any, any>

Home > @acoustic-content-sdk/redux-utils > cloneAuthoringItems

cloneAuthoringItems variable

Basically a re-export of the clone functionality to have it all clean inside this one function

Signature:

cloneAuthoringItems: UnaryFunction<AuthoringItem[], AuthoringItem[]>

Home > @acoustic-content-sdk/redux-utils > DB_KEY

DB_KEY variable

Signature:

DB_KEY = "ecec4405-7fb1-4b86-8d27-7338eea45683"

Home > @acoustic-content-sdk/redux-utils > DB_VALUE

DB_VALUE variable

Signature:

DB_VALUE = "e3257dbc-1ca8-4d57-94a2-37934960f39f"

Home > @acoustic-content-sdk/redux-utils > ensureDraftId

ensureDraftId variable

Makes sure to end the ID with a draft suffix

Signature:

ensureDraftId: (aAuthoringId: string) => string

Home > @acoustic-content-sdk/redux-utils > getDeliveryId

getDeliveryId variable

Returns the delivery ID from an authoring ID, i.e. strips off the ':draft' suffix from the ID

Signature:

getDeliveryId: UnaryFunction<string, string>

Home > @acoustic-content-sdk/redux-utils > getDeliveryIdFromAuthoringItem

getDeliveryIdFromAuthoringItem variable

Returns the delivery ID from an authoring item.

Signature:

getDeliveryIdFromAuthoringItem: UnaryFunction<ItemWithLinkedDocId | BaseAuthoringItem, string>

Home > @acoustic-content-sdk/redux-utils > getValueByAccessor

getValueByAccessor variable

Retrieves a property value by accessor

Signature:

getValueByAccessor: <T>(aItem: BaseAuthoringItem, aAccessor: string) => T

Home > @acoustic-content-sdk/redux-utils > keyById

keyById variable

Extract the delivery ID of the draft

Signature:

keyById: UnaryFunction<ItemWithLinkedDocId, string>

Home > @acoustic-content-sdk/redux-utils > ROOT_ID

ROOT_ID variable

Signature:

ROOT_ID: string

Home > @acoustic-content-sdk/redux-utils > selectClassification

selectClassification variable

Extracts the classification property

Signature:

selectClassification: UnaryFunction<BaseAuthoringItem | ContentItem, string>

Home > @acoustic-content-sdk/redux-utils > updateItemsWithRevision

updateItemsWithRevision variable

Signature:

updateItemsWithRevision: <T extends ItemWithRevision>(aState: Record<string, T>, aItem: T) => Record<string, T>

Home > @acoustic-content-sdk/redux-utils > AddRecordReducer

AddRecordReducer type

Reducer function that adds an item to a record

Signature:

export declare type AddRecordReducer<T> = BiFunction<Record<string, T>, T, Record<string, T>>;

Home > @acoustic-content-sdk/redux-utils > AuthoringItem

AuthoringItem type

Signature:

export declare type AuthoringItem = AuthoringContentItem | AuthoringAsset;

Home > @acoustic-content-sdk/redux-utils > ItemReducer

ItemReducer type

Reducer function that updates an item

Signature:

export declare type ItemReducer<T> = BiFunction<T, T, T>;

Home > @acoustic-content-sdk/redux-utils > RemoveRecordReducer

RemoveRecordReducer type

Reducer function that adds an item to a record

Signature:

export declare type RemoveRecordReducer<T> = BiFunction<Record<string, T>, string, Record<string, T>>;

Home > @acoustic-content-sdk/redux-utils > ResolutionResult

ResolutionResult type

Signature:

export declare type ResolutionResult = Record<string, ResolvedNode<AuthoringItem>>;

Home > @acoustic-content-sdk/redux-utils > ResolveAuthoringAsset

ResolveAuthoringAsset type

Signature:

export declare type ResolveAuthoringAsset = UnaryFunction<string, Observable<AuthoringAsset>>;

Home > @acoustic-content-sdk/redux-utils > ResolveAuthoringContentItem

ResolveAuthoringContentItem type

Signature:

export declare type ResolveAuthoringContentItem = UnaryFunction<string, Observable<AuthoringContentItem>>;

Home > @acoustic-content-sdk/redux-utils > ItemWithId > id

ItemWithId.id property

Signature:

id?: string;

Home > @acoustic-content-sdk/redux-utils > NavigationJson > children

NavigationJson.children property

Signature:

children?: NavigationJson[];

Home > @acoustic-content-sdk/redux-utils > NavigationJson > id

NavigationJson.id property

Signature:

id: string;

Home > @acoustic-content-sdk/redux-utils > ItemWithRevision > rev

ItemWithRevision.rev property

Signature:

rev?: string;

Home > @acoustic-content-sdk/redux-utils > ItemWithLinkedDocId > id

ItemWithLinkedDocId.id property

Signature:

readonly id?: string;

Home > @acoustic-content-sdk/redux-utils > ItemWithLinkedDocId > linkedDocId

ItemWithLinkedDocId.linkedDocId property

Signature:

readonly linkedDocId?: string;

Home > @acoustic-content-sdk/redux-utils > ResolvedNode > id

ResolvedNode.id property

Signature:

id: string;

Home > @acoustic-content-sdk/redux-utils > ResolvedNode > item

ResolvedNode.item property

Signature:

item: T;

Home > @acoustic-content-sdk/redux-utils > ResolvedNode > parentId

ResolvedNode.parentId property

Signature:

parentId?: string;

Home > @acoustic-content-sdk/redux-utils > NavSelectors > root

NavSelectors.root property

ID of the (virtual) root item of the navigation

Signature:

root: string;

Home > @acoustic-content-sdk/redux-utils > NavSelectors > selectChildren

NavSelectors.selectChildren property

Selects the children of a particular item

Signature:

selectChildren: UnaryFunction<string, Observable<string[]>>;

Home > @acoustic-content-sdk/redux-utils > NavSelectors > selectParent

NavSelectors.selectParent property

Selects the parent of a particular item

Signature:

selectParent: UnaryFunction<string, Observable<string>>;

Home > @acoustic-content-sdk/redux-utils > Updater > add

Updater.add property

Inserts a new value into an array pointed to by the accessor. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.

Pass undefined as the new value to delete the value.

Returns the modified version of the top level object.

Signature:

add: BiFunction<string, any, T>;

Home > @acoustic-content-sdk/redux-utils > Updater > del

Updater.del property

Removes the value pointed to by the accessor. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.

Returns the modified version of the top level object.

Signature:

del: UnaryFunction<string, T>;

Home > @acoustic-content-sdk/redux-utils > Updater > get

Updater.get property

Returns the top level, modified object

Signature:

get: Generator<T>;

Home > @acoustic-content-sdk/redux-utils > Updater > set

Updater.set property

Replaces the value pointed to by the accessor with a new value. All values across the parent path will be cloned (shallow) if they do not have a clone, yet.

Pass undefined as the new value to delete the value.

Returns the modified version of the top level object.

Signature:

set: BiFunction<string, any, T>;