DOCUMENTATION.md

Modules

DataStore

Data store prototype object. All data store implementations inherit from this via datastore#createDataStore.

defaults

Data store constants and helper methods.

errors

Helper "factory" methods for data store errors (see error ids).

datastore

UserEvents

Prototype object for per-user events data. DataStore#events must return an implementation that inherits from this via datastore#createUserEvents.

UserStreams

Prototype object for per-user streams data. DataStore#streams must return an implementation that inherits from this via datastore#createUserStreams.

Constants

ErrorIds

Identifier constants for data store errors.

PryvDataStoreError

DataStore

errors

errors

Functions

PryvDataStoreError(id, message, [data], [innerError])

Constructor for data store errors.

Typedefs

identifier : string

A string uniquely identifying an object (user, event, stream, etc.)

timestamp : number

A positive floating-point number representing the number of seconds since a reference time (Unix epoch time).

UserStreams : undefined

UserEvents : undefined

FnKeyValueGetAll ⇒ object

FnKeyValueGet ⇒ *

FnKeyValueSet ⇒ void

KeyValueData : object

StoreInitializationParams : object

FnLog : function

Logger

identifier : string

timestamp : number

integrity : string

Event : object

EventsQuery : object

StreamQueryItem : object

EventDeletionItem : object

AttachmentItem : object

Object to pass when creating events with attachments or adding attachments to events

AttachmentResponseItem : object

Informations sent by the store after saving attachment

identifier : string

timestamp : number

// time in UNIX time (seconds)

Stream : object

StreamDeletionItem : object

DataStore

Data store prototype object. All data store implementations inherit from this via datastore#createDataStore.

• DataStore
  • .streams : UserStreams
  • .events : UserEvents
  • .init(params) ⇒ Promise.<DataStore>
  • .deleteUser(userId)

DataStore.streams : UserStreams

The UserStreams implementation. Must be set in init.

Kind: static property of DataStore

DataStore.events : UserEvents

The UserEvents implementation. Must be set in init.

Kind: static property of DataStore

DataStore.init(params) ⇒ Promise.<DataStore>

Initialize the store.

Kind: static method of DataStore
Returns: Promise.<DataStore> - The data store object itself (for method chaining).

Param	Type
params	StoreInitializationParams

DataStore.deleteUser(userId)

Called when the given user is deleted from Pryv.io, to let the store delete the related data if appropriate.

Kind: static method of DataStore

Param	Type
userId	identifier

defaults

Data store constants and helper methods.

• defaults
  • static
    • .UnknownDate : number
    • .SystemAccessId : string
    • .UnknownAccessId : string
    • .ExternalAccessIdPrefix : string
  • inner
    • ~applyOnEvent(event)
    • ~applyOnEvents(events)
    • ~applyOnStream(stream, [parentId])
    • ~applyOnStreams(streams, [parentId])

defaults.UnknownDate : number

Timestamp representing an unknown creation/modification time.

Kind: static property of defaults

defaults.SystemAccessId : string

'System' access id for created by / modified by.

Kind: static property of defaults

defaults.UnknownAccessId : string

'Unknown' access id for created by / modified by.

Kind: static property of defaults

defaults.ExternalAccessIdPrefix : string

Access id prefix used to tag external identifiers for created by / modified by.

Kind: static property of defaults

defaults~applyOnEvent(event)

Adds missing mandatory properties to the given event. Note: mutates the event object.

Kind: inner method of defaults

Param	Type
event	Object

defaults~applyOnEvents(events)

Adds missing mandatory properties to the given events. Note: mutates the event objects.

Kind: inner method of defaults

Param	Type
events	Array.<Object>

defaults~applyOnStream(stream, [parentId])

Adds missing mandatory properties to the given stream and its children (if present). Note: mutates the stream object.

Kind: inner method of defaults

Param	Type	Default	Description
stream	Object
[parentId]	string	null	for parentId of the stream

defaults~applyOnStreams(streams, [parentId])

