Skip to main content

SyncService

@webda/offline

Class: SyncService

Defined in: packages/offline/src/server/sync.service.ts:132

Webda Modda​

SyncService

Offline sync of models: maintains the _rev of the configured models, records every write in the SyncChange log and exposes Sync.Pull, Sync.Snapshot, Sync.Push and Sync.Watch.

Extends​

Constructors​

Constructor​

new SyncService(name, params): SyncService

Defined in: packages/core/lib/services/service.d.ts:72

Service

Parameters​

name​

string

The name of the service

params​

SyncServiceParameters

The parameters block define in the configuration file

Returns​

SyncService

Inherited from​

Service<SyncServiceParameters>.constructor

Properties​

_compiledCapabilities​

protected _compiledCapabilities: Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:38

Capabilities detected at compile-time from @WebdaCapability-tagged interfaces.

Populated during Service.resolve by reading the service's entry in webda.module.json. Each key is a capability name (e.g., "request-filter"), and the value is an empty object {} by default. Override getCapabilities to provide capability-specific configuration or to conditionally disable capabilities.

See​

getCapabilities

Inherited from​

Service._compiledCapabilities

[WEBDA_EVENTS]​

[WEBDA_EVENTS]: object

Defined in: packages/core/lib/services/service.d.ts:50

Set the Webda events here

Inherited from​

Service.[WEBDA_EVENTS]

bulkWarned​

protected bulkWarned: Set<string>

Defined in: packages/offline/src/server/sync.service.ts:166

Models already warned about bulk operations

changes​

protected changes: EventEmitter<any>

Defined in: packages/offline/src/server/sync.service.ts:136

Emits "change" ({ model, key, seq }) when an entry is appended

counter​

protected counter: number = 0

Defined in: packages/offline/src/server/sync.service.ts:154

instanceId​

protected instanceId: string

Defined in: packages/offline/src/server/sync.service.ts:152

Instance id used in seq

lastMs​

protected lastMs: number = 0

Defined in: packages/offline/src/server/sync.service.ts:153

logger​

protected logger: Logger

Defined in: packages/core/lib/services/service.d.ts:59

Logger with class context

Inherited from​

Service.logger

metrics?​

protected optional metrics?: object

Defined in: packages/core/lib/services/service.d.ts:63

Get metrics

Inherited from​

Service.metrics

name​

readonly name: string

Defined in: packages/core/lib/services/iservice.d.ts:18

Inherited from​

Service.name

ownBumps​

protected ownBumps: WeakSet<object>

Defined in: packages/offline/src/server/sync.service.ts:144

_rev increments the service issued itself (not logged again)

parameters​

readonly parameters: SyncServiceParameters

Defined in: packages/core/lib/services/iservice.d.ts:19

Inherited from​

Service.parameters

pruneTimer?​

protected optional pruneTimer?: Timeout

Defined in: packages/offline/src/server/sync.service.ts:158

Hourly retention pruning

pushContext​

protected pushContext: AsyncLocalStorage<{ id: string; mutationId: string; }>

Defined in: packages/offline/src/server/sync.service.ts:148

The Sync.Push write in progress: only the events it raises carry its mutationId

revved​

protected revved: WeakSet<object>

Defined in: packages/offline/src/server/sync.service.ts:140

Write payloads whose _rev was already set by the service

unsubscribers​

protected unsubscribers: (() => void)[] = []

Defined in: packages/offline/src/server/sync.service.ts:162

Remove the repository listeners

Returns​

void

createConfiguration?​

static optional createConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:23

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.createConfiguration

filterConfiguration?​

static optional filterConfiguration?: (params) => any

Defined in: packages/core/lib/services/iservice.d.ts:27

Create configuration set by the application on load

Parameters​

params​

any

Returns​

any

Inherited from​

Service.filterConfiguration

Parameters​

static Parameters: typeof ServiceParameters

Defined in: packages/core/lib/services/service.d.ts:46

