@owlmeans/client 0.1.18-rc.12 → 0.1.18-rc.13

package/src/store.ts

@@ -1,73 +1,84 @@
-import { useEffect, useId, useMemo, useState } from 'react'
-import type { StateModel, UseStoreHelper, UseStoreHelperOptions, UseStoreListHelper } from '@owlmeans/state'
-import { useContext } from './context.js'
+import { useMemo, useSyncExternalStore } from 'react'
 import type { ResourceRecord } from '@owlmeans/resource'
+import type { StateModel } from '@owlmeans/state'
+import { useContext } from './context.js'
+import type { UseStoreListOptions } from './types.js'
 
-export const useStoreModel: UseStoreHelper = (id, opts) => {
-  const list = useStoreList(id, opts)
+/**
+ * Turn one state subscription into the pair `useSyncExternalStore` wants.
+ *
+ * The value is cached rather than rebuilt per render: the hook is asked for a snapshot on every
+ * render and must answer with the same reference until something actually changed, or React
+ * re-renders forever. A state subscription hands its value over synchronously, so the first
+ * snapshot is taken by subscribing and unsubscribing again — no render ever runs without one,
+ * and no subscription outlives the call.
+ */
+const bind = <V>(subscribe: (listener: (value: V) => void) => () => void) => {
+  let current: V | undefined
+  let seeded = false
 
-  if (list.length < 1) {
-    throw new SyntaxError('Store always return model and create it if not exists')
+  const capture = (notify?: () => void) => (value: V) => {
+    current = value
+    seeded = true
+    notify?.()
   }
 
-  return list[0]
-}
+  return {
+    subscribe: (notify: () => void) => subscribe(capture(notify)),
+    snapshot: (): V => {
+      if (!seeded) {
+        subscribe(capture())()
+      }
 
-export const useStoreList: UseStoreListHelper = (ids, opts) => {
-  if (typeof ids === 'object' && !Array.isArray(ids)) {
-    opts = ids
-  }
-  const params: UseStoreHelperOptions<ResourceRecord> = typeof opts === 'object' ? opts : {}
-  if (typeof ids === 'string' || Array.isArray(ids)) {
-    params.id = ids
-  }
-  if (typeof opts === 'string') {
-    params.resource = opts
-  } else if (typeof opts === 'boolean') {
-    params.listen = opts
+      return current as V
+    }
   }
-  params.listen = params.listen ?? true
+}
 
+/**
+ * One record from a state resource, live.
+ *
+ * It never throws for missing data: an id the store knows nothing about yields a model whose
+ * `empty` is true — reading `record` gives the resource's configured default, and nothing is
+ * written into the store on the way. Pass no id to address the one record of a `single`
+ * resource; on any other that is a configuration error and throws.
+ */
+export const useStoreModel = <T extends ResourceRecord = ResourceRecord>(
+  id?: string, alias?: string
+): StateModel<T> => {
   const context = useContext()
-  const resource = useMemo(() => context.getStateResource(params.resource), [params.resource])
+  const resource = useMemo(() => context.getStateResource<T>(alias), [context, alias])
+  const store = useMemo(
+    () => bind<StateModel<T>>(listener => resource.watch(id, listener)),
+    [resource, id]
+  )
 
-  const deps = [
-    Array.isArray(params.id) ? params.id.join(',') : params.id,
-    /**
-     * The query's CONTENT, not merely whether one was given. A subscription is to the criteria,
-     * so a screen that narrows its filter has to re-subscribe — keyed on `query == null` it kept
-     * answering the first filter it ever saw, and nothing indicated the list had gone stale.
-     */
-    JSON.stringify(params.query),
-    JSON.stringify(params.default),
-    params.listen
-  ]
-
-  const id = useId()
-  const [models, setModels] = useState<StateModel<ResourceRecord>[]>([])
-
-  let _return = [...models]
-
-  const unsubscribe = useMemo(() => {
-    const [unsubscribe, _initialModels] = resource.subscribe({
-      _systemId: id,
-      id: params.id,
-      listener: models => {
-        params.listen && setModels(models)
-      },
-      default: params.default,
-      query: params.query,
-    })
-    setModels(_initialModels)
-
-    if (_return.length < 1) {
-      _return.push(..._initialModels)
-    }
+  return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
+}
 
-    return unsubscribe
-  }, deps)
+/**
+ * A live LIST from a state resource: every record the query accepts, re-evaluated on every write
+ * that changes the answer, so a screen never recomputes ids and never re-subscribes to keep up.
+ * Omitting `query` matches everything.
+ */
+export const useStoreList = <T extends ResourceRecord = ResourceRecord>(
+  opts?: UseStoreListOptions<T>
+): StateModel<T>[] => {
+  const context = useContext()
+  const resource = useMemo(() => context.getStateResource<T>(opts?.resource), [context, opts?.resource])
 
-  useEffect(() => unsubscribe, deps)
+  /**
+   * The subscription is keyed on the query's CONTENT, not on whether one was given: a screen
+   * that narrows its filter has to re-subscribe, and keyed on identity it kept answering the
+   * first filter it ever saw with nothing to say the list had gone stale.
+   */
+  const key = JSON.stringify([opts?.query ?? null, opts?.sort ?? null])
+  const store = useMemo(
+    () => bind<StateModel<T>[]>(
+      listener => resource.query(opts?.query, listener, { sort: opts?.sort })
+    ),
+    [resource, key]
+  )
 
-  return _return as StateModel<any>[]
+  return useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot)
 }

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { PropsWithChildren, FC, DependencyList } from 'react'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { ClientConfig, ClientContext as BasicClientContext } from '@owlmeans/client-context'
+import type { Criteria, ResourceRecord, Sort } from '@owlmeans/resource'
 import type { StateResourceAppend } from '@owlmeans/state'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import type { DebugServiceAppend, ModalServiceAppend } from './components/types.js'
@@ -35,10 +36,10 @@ export interface AppProps extends PropsWithChildren {
   noRouter?: boolean
 }
 
-export interface RoutedComponent<ExtraProps = {}> extends FC<PropsWithChildren<ModuleContextParams & ExtraProps>> {
+export interface RoutedComponent<ExtraProps = {}> extends FC<PropsWithChildren<EntrypointContextParams & ExtraProps>> {
 }
 
-export interface ModuleContextParams<T extends {} = {}> {
+export interface EntrypointContextParams<T extends {} = {}> {
   alias: string
   params: AbstractRequest<T>['params']
   path: string
@@ -79,3 +80,12 @@ export interface UseValueParams<T> {
   default?: T
   deps?: DependencyList
 }
+
+/** What `useStoreList` subscribes to. Every field is optional; nothing at all means everything. */
+export interface UseStoreListOptions<T extends ResourceRecord = ResourceRecord> {
+  /** The live query. Omitted or `{}` matches every record the resource holds. */
+  query?: Criteria<T>
+  sort?: Sort<T>[]
+  /** Which state resource to read; the context's default one when omitted. */
+  resource?: string
+}

package/src/utils/{module.ts → entrypoint.ts}

@@ -1,12 +1,12 @@
 
 import { createContext } from 'react'
-import type { ModuleContextParams, ClientContext } from '../types.js'
+import type { EntrypointContextParams, ClientContext } from '../types.js'
 import type { ClientConfig } from '@owlmeans/client-context'
 
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
 
-export const ModuleContext = createContext<ModuleContextParams>({
+export const EntrypointContext = createContext<EntrypointContextParams>({
   alias: '',
   params: {},
   path: '',

package/src/utils/index.ts

@@ -1,4 +1,4 @@
 
 export * from './router.js'
 export * from './route.js'
-export * from './module.js'
+export * from './entrypoint.js'

package/src/utils/route.tsx

@@ -1,5 +1,5 @@
 import type { FC, PropsWithChildren, ReactElement } from 'react'
-import type { ModuleContextParams, RoutedComponent, ClientContext } from '../types.js'
+import type { EntrypointContextParams, RoutedComponent, ClientContext } from '../types.js'
 import { isValidElement, memo, useEffect } from 'react'
 import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
 import { provideRequest } from '@owlmeans/client-entrypoint'
@@ -18,7 +18,7 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
   useEffect(() => {
     if (module.guards != null) {
       const guards = module.getGuards().map(guard => context.service<GuardService>(guard))
-      const request = provideRequest(module.alias, module.getPath())
+      const request = provideRequest(module.alias, module.path())
       const reply = provideResponse()
       let canceled = false
       Promise.all(guards.map(async guard => {
@@ -41,7 +41,7 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
   }, module.guards ?? [])
 
   let Renderer: HandledRenderer<{}> = module.handle?.({
-    alias: module.alias, path: module.getPath(),
+    alias: module.alias, path: module.path(),
     params, body: {}, headers: {}, query: {},
   }, reply) as HandledRenderer<{}>
 
@@ -55,8 +55,8 @@ export const createRouteRenderer: (params: RendererParams) => FC = ({ context, m
   const Outlet = context.router().outlet()
   if (isComponent(Renderer)) {
     const EnsuredRenderer = memo(Renderer) as RoutedComponent
-    const props: ModuleContextParams = {
-      context, params, alias: module.getAlias(), path: module.getPath()
+    const props: EntrypointContextParams = {
+      context, params, alias: module.alias, path: module.path()
     }
     if (hasChildren) {
       return <EnsuredRenderer {...props}><Outlet /></EnsuredRenderer>

package/src/utils/router.ts

@@ -7,8 +7,8 @@ import type { ClientContext } from '../types.js'
 type Config = ClientConfig
 interface Context<C extends Config = Config> extends ClientContext<C> { }
 
-export const buildModuleTree = <R, C extends Config = Config, T extends Context<C> = Context<C>>(context: T): ModuleTree<R> => {
-  const modules = context.entrypoints<ClientEntrypoint<R>>().filter(
+export const buildEntrypointTree = <R, C extends Config = Config, T extends Context<C> = Context<C>>(context: T): EntrypointTree<R> => {
+  const entrypoints = context.entrypoints<ClientEntrypoint<R>>().filter(
     module => module.route.route.type === AppType.Frontend
       && (module.sticky || module.route.route.service == null
         || module.route.route.service === context.cfg.service)
@@ -17,8 +17,8 @@ export const buildModuleTree = <R, C extends Config = Config, T extends Context<
   const flatTree = new Map<ClientEntrypoint<R>, ClientEntrypoint<R>[]>()
   const roots: ClientEntrypoint<R>[] = []
 
-  modules.forEach(module => {
-    const parentAlias = module.getParentAlias()
+  entrypoints.forEach(module => {
+    const parentAlias = module.route.route.parent
     if (parentAlias == null) {
       roots.push(module)
     } else {
@@ -29,18 +29,18 @@ export const buildModuleTree = <R, C extends Config = Config, T extends Context<
     }
   })
 
-  const reduceModules = (modules: ClientEntrypoint<R>[]): ModuleTree<R> => modules.reduce(
-    (tree, module) => tree.set(module, reduceModules(flatTree.get(module) ?? [])), new Map()
+  const reduceEntrypoints = (entrypoints: ClientEntrypoint<R>[]): EntrypointTree<R> => entrypoints.reduce(
+    (tree, module) => tree.set(module, reduceEntrypoints(flatTree.get(module) ?? [])), new Map()
   )
 
-  return reduceModules(roots)
+  return reduceEntrypoints(roots)
 }
 
-export const visitModuleTree = async <T, R>(tree: ModuleTree<T>, visitor: ModuleTreeVisitor<T, R>): Promise<R[]> =>
+export const visitEntrypointTree = async <T, R>(tree: EntrypointTree<T>, visitor: EntrypointTreeVisitor<T, R>): Promise<R[]> =>
   Array.from(tree.entries()).reduce<Promise<R[]>>(
     async (result, [module, tree], _, source) => [
       ...(await result),
-      await visitor(module, await visitModuleTree(tree, visitor), source.length === 1)
+      await visitor(module, await visitEntrypointTree(tree, visitor), source.length === 1)
     ], Promise.resolve([]))
 
 export const initializeRouter = async (context: Context) => {
@@ -52,9 +52,9 @@ export const initializeRouter = async (context: Context) => {
   return await model.resolve(context)
 }
 
-export interface ModuleTreeVisitor<T, R> {
+export interface EntrypointTreeVisitor<T, R> {
   (module: ClientEntrypoint<T>, children: R[], alone: boolean): Promise<R>
 }
 
-interface ModuleTree<T> extends Map<ClientEntrypoint<T>, ModuleTree<T>> {
+interface EntrypointTree<T> extends Map<ClientEntrypoint<T>, EntrypointTree<T>> {
 }

package/build/module.d.ts

@@ -1,3 +0,0 @@
-import type { ModuleContextParams } from './types.js';
-export declare const useModule: <T extends {} = {}>() => ModuleContextParams<T>;
-//# sourceMappingURL=module.d.ts.map

package/build/module.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,EAAE,GAAG,EAAE,OAAoC,mBAAmB,CAAC,CAAC,CAAC,CAAA"}

package/build/module.js

@@ -1,4 +0,0 @@
-import { useContext } from 'react';
-import { ModuleContext } from './utils/index.js';
-export const useModule = () => useContext(ModuleContext);
-//# sourceMappingURL=module.js.map

package/build/module.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAGhD,MAAM,CAAC,MAAM,SAAS,GAAG,GAAsB,EAAE,CAAC,UAAU,CAAC,aAAa,CAA2B,CAAA"}

package/build/utils/module.d.ts

@@ -1,3 +0,0 @@
-import type { ModuleContextParams } from '../types.js';
-export declare const ModuleContext: import("react").Context<ModuleContextParams<{}>>;
-//# sourceMappingURL=module.d.ts.map

package/build/utils/module.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/utils/module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAiB,MAAM,aAAa,CAAA;AAMrE,eAAO,MAAM,aAAa,kDAKxB,CAAA"}

package/build/utils/module.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/utils/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAOrC,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAsB;IAC9D,KAAK,EAAE,EAAE;IACT,MAAM,EAAE,EAAE;IACV,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAa;CACvB,CAAC,CAAA"}

package/src/module.ts

@@ -1,6 +0,0 @@
-
-import { useContext } from 'react'
-import { ModuleContext } from './utils/index.js'
-import type { ModuleContextParams } from './types.js'
-
-export const useModule = <T extends {} = {}>() => useContext(ModuleContext) as ModuleContextParams<T>