API reference > @kontsedal/olas-entities

olas-entities package

Functions

Function	Description
defineEntity(opts)	Declare an entity type. name MUST be unique within a plugin instance; the plugin uses it as the partition key in the normalized store and the reverse index. idOf is a type-narrowing predicate masquerading as a partial function: return the id when the value matches this entity's shape, null (or undefined) when it doesn't. Idiom: include a discriminating field check inside idOf so unrelated objects with an id field don't get falsely classified.
entitiesPlugin(options)	Build the entity-normalization plugin: createRoot(App, { deps, queries: queryEngine(), plugins: [entitiesPlugin({ entities: [Post, User] })], }) // in a controller const entities = ctx.inject(Entities) entities.update(Post, 'p1', { liked: true }) Lifecycle: - On every cache write, the plugin walks the written data and finds every subtree value that a registered entity claims via idOf. It updates both the normalized store and the reverse index (entity-id → bindings). - On update, it reads the reverse index for the entity and writes the patch into every binding with host.queries.write, inside one batch so subscribers see one round of notifications. - Regular and infinite queries are both observed. The store is per root: each root the plugin is installed in gets its own.

Variables

Variable	Description
ENTITIES_PLUGIN_NAME	The plugin's name — and the origin stamped on its backprop writes.
Entities	The scope entitiesPlugin provides its store under. Resolve it withctx.inject(Entities) in a controller or root.inject(Entities) outside one. In a test, seed a fake with RootOptions.scopes.

Type Aliases

Type Alias	Description
EntitiesOptions	Options for entitiesPlugin(...).
EntityBinding	Public, frozen view of a binding — for entities.bindings(...) devtools.
EntityDef	Module-scoped descriptor for an entity type. Define one per entity class (Post, User, Comment), then pass the resulting handles toentitiesPlugin({ entities: [...] }). idOf extracts a string id from a value if it IS an entity of this type, or returns null / undefined if it isn't. The plugin uses idOf both to walk query results (testing every reachable subtree value) and to look up entities in the store. Falsy returns are treated as "not an entity." The phantom type slot lets entities.signal(Post, id) returnReadSignal<Post | undefined> rather than a type-erased unknown.
EntityOptions	What defineEntity takes.
EntityStore	One root's normalized entity store — the service entitiesPlugin provides. Reach it through the Entities scope: ctx.inject(Entities) in a controller, root.inject(Entities) outside one. Per-entity ops are typed by the EntityDef<T> you pass in — signal(Post, id) returns ReadSignal<Post | undefined>, not ReadSignal<unknown>.