Adds missing mandatory properties to the given streams and their children (if present). Note: mutates the stream objects.

Kind: inner method of defaults

Param	Type	Default	Description
streams	Array.<Object>
[parentId]	string	null	for parentId of the stream

errors

Helper "factory" methods for data store errors (see error ids).

• errors
  • .unexpectedError(message, data, innerError) ⇒ PryvDataStoreError
  • .invalidRequestStructure(message, data, innerError) ⇒ PryvDataStoreError
  • .unknownResource(resourceType, id, innerError) ⇒ PryvDataStoreError
  • .itemAlreadyExists(resourceType, conflictingKeys, innerError) ⇒ PryvDataStoreError
  • .invalidItemId(message, data, innerError) ⇒ PryvDataStoreError
  • .unsupportedOperation(message, [data], [innerError]) ⇒ PryvDataStoreError

errors.unexpectedError(message, data, innerError) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
message	string
data	*
innerError	Error

errors.invalidRequestStructure(message, data, innerError) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
message	string
data	*
innerError	Error

errors.unknownResource(resourceType, id, innerError) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
resourceType	string
id	string
innerError	Error

errors.itemAlreadyExists(resourceType, conflictingKeys, innerError) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
resourceType	string
conflictingKeys	Array.<string>
innerError	Error

errors.invalidItemId(message, data, innerError) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
message	string
data	*
innerError	Error

errors.unsupportedOperation(message, [data], [innerError]) ⇒ PryvDataStoreError

Kind: static method of errors

Param	Type
message	string
[data]	*
[innerError]	Error

datastore

• datastore
  • .createDataStore(implementation) ⇒ DataStore
  • .createUserStreams(implementation) ⇒ UserStreams
  • .createUserEvents(implementation) ⇒ UserEvents

datastore.createDataStore(implementation) ⇒ DataStore

Create a new data store object with the given implementation.

Kind: static method of datastore

Param	Type	Description
implementation	Object	An object implementing DataStore methods

datastore.createUserStreams(implementation) ⇒ UserStreams

Create a new user streams object with the given implementation.

Kind: static method of datastore

Param	Type	Description
implementation	Object	An object implementing UserStreams methods

datastore.createUserEvents(implementation) ⇒ UserEvents

Create a new user events object with the given implementation.

Kind: static method of datastore

Param	Type	Description
implementation	Object	An object implementing UserEvents methods

UserEvents

Prototype object for per-user events data. DataStore#events must return an implementation that inherits from this via datastore#createUserEvents.

• UserEvents
  • .getOne(userId, eventId) ⇒ Promise.<(Event|null)>
  • .get(userId, query, options) ⇒ Promise.<Array.<Event>>
  • .getStreamed(userId, query, options) ⇒ Promise.<ReadableStream.<Event>>
  • .getDeletionsStreamed(userId, query, [options]) ⇒ Promise.<ReadableStream.<EventDeletionItem>>
  • .getHistory(userId, eventId) ⇒ Promise.<Array.<Event>>
  • .create(userId, eventData) ⇒ Promise.<Event>
  • .addAttachment(userId, eventId, attachmentItem) ⇒ Promise.<Event>
  • .getAttachment(userId, eventId, fileId) ⇒ Promise.<ReadableStream>
  • .deleteAttachment(userId, eventId, fileId) ⇒ Promise.<AttachmentResponseItem>
  • .update(userId, eventData) ⇒ Promise.<boolean>
  • .delete(userId, eventId) ⇒ Promise.<(Event|EventDeletionItem)>

UserEvents.getOne(userId, eventId) ⇒ Promise.<(Event|null)>

Kind: static method of UserEvents

Param	Type
userId	identifier
eventId	identifier

UserEvents.get(userId, query, options) ⇒ Promise.<Array.<Event>>

Get events for this user.

Kind: static method of UserEvents

Param	Type	Description
userId	identifier
query	EventsQuery	Event query
options	Object