Service parameters

Inherited from​

Service.Parameters

Methods​

__clean()​

abstract __clean(): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:215

Clean the service data, can only be used in test mode

Returns​

Promise<void>

Inherited from​

Service.__clean

addListener()​

addListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:80

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void | Promise<void>

the event listener

Returns​

this

this for chaining

See​

EventEmitter.addListener

Inherited from​

Service.addListener

addRoute()​

protected addRoute(url, methods, executer, openapi?, override?): void

Defined in: packages/core/lib/services/service.d.ts:177

Add a route dynamicaly

Parameters​

url​

string

of the route can contains dynamic part like {uuid}

methods​

HttpMethodType[]

the HTTP methods

executer​

Function

Method to execute for this route

openapi?​

OpenAPIWebdaDefinition

the OpenAPI specification

override?​

boolean

whether to override existing

Returns​

void

Inherited from​

Service.addRoute

append()​

protected append(modelId, key, op, rev?): Promise<void>

Defined in: packages/offline/src/server/sync.service.ts:272

Append a change-log entry and notify the watchers

Parameters​

modelId​

string

the model identifier

key​

string

the canonical key

op​

"upsert" | "delete"

the kind of write

rev?​

number

the revision after the write, when known

Returns​

Promise<void>

applyMutation()​

protected applyMutation(m): Promise<MutationResult>

Defined in: packages/offline/src/server/sync.service.ts:653

Apply one mutation

Parameters​

m​

Mutation

the mutation

Returns​

Promise<MutationResult>

its result

authorizeClientEvent()​

authorizeClientEvent(_event, _context): boolean

Defined in: packages/core/lib/services/service.d.ts:153

Authorize a public event subscription

Parameters​

_event​

string

the event name

_context​

OperationContext

the execution context

Returns​

boolean

true if the condition is met

Inherited from​

Service.authorizeClientEvent

canRead()​

protected canRead(object, modelId): Promise<boolean>

Defined in: packages/offline/src/server/sync.service.ts:440

Parameters​

object​

any

the object

modelId​

string

the model it is reached through

Returns​

Promise<boolean>

true when the current caller may read it

computeParameters()​

computeParameters(): void

Defined in: packages/core/lib/services/service.d.ts:77

Used to compute or derivate input parameter to attribute

Returns​

void

Deprecated​

Inherited from​

Service.computeParameters

conflict()​

protected conflict(mutationId, modelId, object?): MutationResult

Defined in: packages/offline/src/server/sync.service.ts:595

Parameters​

mutationId​

string

the mutation

modelId​

string

the model

object?​

any

the current server object, undefined when deleted

Returns​

MutationResult

a conflict result

emit()​

emit<Key>(event, data): Promise<void>

Defined in: packages/core/lib/services/service.d.ts:204

Emit the event with data and wait for Promise to finish if listener returned a Promise

Type Parameters​

Key​

Key extends never

Parameters​

event​

Key

the event name

data​

object[Key]

the data to process

Returns​

Promise<void>

Inherited from​

Service.emit

getCapabilities()​

getCapabilities(): Record<string, any>

Defined in: packages/core/lib/services/iservice.d.ts:60

Return the capabilities of this service.

By default returns capabilities detected at compile-time from

Returns​

Record<string, any>

the result

Webda Capability-tagged​

interfaces in webda.module.json.

Override to disable capabilities based on configuration:

getCapabilities() {
  const caps = super.getCapabilities();
  if (!this.parameters.enabled) delete caps["request-filter"];
  return caps;
}

Inherited from​

Service.getCapabilities

getClientEvents()​

getClientEvents(): string[]

Defined in: packages/core/lib/services/service.d.ts:144

Return the events that an external system can subscribe to

Returns​

string[]

the list of results

Inherited from​

Service.getClientEvents

getMaxListeners()​

getMaxListeners(): number

Defined in: packages/core/lib/events/asynceventemitter.d.ts:84

Returns​

