@metreeca/tile
    Preparing search index...

    Function useCollection

    • Binds a component to a collection held by the shared store.

      Retrieves the items a multi-valued property of a resource collects from the store offered by the innermost enclosing Store context and keeps the component in step with them, so that a view lists what the store holds and adds items without driving exchanges of its own: the collection is retrieved again whenever the store signals a change to the resource holding it, whoever made it.

      A missing resource, a rejected creation and a failed exchange alike move the binding to its error state, as for useResource; an operation the view called also rejects with the same Problem, while a failed exchange no view called for is reported through the binding alone.

      The model is typed and held stable as for useResource, and may likewise be fixed or replaced at runtime.

      Type Parameters

      • S extends Lazy<ResourceShape>

        The shape describing the resource holding the collection

      • T extends
            | Model<S, T>
            | Template & Entries<S, T>
            | Template & Entries<S, T> & {
                readonly [F in string | number | symbol]: F extends Repeated<S>
                    ? Collecting<S, F, T[F]>
                    : never
            }

        The model naming the property collecting the items and stating which values of each item are wanted

      Parameters

      • options: { entry: string; shape: S; model: T }

        The resource holding the collection, the shape describing it and the model addressing the collection; read as the component first renders and whenever the store, the resource identifier or the model change

        • Readonlyentry: string

          The identifier of the resource holding the collection, either absolute or relative to the current location.

        • Readonlyshape: S

          The shape describing the resource holding the collection, possibly deferred to break definition cycles.

        • Readonlymodel: T

          The model naming the multi-valued property collecting the items and stating, under that name, the template or projection narrowing each item to the values retrieved, and nothing wider: { members: { name: {} } } lists the names of the items the members property collects.

          Warning

          Models are compared by reference: any new object, even with the same content, retrieves the collection again. A model written inline, as in useCollection({ …, model: { members: { name: {} } } }), is a new object on every render, and retrieves the collection 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: Items<S, T>; create(state: Draft<S, T>): 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 collection is first retrieved, ready with the items and the operation adding one, or error with the Problem that prevented either; a state is kept until the next one supersedes it, including while the collection is retrieved again after a change or on reload

      Error If called outside any Store context

      RangeError If entry is invalid, or relative while the location is not hierarchical

    Settings
    Member Visibility