UserEvents.getStreamed(userId, query, options) ⇒ Promise.<ReadableStream.<Event>>

Get events as a stream for this user.

Kind: static method of UserEvents

Param	Type	Description
userId	identifier
query	EventsQuery	Event query
options	Object

UserEvents.getDeletionsStreamed(userId, query, [options]) ⇒ Promise.<ReadableStream.<EventDeletionItem>>

Kind: static method of UserEvents

Param	Type
userId	identifier
query	Object
[options]	Object

UserEvents.getHistory(userId, eventId) ⇒ Promise.<Array.<Event>>

Kind: static method of UserEvents

Param	Type
userId	identifier
eventId	identifier

UserEvents.create(userId, eventData) ⇒ Promise.<Event>

Kind: static method of UserEvents
Returns: Promise.<Event> - - The created event
Throws:

• PryvDataStoreError with id item-already-exists
• PryvDataStoreError with id invalid-item-id
• PryvDataStoreError with id resource-is-readonly if either storage or parent stream is read-only

See: Create events in Pryv.io API reference

Param	Type
userId	identifier
eventData	object

UserEvents.addAttachment(userId, eventId, attachmentItem) ⇒ Promise.<Event>

Add the given file to the event.

Kind: static method of UserEvents
Returns: Promise.<Event> - - The updated event
Throws:

• PryvDataStoreError with id item-already-exists
• PryvDataStoreError with id invalid-item-id
• PryvDataStoreError with id resource-is-readonly if either storage or parent stream is read-only

Param	Type	Description
userId	identifier
eventId	identifier
attachmentItem	AttachmentItem	The file's information and data

UserEvents.getAttachment(userId, eventId, fileId) ⇒ Promise.<ReadableStream>

Retrieve the specified file as a stream.

Kind: static method of UserEvents

Param	Type
userId	identifier
eventId	identifier
fileId	identifier

UserEvents.deleteAttachment(userId, eventId, fileId) ⇒ Promise.<AttachmentResponseItem>

Delete the specified file.

Kind: static method of UserEvents
Returns: Promise.<AttachmentResponseItem> - - The ids and other information related to the attachments
Throws:

• PryvDataStoreError with id invalid-item-id
• PryvDataStoreError with id resource-is-readonly if either storage or parent stream is read-only

Param	Type
userId	identifier
eventId	identifier
fileId	identifier

UserEvents.update(userId, eventData) ⇒ Promise.<boolean>

Update the specified event with new data (the given event data replaces the original data).

Kind: static method of UserEvents
Returns: Promise.<boolean> - - true if an event was updated
Throws:

• PryvDataStoreError with id resource-is-readonly if either storage or parent stream is read-only

Param	Type	Description
userId	identifier
eventData	Event	New event data

UserEvents.delete(userId, eventId) ⇒ Promise.<(Event|EventDeletionItem)>

Kind: static method of UserEvents
Returns: Promise.<(Event|EventDeletionItem)> - - The trashed Event
Throws:

• PryvDataStoreError with id item-already-exists
• PryvDataStoreError with id resource-is-readonly if either storage or parent stream is read-only

See: https://api.pryv.com/reference/#delete-event

Param	Type
userId	identifier
eventId	identifier

UserStreams

Prototype object for per-user streams data. DataStore#streams must return an implementation that inherits from this via datastore#createUserStreams.

• UserStreams
  • .getOne(userId, query) ⇒ Promise.<(Stream|null)>
  • .get(userId, query) ⇒ Promise.<Array.<Stream>>
  • .getDeletions(userId, deletionsSince) ⇒ Promise.<StreamDeletionItem>
  • .create(userId, streamData) ⇒ Promise.<Stream>
  • .createDeleted(userId, streamData) ⇒ Promise.<Stream>
  • .update(userId, updateData) ⇒ Promise.<Stream>
  • .delete(userId, streamId) ⇒ Promise.<(Stream|StreamDeletionItem)>

