lib/observable

Angular-like reactive observable system for FiveM.

This module provides a comprehensive observable system for managing state across client and server boundaries in FiveM.

Observable Types

Type	Owner	Sync Direction	Use Case
serverOnly	Server	None	Server-internal state
clientOnly	Client	None	Client-internal state
webOwned	Web	Client/Server → Web	UI-specific state
serverOwned	Server	Server → Clients	Authoritative server state
clientOwned	Client	Client → Server	Client-authoritative state
shared	Both	Bidirectional	Collaborative state

Player Subscriptions

By default, players must be manually subscribed to observables. Set broadcast: true in options to auto-subscribe all players.

Inter-Observable Subscription

Observables can subscribe to each other for synchronization:

const health = serverOwned({ id: "health", initialValue: 100 });
const display = serverOwned({ id: "healthDisplay", initialValue: "100%" });
 
// display updates when health changes
display.pipe(health, (h) => `${h}%`);

Classes

Class	Description
ComputedObservable	Computed observable that derives its value from other observables. Read-only - value is computed from sources.
Observable	Base Observable class for local-only reactivity.
ReadonlyObservableWrapper	Read-only wrapper around an observable. Hides mutation methods while allowing subscription.

Interfaces

Interface	Description
ClientOwnedObservable	Client-owned observable interface. Client has R/W, server has RO.
ObservableOptions	Options for creating an observable.
ReadonlyObservable	Read-only observable interface. Provides access to current value and subscription capability.
ServerOwnedObservable	Server-owned observable interface. Server has R/W, clients have RO.
SharedObservable	Shared observable interface. Both client and server have R/W with conflict resolution.
SharedObservableOptions	Options for shared observables with conflict resolution.
Subscription	Subscription to an observable, can be disposed to unsubscribe.
SyncedObservableOptions	Options for synchronized observables (serverOwned, clientOwned, shared).
WebOwnedObservable	Web-owned observable interface. Full read/write access on web, accessible via @Web methods from client/server.
WebOwnedObservableOptions	Options for creating a web-owned observable.
WritableObservable	Writable observable interface. Extends read-only with mutation capabilities.

Type Aliases

Type Alias	Description
ConflictResolver	Custom conflict resolution function.
ObservableOwnership	Observable ownership type.
PlayerId	Player ID type for subscription tracking. This is the FiveM server ID (number).
SubscriptionCallback	Callback function invoked when observable value changes.

Functions

Function	Description
addPlayerSubscription	Subscribe a player to an observable.
clearAllPlayerSubscriptions	Clear all player subscriptions. Used during resource teardown.
clearPlayerSubscriptions	Clear all player subscriptions for an observable.
clearRegistry	Clear all registered observables. Used during resource teardown.
clearWebNotifier	Clear the web notifier callback. Call this during client shutdown.
clientOnly	Create a client-only observable. Only available on client runtime.
clientOwned	Create a client-owned observable. Client has R/W, server has RO. Works on both server and client (server gets per-player read-only view).
computed	Create a computed observable that derives its value from other observables.
createClientOwnedClient	Create a client-owned observable. Client has R/W, server has RO. Works on both server and client (server gets per-player read-only view).
createClientOwnedServer	Create a client-owned observable. Client has R/W, server has RO. Works on both server and client (server gets per-player read-only view).
createClientOwnedWeb	Create a client-owned observable. Client has R/W, server has RO. Works on both server and client (server gets per-player read-only view).
createObservable	Create a basic observable with local-only reactivity.
createServerOwnedClient	Create a server-owned observable. Server has R/W, clients have RO. Works on both server and client (client gets read-only view).
createServerOwnedServer	Create a server-owned observable. Server has R/W, clients have RO. Works on both server and client (client gets read-only view).
createServerOwnedWeb	Create a server-owned observable. Server has R/W, clients have RO. Works on both server and client (client gets read-only view).
createSharedClient	Create a shared observable. Both client and server have R/W with conflict resolution.
createSharedServer	Create a shared observable. Both client and server have R/W with conflict resolution.
createSharedWeb	Create a shared observable. Both client and server have R/W with conflict resolution.
createWebOwnedClient	Create a web-owned observable. Web has R/W, client/server can update via @Web methods. Used for UI-specific state.
createWebOwnedServer	Create a web-owned observable. Web has R/W, client/server can update via @Web methods. Used for UI-specific state.
createWebOwnedWeb	Create a web-owned observable. Web has R/W, client/server can update via @Web methods. Used for UI-specific state.
getAllObservables	Get all registered observables.
getObservable	Get an observable by ID.
getObservableEntry	Get a registry entry by ID.
getObservableIds	Get all registered observable IDs.
getSubscribedPlayers	Get the set of subscribed players for an observable.
hasObservable	Check if an observable is registered.
initObservableLifecycle	Initialize observable lifecycle hooks.
initWebSync	Initialize web sync system on client. Call this during client bootstrap.
isPlayerSubscribed	Check if a player is subscribed to an observable.
notifyWebOfChange	Notify web of an observable value change. No-op if no notifier is registered (non-client runtimes).
registerObservable	Register an observable in the global registry.
removePlayerFromAllSubscriptions	Remove a player from all observable subscriptions. Call this when a player disconnects.
removePlayerSubscription	Remove a player subscription from an observable.
serverOnly	Create a server-only observable. Only available on server runtime.
serverOwned	Create a server-owned observable. Server has R/W, clients have RO. Works on both server and client (client gets read-only view).
setWebNotifier	Register a web notifier callback. Call this from client runtime to enable web notifications.
shallowEquals	Shallow equality function for plain objects. Compares object properties at one level deep. Falls back to strict equality for primitives and non-plain objects.
shared	Create a shared observable. Both client and server have R/W with conflict resolution.
shutdownObservableLifecycle	Shutdown observable lifecycle management. Call this during server teardown.
shutdownWebSync	Shutdown web sync system.
strictEquals	Strict equality function. Use this for primitives or when you want reference equality.
unregisterObservable	Unregister an observable from the global registry.
webOwned	Create a web-owned observable. Web has R/W, client/server can update via @Web methods. Used for UI-specific state.

References

deepEquals

Re-exports deepEquals