✨ Inspectable attributes

[cowboyd]

Motivation

Effection currently lack a standardized way to attach metadata for debugging and visualization purposes. We need a way to attach metadata to a scope so that it can be consumed by downstream tooling such as OTEL or the Effection Inspector.

Approach

This change introduces two new APIs:

• useAttributes() - An operation that adds serializable metadata (name/value pairs) to the current scope. This is api is meant to be used to annotate Effection scopes from user-land code. Accessible from the main module export.
• getAttributes() - A function to retrieve a scope attributes. This api is not really designed to be called from user-land, but will be called from tooling that needs to read attributes from a scope. This api is only available via the effection/exmperimental module.

Each scope maintains its own attributes. They are not inherited from parent scopes. This makes sense when we think that these attributes are there to present information that is unique to the current scope.p

Multiple calls to useAttributes within the same scope merge attributes rather than replacing them, allowing progressive enhancement of scope metadata.

Example Usage

function useServer(port: number): Operation<Server> {
  return resource(function*(provide) {
    yield* useAttributes({ name: "Server", port });
    let server = createServer();
    server.listen();
    try {
      yield* provide(server);
    } finally {
      server.close();
    }
  });
}

Note: this api is called useLabels() in the current @effectionx/inspector branch.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/thefrontside/effection@1098

commit: 6ff6140