Function useResource

useResource<S extends Lazy<ResourceShape>, T extends Model<S, T>>(
    options: { entry: string; shape: S; model: T },
): Relay<
    {
        blank: void;
        ready: {
            state: Match<S, T>;
            update(state: Draft<S>): Promise<string>;
            delete(): Promise<string>;
        };
        error: { state: Problem; reload(): Promise<void> };
    },
>
Binds a component to a resource held by the shared store.

Retrieves the resource from the store offered by the innermost enclosing Store context and keeps the component in step with it, so that a view renders what the store holds and writes changes back without driving exchanges of its own: the resource is retrieved again whenever the store signals a change to it, whoever made it.

A missing resource, a rejected write and a failed exchange alike move the binding to its error state, so that a view shows them where it shows the resource and offers to retry from there; an operation the view called also rejects with the same Problem, so that the view waiting on it can tell success from failure. A failed exchange no view called for, retrieving the resource as the component renders or after the store signals a change, is reported through the binding alone and never reaches the page: only a missing Store context or an unforeseen failure does, for an enclosing Faults context to take up.

The template may be fixed or replaced at runtime, and a different one has the resource retrieved again:
- a fixed template, declared in code, types the resource exactly with the values it asks for
- a runtime template, built as the interface runs, for instance as a user picks the values to show, types the resource only as loosely as the template itself is typed, so a view reads the values it holds by inspecting it
Caution
A template is told apart by identity, not content: declare a fixed template once, outside the component, and hold a runtime one in state of the component's own. A template written inline at the call site is a new object on every render, and has the resource retrieved again, and the component rendered again, on every render.
Type Parameters
- S extends Lazy<ResourceShape>
  The shape describing the resource
- T extends Model<S, T>
  The template stating which values of the resource are wanted
Parameters
- options: { entry: string; shape: S; model: T }
  The resource to be bound, the shape describing it and the values wanted; read as the component first renders and whenever the store, the resource identifier or the template change, so a view is expected to keep the shape stable for the lifetime of the component
  - Readonlyentry: string
    
    The identifier of the resource, either absolute or relative to the current location.
  - Readonlyshape: S
    
    The shape the retrieved resource is validated against, possibly deferred to break definition cycles.
  - Readonlymodel: T
    
    The template stating which values of the resource are retrieved, and nothing wider.
    
    Warning
    Templates are compared by reference: any new object, even with the same content, retrieves the resource again. A template written inline, as in useResource({ …, model: { name: {} } }), is a new object on every render, and retrieves the resource on every render: declare it as a constant instead, or keep it in state if it changes at runtime.
Returns Relay<
    {
        blank: void;
        ready: {
            state: Match<S, T>;
            update(state: Draft<S>): Promise<string>;
            delete(): Promise<string>;
        };
        error: { state: Problem; reload(): Promise<void> };
    },
>
A Relay over the state of the binding, to be matched by a view with a handler for each: blank until the resource is first retrieved, ready with the resource and the operations writing it back to the store, or error with the Problem that prevented either; a state is kept until the next one supersedes it, including while the resource is retrieved again after a change, under a new identifier or on reload

Throws
Error If called outside any Store context

Throws
RangeError If entry is invalid, or relative while the location is not hierarchical
- Defined in packages/tile-data/src/store.ts:144

Function useResource

Type Parameters

Parameters

`Readonly`entry: string

`Readonly`shape: S

`Readonly`model: T

Returns Relay<
    {
        blank: void;
        ready: {
            state: Match<S, T>;
            update(state: Draft<S>): Promise<string>;
            delete(): Promise<string>;
        };
        error: { state: Problem; reload(): Promise<void> };
    },
>

Throws

Throws

Settings

Function useResource

Type Parameters

Parameters

Readonlyentry: string

Readonlyshape: S

Readonlymodel: T

Returns Relay< { blank: void; ready: { state: Match<S, T>; update(state: Draft<S>): Promise<string>; delete(): Promise<string>; }; error: { state: Problem; reload(): Promise<void> }; },>

Throws

Throws

Settings

`Readonly`entry: string

`Readonly`shape: S

`Readonly`model: T

Returns Relay<
{
blank: void;
ready: {
state: Match<S, T>;
update(state: Draft<S>): Promise<string>;
delete(): Promise<string>;
};
error: { state: Problem; reload(): Promise<void> };
},
>