number

Inherited from​

Service.getMaxListeners

getMetric()​

getMetric<T>(type, configuration): T

Defined in: packages/core/lib/services/service.d.ts:138

Add service name label

Type Parameters​

T​

T = Gauge<string> | Counter<string> | Histogram<string>

Parameters​

type​

CustomConstructor<T, [MetricConfiguration<T>]>

the type to look up

configuration​

MetricConfiguration<T>

the configuration

Returns​

T

the result

Inherited from​

Service.getMetric

getName()​

getName(): string

Defined in: packages/core/lib/services/service.d.ts:209

Get service name

Returns​

string

the result string

Inherited from​

Service.getName

getOpenApiReplacements()​

getOpenApiReplacements(): any

Defined in: packages/core/lib/services/service.d.ts:182

Return variables for replacement in openapi

Returns​

any

the result

Inherited from​

Service.getOpenApiReplacements

getOperationId()​

getOperationId(id): string | undefined

Defined in: packages/core/lib/services/service.d.ts:167

If undefined is returned it cancel the operation registration

Parameters​

id​

string

the identifier

Returns​

string | undefined

the result

Inherited from​

Service.getOperationId

getParameters()​

getParameters(): SyncServiceParameters

Defined in: packages/core/lib/services/service.d.ts:82

Get the service parameters

Returns​

SyncServiceParameters

the result

Inherited from​

Service.getParameters

getService()​

getService<T>(name): ServicesMap[T]

Defined in: packages/core/lib/services/service.d.ts:131

Get a service by name

Type Parameters​

T​

T extends keyof ServicesMap

Parameters​

name​

T

the name to use

Returns​

ServicesMap[T]

the result map

Deprecated​

Use useService, might reconsider

Inherited from​

Service.getService

getState()​

getState(): ServiceStates

Defined in: packages/core/lib/services/service.d.ts:55

Get the current state

Returns​

ServiceStates

the result

Inherited from​

Service.getState

getUrl()​

getUrl(url, _methods): string

Defined in: packages/core/lib/services/service.d.ts:161

Return the full path url based on parameters

Parameters​

url​

string

relative url to service

_methods​

HttpMethodType[]

in case we need filtering (like Store)

Returns​

string

absolute url or undefined if need to skip the Route

Inherited from​

Service.getUrl

guardedConflict()​

protected guardedConflict(mutationId, modelId, object?): Promise<MutationResult>

Defined in: packages/offline/src/server/sync.service.ts:616

A conflict that never carries an object the caller cannot read

Parameters​

mutationId​

string

the mutation

modelId​

string

the model

object?​

any

the current server object, undefined when deleted

Returns​

Promise<MutationResult>

the conflict, or a NOT_FOUND rejection

hidden()​

protected hidden(mutationId): MutationResult

Defined in: packages/offline/src/server/sync.service.ts:605

Parameters​

mutationId​

string

the mutation

Returns​

MutationResult

the result for an object the caller cannot read: indistinguishable from a missing one

hook()​

protected hook(modelId, model): void

Defined in: packages/offline/src/server/sync.service.ts:315

Maintain _rev and log every write of a synced model

Parameters​

modelId​

string

the model identifier

model​

any

the model class

Returns​

void

horizon()​

protected horizon(): string

Defined in: packages/offline/src/server/sync.service.ts:388

Cursors below this seq may have missed pruned entries: computed from the clock, so every instance agrees whichever of them pruned

Returns​

string

the retention horizon

init()​

init(): Promise<SyncService>

Defined in: packages/offline/src/server/sync.service.ts:172

Check the configured models, then hook their repositories

Returns​

Promise<SyncService>

this

Overrides​

Service.init

initMetrics()​

initMetrics(): void

Defined in: packages/core/lib/services/service.d.ts:124

Init the metrics

Returns​

void

Inherited from​

Service.initMetrics

initOperations()​

initOperations(): void

Defined in: packages/core/lib/services/service.d.ts:186

