Lime Web Components API Documentation - v6.27.0
    Preparing search index...

    Interface RuleRegistryBeta

    The central place primitives and rules come together.

    This package only describes the contract; the actual behavior is supplied by an implementation, reached through the platform service ruleRegistry.

    What the API does, by area:

    • Primitives. register adds a RulePrimitive; listPrimitives lists them.
    • Rule lifecycle. compile turns a Rule into a callable predicate. validate runs the same checks without throwing or producing a predicate.
    • Building a scope (convenience). scope delegates to ContextRegistry.scope so rule code does not have to thread two services. New consumers that don't compile rules should go to the context registry directly.

    Context resolution (DOM-walked providers, session-wide fallbacks, scope construction) lives on ContextRegistry. Primitives read from a ContextScope without needing to know which service built it.

    Saved rules are loaded by the host client from its own config layer at boot and live in the same id namespace as primitives. They are not registered through this interface. The registry resolves references during compile and validate but exposes no public API for managing them.

    Compiling and evaluating a rule from a web component

    const registry = platform.get(PlatformServiceName.RuleRegistry);
    const compiled = registry.compile(this.descriptor.rules.visibility);
    const visible = compiled.evaluate(registry.scope({ host: this.host }));

    Test-fixture scope

    const scope = registry.scope({
        with: { user: testUser, limeobject: testObject },
    });
    const passes = registry.compile(rule).evaluate(scope);
    interface RuleRegistry {
        attachMetadata(id: string, metadata: ConfigMetadata): void;
        compile(rule: Rule): CompiledRule;
        listMetadata?(): PrimitiveMetadata[];
        listPrimitives(): RulePrimitive<JsonValue, keyof ContextMap>[];
        register(primitive: RulePrimitive, metadata?: ConfigMetadata): void;
        scope(options?: ContextScopeOptions): ContextScope;
        subscribe(
            compiled: CompiledRule,
            scope: ContextScope,
            listener: (result: boolean) => void,
        ): () => void;
        subscribe(
            compiled: CompiledRule,
            options: ContextScopeOptions,
            listener: (result: boolean) => void,
        ): () => void;
        validate(
            rule: Rule,
            available?: (keyof ContextMap)[],
        ): RuleValidationResult;
    }
    Index

    Methods

    attachMetadata compile listMetadata? listPrimitives register scope subscribe validate

    Methods

    • Beta

      Attach display metadata to an already-registered primitive.

      Use this when the UI binding (a configComponent to author a primitive's args) is contributed by a UI layer that loads after the primitive itself is registered.

      If a field is already set, the existing value is kept and a warning is logged.

      Parameters

      • id: string

        The primitive id to attach metadata to.

      • metadata: ConfigMetadata

        The fields to attach.

      Returns void

      If no primitive with id has been registered. Throwing (rather than silently retaining orphan metadata) surfaces typos and ordering bugs at boot.

    • Beta

      Turn a Rule into a CompiledRule: an evaluate function paired with the static reads it depends on.

      Every ref is resolved against the registered primitives and saved rules. Saved rules are expanded in place and cycles are detected. Args at each leaf are not validated by the contract; primitives are responsible for handling their own args (see RulePrimitive). An implementation may surface args-mismatch issues if it has a way to introspect a primitive's args, but the contract does not require it.

      The returned CompiledRule is a snapshot: it reflects whatever was registered when compile ran, so anything compiled against an older set of saved rules is stale once those rules change. If results are cached, recompile when saved rules change. Re-running compile on a structurally-equal rule may or may not return the same CompiledRule instance, so don't rely on identity equality.

      Thrown errors inside a predicate are caught and treated as false for that node, the same outcome as a missing context key. Callers do not need to wrap evaluations in try/catch. This fail-closed behavior applies only to errors raised at evaluation time. Errors raised by RulePrimitive.build while compiling propagate out of compile, so a primitive that cannot handle its args should return a constant-false predicate from build rather than throwing.

      Parameters

      • rule: Rule

        The rule to compile.

      Returns CompiledRule

      A CompiledRule carrying evaluate and reads.

      If the rule has an unknown-ref or cycle issue, or if a RulePrimitive.build call throws. Implementations that validate args may also throw args-mismatch. args-on-saved-rule does not throw, the args are dropped and RuleRegistry.validate reports it as a diagnostic. Use RuleRegistry.validate for the non-throwing variant.

    • Beta

      List the display metadata supplied at registration.

      Optional, an implementation that doesn't track metadata can leave this method off. When present, returns one entry per registered primitive.

      Returns PrimitiveMetadata[]

      Metadata for each registered primitive.

    • Beta

      Register a RulePrimitive.

      The id must be namespaced (contain a .) and must not be in use already, neither by another primitive nor by a saved rule.

      metadata is optional and carries the display side of things: title, description, icon, tags, and a configComponent for editing the primitive's args. None of it is used at evaluation time; it shows up later via listMetadata.

      Parameters

      Returns void

      If the id is unnamespaced, already taken by another primitive, or already in use by a saved rule.

    • Beta

      Reactively evaluate a compiled rule against an already-built ContextScope — including one produced by ContextScope.extend. The push-side mirror of CompiledRule.evaluate, which already takes a scope.

      Semantics match the options-based overload: emits the current result immediately, then re-emits only when the boolean flips. It re-evaluates when any key in compiled.reads changes, except keys the scope has pinned (its with plus everything layered on by extend) — a pinned key can't affect the result, so it is never subscribed to. Dynamic keys are watched against the scope's host.

      Pinned values are captured for the life of the subscription. If a pinned value's identity changes (e.g. a row's limeobject is replaced), discard this subscription and subscribe again against a freshly-extended scope — the same lifecycle the options overload already implies for with.

      Declared before the options overload: a ContextScope also structurally satisfies ContextScopeOptions (every member of which is optional), so this more specific shape must come first to be selectable. A plain options object lacks get/extend and falls through to the overload below.

      Parameters

      • compiled: CompiledRule

        A rule compiled via compile.

      • scope: ContextScope

        The scope to evaluate against, typically host-bound and possibly extended with per-item overrides.

      • listener: (result: boolean) => void

        Called with the current result, then on change.

      Returns () => void

      A teardown that stops every underlying subscription.

    • Beta

      Reactively evaluate a compiled rule and call listener whenever the result changes.

      Emits the current result immediately, then re-emits only when the boolean flips — not on every context tick. Re-evaluates when any key in compiled.reads changes, except keys pinned by options.with (a pinned key can't affect the result). with values are captured once at subscribe time; a value that needs to change must come from a provider resolved via options.host.

      Composes ContextRegistry.subscribe, scope, and CompiledRule.reads; no new context machinery.

      Parameters

      • compiled: CompiledRule

        A rule compiled via compile.

      • options: ContextScopeOptions

        Scope construction options (host and/or with), the same shape scope takes.

      • listener: (result: boolean) => void

        Called with the current result, then on change.

      Returns () => void

      A teardown that stops every underlying subscription.

    • Beta

      Same checks as compile, but returns structured diagnostics instead of throwing, and no predicate is produced.

      available is a hint from the caller, not something the registry can verify: the registry doesn't know which context keys will be supplied at evaluation time, only the caller building the scope does. Pass it when known; otherwise the runtime fallback (missing keys produce false) catches the gap.

      Parameters

      • rule: Rule

        The rule to validate.

      • Optionalavailable: (keyof ContextMap)[]

        Optional list of context keys the caller knows will be available where the rule runs. Used to surface missing-slot issues at save time.

      Returns RuleValidationResult

      ok: true when the rule passes every check; otherwise ok: false with a list of issues.

    Settings

    Member Visibility

    On This Page

    Methods