UserStreams.getOne(userId, query) ⇒ Promise.<(Stream|null)>

Get a stream

Kind: static method of UserStreams
Returns: Promise.<(Stream|null)> - - the stream or null if not found:

Param	Type	Default	Description
userId	identifier
query	object
query.id	identifier		'*', means root streamId. Notice parentId is not implemented by stores
[query.childrenDepth]	number	0	0 = NO; -1 = ALL; 1.. Gives the number of levels to expand
[query.excludeIds]	Array.<identifier>		list of streamIds to exclude from query. if childrenDepth is >0 or < 0, children of excludedIds should be excludded too
[query.includeTrashed]	boolean		(equivalent to state = 'all')

UserStreams.get(userId, query) ⇒ Promise.<Array.<Stream>>

Query streams

Kind: static method of UserStreams
Returns: Promise.<Array.<Stream>> - - an array of streams

Param	Type	Default	Description
userId	identifier
query	object
[query.parentId]	identifier		'*' or null, means root streamId.
[query.childrenDepth]	number	0	0 = NO; -1 = ALL; 1.. Gives the number of levels to expand
[query.excludeIds]	Array.<identifier>		list of streamIds to exclude from query. if childrenDepth is >0 or < 0, children of excludedIds should be excludded too
[query.includeTrashed]	boolean		(equivalent to state = 'all')

UserStreams.getDeletions(userId, deletionsSince) ⇒ Promise.<StreamDeletionItem>

Get a list of deleted ids since

Kind: static method of UserStreams

Param	Type
userId	identifier
deletionsSince	timestamp

UserStreams.create(userId, streamData) ⇒ Promise.<Stream>

Kind: static method of UserStreams
Returns: Promise.<Stream> - - The created Stream
Throws:

• item-already-exists (if item is deleted, id can be re-used)
• invalid-item-id
• resource-is-readonly <=== Thrown either because Storage or Parent stream is readonly

See: https://api.pryv.com/reference/#create-stream

Param	Type
userId	identifier
streamData	Stream

UserStreams.createDeleted(userId, streamData) ⇒ Promise.<Stream>

(Optional used by tests only)

Kind: static method of UserStreams
Returns: Promise.<Stream> - - The created Stream
Throws:

• resource-is-readonly <=== Thrown either because Storage or Parent stream is readonly

Param	Type
userId	identifier
streamData	Stream

UserStreams.update(userId, updateData) ⇒ Promise.<Stream>

Kind: static method of UserStreams
Returns: Promise.<Stream> - - The update Stream
Throws:

• item-already-exists
• resource-is-readonly <=== Thrown because item cannot be updated

See: https://api.pryv.com/reference/#update-stream

Param	Type
userId	identifier
updateData	Object

UserStreams.delete(userId, streamId) ⇒ Promise.<(Stream|StreamDeletionItem)>

Kind: static method of UserStreams
Returns: Promise.<(Stream|StreamDeletionItem)> - - The trashed Stream
Throws:

• resource-is-readonly <=== Thrown because item cannot be updated

See: https://api.pryv.com/reference/#delete-stream

Param	Type
userId	identifier
streamId	identifier

ErrorIds

Identifier constants for data store errors.

Kind: global constant

PryvDataStoreError

Kind: global constant
License: Copyright (C) 2021–2023 Pryv S.A. https://pryv.com - All Rights Reserved This program is free software; you can redistribute it and/or modify it under the terms of the 3-Clause BSD License SPDX-License-Identifier: BSD-3-Clause

DataStore

Kind: global constant
License: Copyright (C) 2021–2023 Pryv S.A. https://pryv.com - All Rights Reserved This program is free software; you can redistribute it and/or modify it under the terms of the 3-Clause BSD License SPDX-License-Identifier: BSD-3-Clause

errors

Kind: global constant
License: Copyright (C) 2021–2023 Pryv S.A. https://pryv.com - All Rights Reserved This program is free software; you can redistribute it and/or modify it under the terms of the 3-Clause BSD License SPDX-License-Identifier: BSD-3-Clause