Init the operations from

Returns​

void

Operation​

decorators on this service

Inherited from​

Service.initOperations

invalid()​

protected invalid(modelId, candidate): string | undefined

Defined in: packages/offline/src/server/sync.service.ts:639

Validate a candidate object against the model schema

Parameters​

modelId​

string

the model

candidate​

any

the full object

Returns​

string | undefined

undefined when valid, the error message otherwise

keyInUse()​

protected keyInUse(mutationId, modelId, existing): Promise<MutationResult>

Defined in: packages/offline/src/server/sync.service.ts:627

Parameters​

mutationId​

string

the mutation

modelId​

string

the model

existing​

any

the object already stored under the key

Returns​

Promise<MutationResult>

a conflict when readable, KEY_IN_USE otherwise (no content)

listeners()​

listeners(eventName): Function[]

Defined in: packages/core/lib/events/asynceventemitter.d.ts:139

Get all listeners for an event

Parameters​

eventName​

never

the event name

Returns​

Function[]

the list of results

Inherited from​

Service.listeners

load()​

protected load(modelId, key): Promise<any>

Defined in: packages/offline/src/server/sync.service.ts:240

Load an object by canonical key

Parameters​

modelId​

string

the model identifier

key​

string

the canonical key

Returns​

Promise<any>

the object, undefined when missing

loadCapabilities()​

protected loadCapabilities(): void

Defined in: packages/core/lib/services/service.d.ts:120

Load capabilities from webda.module.json metadata into _compiledCapabilities.

Called during resolve after dependency injection. Reads the service's type name from parameters, looks it up in the application's module metadata (moddas or beans section), and populates _compiledCapabilities with an empty object for each declared capability name.

Fails silently if the application is not available (e.g., in unit tests where services are instantiated without a full application context).

Returns​

void

Example​

// If webda.module.json contains:
// { "moddas": { "MyApp/HawkService": { "capabilities": ["request-filter", "cors-filter"] } } }
// Then after resolve(), this.getCapabilities() returns:
// { "request-filter": {}, "cors-filter": {} }

See​

getCapabilities

Inherited from​

Service.loadCapabilities

log()​

log(level, ...args): void

Defined in: packages/core/lib/services/service.d.ts:226

Parameters​

level​

WorkerLogLevel

to log

args​

...any[]

additional arguments

Returns​

void

Inherited from​

Service.log

nextSeq()​

nextSeq(): string

Defined in: packages/offline/src/server/sync.service.ts:215

Returns​

string

a seq greater than every seq this process generated before

off()​

off<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:116

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.off

Inherited from​

Service.off

on()​

on<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:102

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.on

once()​

once<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:95

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.once

Inherited from​

Service.once

pkFields()​

protected pkFields(modelId): string[]

Defined in: packages/offline/src/server/sync.service.ts:230

Parameters​

modelId​

string

the model identifier

Returns​

string[]

its primary key fields

prune()​

protected prune(): Promise<void>

Defined in: packages/offline/src/server/sync.service.ts:395

Delete the entries older than the retention

Returns​

Promise<void>

pull()​

pull(scopes, cursor?, limit?): Promise<PullResponse>

Defined in: packages/offline/src/server/sync.service.ts:479

Changes of the scoped objects since cursor

Parameters​

scopes​

SyncScope[]

the sync scopes

cursor?​

string

the cursor of the previous pull, absent for the first one

limit?​

number

page size (capped by pageSize)

Returns​

Promise<PullResponse>

the page of changes

push()​

push(mutations): Promise<PushResponse>

Defined in: packages/offline/src/server/sync.service.ts:565

Apply client mutations, each on its own, in order

Parameters​

mutations​

Mutation[]

the mutations

Returns​

Promise<PushResponse>

one result per mutation

rejected()​

protected rejected(mutationId, code, message): MutationResult

Defined in: packages/offline/src/server/sync.service.ts:585

Parameters​

mutationId​

string

the mutation

code​

string

error code

message​

string

error message

Returns​

MutationResult

a rejected result

removeAllListeners()​

removeAllListeners<Key>(eventName?): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:122

Type Parameters​

Key​

Key extends never

Parameters​

eventName?​

Key

the event name

Returns​

this

this for chaining

See​

EventEmitter.removeAllListeners

Inherited from​

Service.removeAllListeners

removeListener()​

removeListener<Key>(eventName, listener): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:109

Type Parameters​

Key​

Key extends never

Parameters​

eventName​

Key

the event name

listener​

(event) => void

the event listener

Returns​

this

this for chaining

See​

EventEmitter.removeListener

Inherited from​

Service.removeListener

resolve()​

resolve(): this

Defined in: packages/core/lib/services/service.d.ts:98

Resolve parameters and load metadata. @Route-declared routes are scanned and registered by Router.discoverRoutes(services) from Core.init() once every service has resolved — nothing to do per-service here.

Returns​

this

the result

Inherited from​

Service.resolve

safely()​

protected safely(modelId, key, step): Promise<void>

Defined in: packages/offline/src/server/sync.service.ts:295

Run an after-event step without ever throwing into the caller's committed write

Parameters​

modelId​

string

the model identifier

key​

string | undefined

the canonical key

step​

(key) => Promise<void>

the step to run

Returns​

Promise<void>

seqAt()​

seqAt(ms): string

Defined in: packages/offline/src/server/sync.service.ts:208

Parameters​

ms​

number

epoch milliseconds

Returns​

string

the smallest seq of that millisecond

setMaxListeners()​

setMaxListeners(n): this

Defined in: packages/core/lib/events/asynceventemitter.d.ts:88

Parameters​

n​

number

Returns​

this

Inherited from​

Service.setMaxListeners

snapshot()​

snapshot(scope, continuationToken?): Promise<SnapshotResponse>

Defined in: packages/offline/src/server/sync.service.ts:536

Every object of a scope, paged: used by clients to resync

Parameters​

scope​

SyncScope

the scope

continuationToken?​

string

token of the previous page

Returns​

Promise<SnapshotResponse>

the page of objects

stop()​

stop(): Promise<void>

Defined in: packages/offline/src/server/sync.service.ts:197

Returns​

Promise<void>

nothing

Overrides​

Service.stop

toJSON()​

toJSON(): string

Defined in: packages/core/lib/services/service.d.ts:191

Prevent service to be serialized

Returns​

string

the result

Inherited from​

Service.toJSON

toString()​

toString(): string

Defined in: packages/core/lib/services/service.d.ts:91

Return service representation

Returns​

string

the result

Inherited from​

Service.toString

toSynced()​

protected toSynced(modelId, object): SyncedObject

Defined in: packages/offline/src/server/sync.service.ts:454

Parameters​

modelId​

string

the model identifier

object​

any

the object

Returns​

SyncedObject

the object as sent to clients

touch()​

touch(modelId, keys): Promise<void>

Defined in: packages/offline/src/server/sync.service.ts:255

Log writes the repository events cannot see (bulk updateMany/deleteMany)

Parameters​

modelId​

string

the model identifier

keys​

unknown[]

primary keys (scalars or key objects)

Returns​

Promise<void>

validateScopes()​

protected validateScopes(scopes): object[]

Defined in: packages/offline/src/server/sync.service.ts:404

Validate client scopes

Parameters​

scopes​

SyncScope[]

the scopes

Returns​

object[]

the scopes with their compiled filter

watch()​

watch(scopes, _cursor?): AsyncGenerator<WatchEvent>

Defined in: packages/offline/src/server/sync.service.ts:776

Stream of hints telling the client to pull: only a cursor, never object data

Parameters​

scopes​

SyncScope[]

the sync scopes

_cursor?​

string

the client cursor (reserved)

Returns​

AsyncGenerator<WatchEvent>

the hints