errors

Kind: global constant
License: Copyright (C) 2021–2023 Pryv S.A. https://pryv.com - All Rights Reserved This program is free software; you can redistribute it and/or modify it under the terms of the 3-Clause BSD License SPDX-License-Identifier: BSD-3-Clause

PryvDataStoreError(id, message, [data], [innerError])

Constructor for data store errors.

Kind: global function

Param	Type	Default
id	string
message	string
[data]	*
[innerError]	Error

identifier : string

A string uniquely identifying an object (user, event, stream, etc.)

Kind: global typedef

timestamp : number

A positive floating-point number representing the number of seconds since a reference time (Unix epoch time).

Kind: global typedef

UserStreams : undefined

Kind: global typedef

UserEvents : undefined

Kind: global typedef

FnKeyValueGetAll ⇒ object

Kind: global typedef

Param	Type
userId	identifier

FnKeyValueGet ⇒ *

Kind: global typedef

Param	Type
userId	identifier
key	string

FnKeyValueSet ⇒ void

Kind: global typedef

Param	Type
userId	identifier
key	string
value	*

KeyValueData : object

Kind: global typedef
Properties

Name	Type	Description
getAll	FnKeyValueGetAll	Get all key-value data for the given user.
get	FnKeyValueGet	Get key-value data for the given user.
set	FnKeyValueSet	Set key-value data for the given user.

StoreInitializationParams : object

Kind: global typedef
Properties

Name	Type	Description
id	identifier	The store's id as defined in the Pryv.io platform configuration (for information)
name	string	The store's name as defined in the Pryv.io platform configuration (for information; names the root stream representing the store)
settings	object	The store's settings as defined in the Pryv.io platform configuration
storeKeyValueData	KeyValueData	Utility to save per-user data
logger	Logger	Logger for the store (messages will appear in the Pryv.io core logs)

FnLog : function

Kind: global typedef

Param	Type	Description
message	string	The log message
...context	any	Any additional contextual information

Logger

Kind: global typedef
Properties

Name	Type	Description
log	FnLog	Log message with 'info' level
warn	FnLog	Log message with 'warning' level
error	FnLog	Log message with 'error' level
debug	FnLog	Log message with 'debug' level

identifier : string

Kind: global typedef

timestamp : number

Kind: global typedef

integrity : string

Kind: global typedef

Event : object

Kind: global typedef

EventsQuery : object

Kind: global typedef
Properties

Name	Type	Description
[state]	string	The events' state: default (i.e. not trashed), trashed or all
[fromTime]	timestamp	The start time of the timeframe to retrieve events for. Default is 24 hours before toTime if the latter is set; otherwise it is not taken into account.
[toTime]	timestamp	The end time of the timeframe to retrieve events for. Default is the current time if fromTime is set.
[streams]	Array.<StreamQueryItem>	Streams query: an array of stream query items (see related documentation).
[types]	Array.<string>	If set, only events of any of the listed types will be returned.
[running]	boolean	If true, only running period events will be returned.
[modifiedSince]	timestamp	If specified, only events modified since that time will be returned.

StreamQueryItem : object

Kind: global typedef

EventDeletionItem : object

Kind: global typedef

AttachmentItem : object

Object to pass when creating events with attachments or adding attachments to events

Kind: global typedef
Properties

Name	Type	Description
filename	string	fileName
[size]	number	The size of the attachment
attachmentData	ReadableStream
[integrity]	integrity	The integrity checksum of the attachment

AttachmentResponseItem : object

Informations sent by the store after saving attachment

Kind: global typedef

Param	Type	Description
id	string	mandatory id of the attachement - unique - per event

identifier : string

Kind: global typedef

timestamp : number

// time in UNIX time (seconds)

Kind: global typedef

Stream : object

Kind: global typedef

StreamDeletionItem : object

Kind: global typedef
Properties

Name	Type
id	identifier
deleted	timestamp