ignotum 0.0.16 → 0.0.18

package/src/client/router.ts

@@ -1,324 +1 @@
-import {
-  buildUrl,
-  compilePatterns,
-  decodeRouteInputs,
-  matchPattern,
-  parseLocation,
-} from "@ignotum/shared/routing";
-import { Effect, Predicate, Schema } from "effect";
-import { createContext, createElement, type JSX } from "preact";
-import { useContext, useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";
-import {
-  getRouteDefinition,
-  type RouteReference,
-  type ReferenceTypes,
-} from "../internal/routes.js";
-import type { RouteInputs, RouteMatch, RouteLocation, NavigationResult } from "./routes.js";
-import type {
-  RouterStore,
-  RouterSnapshot,
-  NavigationOptions,
-  NavigationState,
-  BlockerState,
-} from "./router-store.js";
-
-export const RouterContext = createContext<RouterStore | undefined>(undefined);
-const useRouter = (): RouterStore => {
-  const router = useContext(RouterContext);
-  if (router === undefined)
-    throw new Error("Ignotum routing hooks require a managed client mount.");
-  return router;
-};
-export const useRouterSnapshot = (router: RouterStore): RouterSnapshot => {
-  const [snapshot, setSnapshot] = useState(router.getSnapshot);
-  useLayoutEffect(() => {
-    const update = () => setSnapshot(router.getSnapshot());
-    const unsubscribe = router.subscribe(update);
-    update();
-    return unsubscribe;
-  }, [router]);
-  return snapshot;
-};
-
-type OptionsArgs<Options> = {} extends Options ? [options?: Options] : [options: Options];
-export type NavigateOptions<Reference extends RouteReference> = RouteInputs<Reference> &
-  NavigationOptions;
-export interface Navigate {
-  <Reference extends RouteReference>(
-    reference: Reference,
-    ...args: OptionsArgs<NavigateOptions<NoInfer<Reference>>>
-  ): Promise<NavigationResult>;
-  back(): void;
-  forward(): void;
-}
-
-export function url<Reference extends RouteReference>(
-  reference: Reference,
-  ...args: OptionsArgs<RouteInputs<NoInfer<Reference>>>
-): string {
-  return Effect.runSync(buildUrl(getRouteDefinition(reference), args[0]));
-}
-
-// Link and navigate own additional options; only URL fields belong to the shared URL codec.
-const destinationHref = (
-  reference: RouteReference,
-  input: {
-    readonly params?: unknown;
-    readonly searchParams?: unknown;
-    readonly hash?: string;
-  } = {},
-): string =>
-  Effect.runSync(
-    buildUrl(getRouteDefinition(reference), {
-      params: input.params,
-      searchParams: input.searchParams,
-      hash: input.hash,
-    }),
-  );
-
-const NavigationInput = Schema.Struct({
-  params: Schema.optional(Schema.Unknown),
-  searchParams: Schema.optional(Schema.Unknown),
-  hash: Schema.optional(Schema.String),
-  replace: Schema.optional(Schema.Boolean),
-  scroll: Schema.optional(Schema.Literals(["auto", "preserve"])),
-}).annotate({ parseOptions: { onExcessProperty: "error" } });
-
-export const useNavigate = (): Navigate => {
-  const router = useRouter();
-  const [navigate] = useState<Navigate>(() =>
-    Object.assign(
-      <Reference extends RouteReference>(
-        reference: Reference,
-        ...args: OptionsArgs<NavigateOptions<NoInfer<Reference>>>
-      ) => {
-        const options = Schema.decodeUnknownSync(NavigationInput)(args[0] ?? {});
-        return router.navigate(destinationHref(reference, options), options);
-      },
-      { back: router.back, forward: router.forward },
-    ),
-  );
-  return navigate;
-};
-export const useLocation = (): RouteLocation => {
-  const snapshot = useRouterSnapshot(useRouter());
-  if (snapshot.location === undefined)
-    throw new Error("The initial Ignotum location has not committed.");
-  return snapshot.location;
-};
-export const useNavigation = (): NavigationState => useRouterSnapshot(useRouter()).navigation;
-
-export const useBlocker = ({ when }: { readonly when: boolean }): BlockerState => {
-  const router = useRouter();
-  const [id] = useState(() => Symbol("blocker"));
-  useRouterSnapshot(router);
-  useLayoutEffect(() => {
-    router.setBlocker(id, when);
-  }, [router, id, when]);
-  useLayoutEffect(() => () => router.setBlocker(id, false), [router, id]);
-  return router.getBlocker(id);
-};
-
-const matchReference = <Reference extends RouteReference>(
-  reference: Reference,
-  snapshot: RouterSnapshot,
-  end: boolean,
-): RouteMatch<Reference> | undefined => {
-  const location = snapshot.location;
-  const outcome = snapshot.branch?.outcome;
-  if (location === undefined || outcome === undefined) return;
-  const definition = getRouteDefinition(reference);
-  if (end && (outcome._tag !== "Matched" || outcome.route.id !== definition.id)) return;
-  const parsed = Effect.runSync(
-    parseLocation(`${location.pathname}${location.search}`).pipe(Effect.result),
-  );
-  if (parsed._tag === "Failure") return;
-  const compiled = Effect.runSync(compilePatterns([{ ...definition, layouts: [] }], []));
-  for (let length = parsed.success.segments.length; length >= 0; length--) {
-    if (length === 0 && parsed.success.segments.length !== 0) break;
-    const match = matchPattern(compiled, parsed.success.segments.slice(0, length));
-    if (match.route !== undefined) {
-      const decoded = Effect.runSync(
-        decodeRouteInputs(definition, match.params, location.search).pipe(Effect.result),
-      );
-      if (decoded._tag === "Failure") return;
-      // SAFETY: The reference's own validated descriptors determine these decoded generic input types.
-      return { ...decoded.success, hash: location.hash } as RouteMatch<Reference>;
-    }
-    if (end) break;
-  }
-  return;
-};
-export function useMatch<Reference extends RouteReference>(
-  reference: Reference,
-  options?: { readonly end?: boolean },
-): RouteMatch<Reference> | undefined {
-  return matchReference(reference, useRouterSnapshot(useRouter()), options?.end ?? true);
-}
-export type RouteState<Reference extends RouteReference> = RouteMatch<Reference> & {
-  readonly setSearchParams: (
-    next:
-      | ReferenceTypes<Reference>["searchInputs"]
-      | ((
-          current: ReferenceTypes<Reference>["searchParams"],
-        ) => ReferenceTypes<Reference>["searchInputs"]),
-    options?: NavigationOptions,
-  ) => Promise<NavigationResult>;
-};
-export function useRoute<Reference extends RouteReference>(
-  reference: Reference,
-): RouteState<Reference> {
-  const router = useRouter();
-  const snapshot = useRouterSnapshot(router);
-  const match = matchReference(reference, snapshot, true);
-  if (match === undefined)
-    throw new Error(`useRoute requires page '${getRouteDefinition(reference).id}' to be active.`);
-  return {
-    ...match,
-    setSearchParams: (next, options) => {
-      const latest = matchReference(reference, router.getSnapshot(), true);
-      const location = router.getSnapshot().location;
-      if (latest === undefined || location === undefined)
-        throw new Error("Cannot update search parameters for an inactive route.");
-      // A function is the only callable alternative in the public search update union.
-      const inputs = Predicate.isFunction(next) ? next(latest.searchParams) : next;
-      const href = destinationHref(reference, {
-        params: latest.params,
-        searchParams: inputs,
-        hash: latest.hash,
-      });
-      const destination = new URL(href, router.browser.location.origin);
-      destination.pathname = location.pathname;
-      const declared = new Set(
-        getRouteDefinition(reference).searchParams.map((field) => field.name),
-      );
-      for (const [name, value] of new URLSearchParams(location.search)) {
-        if (!declared.has(name)) destination.searchParams.append(name, value);
-      }
-      return router.navigate(`${destination.pathname}${destination.search}${destination.hash}`, {
-        scroll: "preserve",
-        ...options,
-      });
-    },
-  };
-}
-
-type AnchorProps = Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "class" | "ref">;
-export type LinkProps<Reference extends RouteReference> = AnchorProps &
-  NavigateOptions<Reference> & {
-    readonly to: Reference;
-    readonly class?: string;
-    readonly preload?: "intent" | "none";
-  };
-export type NavLinkProps<Reference extends RouteReference> = Omit<LinkProps<Reference>, "class"> & {
-  readonly end?: boolean;
-  readonly class?: string | ((state: { readonly isActive: boolean }) => string);
-};
-
-const activePath = (current: string, destination: string, end: boolean): boolean => {
-  const source = Effect.runSync(parseLocation(current).pipe(Effect.result));
-  const target = Effect.runSync(parseLocation(destination).pipe(Effect.result));
-  if (source._tag === "Failure" || target._tag === "Failure") return false;
-  const from = source.success.segments;
-  const to = target.success.segments;
-  if (from.length !== to.length && (end || to.length === 0 || from.length < to.length))
-    return false;
-  return to.every((segment, index) => from[index] === segment);
-};
-
-interface AnchorRuntimeProps extends AnchorProps, NavigationOptions {
-  readonly to: RouteReference;
-  readonly params?: unknown;
-  readonly searchParams?: unknown;
-  readonly hash?: string;
-  readonly preload?: "intent" | "none";
-  readonly end?: boolean;
-  readonly active?: boolean;
-  readonly class?: string | ((state: { readonly isActive: boolean }) => string);
-}
-function Anchor(props: AnchorRuntimeProps): JSX.Element {
-  const router = useRouter();
-  const snapshot = useRouterSnapshot(router);
-  const {
-    to,
-    params,
-    searchParams,
-    hash,
-    replace,
-    scroll,
-    preload = "intent",
-    end = true,
-    active = false,
-    class: className,
-    onClick,
-    onMouseEnter,
-    onFocus,
-    ...attributes
-  } = props;
-  const href = destinationHref(to, { params, searchParams, hash });
-  const isActive =
-    active &&
-    snapshot.location !== undefined &&
-    activePath(snapshot.location.pathname, href.split(/[?#]/)[0]!, end);
-  const prepare = () => {
-    if (preload !== "none") void router.preload(href).catch(() => {});
-  };
-  return createElement("a", {
-    ...attributes,
-    href,
-    class: Predicate.isFunction(className) ? className({ isActive }) : className,
-    "aria-current": isActive ? "page" : attributes["aria-current"],
-    onClick: (event: JSX.TargetedMouseEvent<HTMLAnchorElement>): void => {
-      onClick?.(event);
-      const anchor = event.currentTarget;
-      if (
-        event.defaultPrevented ||
-        event.button !== 0 ||
-        event.metaKey ||
-        event.ctrlKey ||
-        event.shiftKey ||
-        event.altKey ||
-        (anchor.target !== "" && anchor.target.toLowerCase() !== "_self") ||
-        anchor.hasAttribute("download") ||
-        anchor.relList.contains("external") ||
-        anchor.origin !== router.browser.location.origin ||
-        `${anchor.pathname}${anchor.search}${anchor.hash}` !== href
-      )
-        return;
-      event.preventDefault();
-      void router.navigate(href, { replace, scroll });
-    },
-    onMouseEnter: (event: JSX.TargetedMouseEvent<HTMLAnchorElement>): void => {
-      onMouseEnter?.(event);
-      if (!event.defaultPrevented) prepare();
-    },
-    onFocus: (event: JSX.TargetedFocusEvent<HTMLAnchorElement>): void => {
-      onFocus?.(event);
-      if (!event.defaultPrevented) prepare();
-    },
-  });
-}
-export function Link<Reference extends RouteReference>(props: LinkProps<Reference>): JSX.Element {
-  return createElement(Anchor, props);
-}
-export function NavLink<Reference extends RouteReference>(
-  props: NavLinkProps<Reference>,
-): JSX.Element {
-  return createElement(Anchor, { ...props, active: true });
-}
-export type RedirectProps<Reference extends RouteReference> = NavigateOptions<Reference> & {
-  readonly to: Reference;
-};
-export function Redirect<Reference extends RouteReference>(props: RedirectProps<Reference>): null {
-  const router = useRouter();
-  const href = destinationHref(props.to, props);
-  const previous = useRef<string>();
-  const replace = props.replace ?? true;
-  useEffect(() => {
-    const identity = JSON.stringify([href, replace, props.scroll]);
-    if (previous.current === identity) return;
-    previous.current = identity;
-    void router.navigate(href, { replace, scroll: props.scroll }, true);
-  }, [router, href, replace, props.scroll]);
-  return null;
-}
+export * from "@ignotum/platform/versions/1/browser/router";

package/src/client/routes.ts

@@ -1,28 +1 @@
-import type { ReferenceTypes } from "../internal/routes.js";
-
-type Empty = Readonly<Record<string, never>>;
-type Group<Name extends string, Fields> = keyof Fields extends never
-  ? { readonly [Key in Name]?: Empty }
-  : {} extends Fields
-    ? { readonly [Key in Name]?: Fields }
-    : { readonly [Key in Name]: Fields };
-
-/** Decoded values delivered to a page component. */
-export type RouteProps<Reference> = {
-  readonly params: ReferenceTypes<Reference>["params"];
-  readonly searchParams: ReferenceTypes<Reference>["searchParams"];
-};
-/** URL inputs. Search defaults can be omitted when navigating. */
-export type RouteInputs<Reference> = Group<"params", ReferenceTypes<Reference>["params"]> &
-  Group<"searchParams", ReferenceTypes<Reference>["searchInputs"]> & { readonly hash?: string };
-export type RouteMatch<Reference> = RouteProps<Reference> & { readonly hash: string };
-export interface RouteLocation {
-  readonly pathname: string;
-  readonly search: string;
-  readonly hash: string;
-  readonly key: string;
-}
-export type NavigationResult =
-  | { readonly status: "committed" }
-  | { readonly status: "cancelled" }
-  | { readonly status: "failed"; readonly error: unknown };
+export * from "@ignotum/platform/versions/1/browser/routes";

package/src/client/sync.ts

@@ -1,286 +1 @@
-import { BrowserSession } from "./id.js";
-import { ManagedBrowserClient } from "./managed-client.js";
-import type { ExecutionSelection } from "@ignotum/contracts/platform";
-import { Context, Effect, Layer, ManagedRuntime, Schema } from "effect";
-
-import { encodeCanonicalJson } from "@ignotum/contracts/json";
-import { type AppStateRevision } from "@ignotum/contracts/runtime/hosted";
-import { IdGenerator } from "@ignotum/shared/id";
-import type { ManagedClientMessage, ManagedServerMessage } from "@ignotum/contracts/managed-sync";
-
-import type {
-  ErrorValue,
-  QueryResult,
-  Result as IgnotumResult,
-} from "@ignotum/contracts/runtime/result";
-import { failureFromWire, pending, Result } from "@ignotum/contracts/runtime/result";
-import {
-  SubscriptionId,
-  decodeTransportValue,
-  type FunctionAddress,
-  type WireResult,
-} from "@ignotum/contracts/runtime/sync";
-import {
-  ClientInfrastructureError,
-  ConnectionUnavailable,
-  InvalidServerMessage,
-  clientErrorReporterLayer,
-} from "./errors.js";
-import { applyFileGrants } from "./files.js";
-
-type Listener = () => void;
-
-interface QueryEntry {
-  readonly args: Schema.Json;
-  readonly function: FunctionAddress;
-  readonly listeners: Set<Listener>;
-  readonly subscriptionId: SubscriptionId;
-  generation: number;
-  dependsOnId?: boolean;
-  revision: AppStateRevision | undefined;
-  references: number;
-  result: QueryResult<unknown, ErrorValue> | ClientInfrastructureError;
-}
-
-export interface QueryObserver {
-  readonly getSnapshot: () => QueryResult<unknown, ErrorValue> | ClientInfrastructureError;
-  readonly release: Effect.Effect<void>;
-  readonly subscribe: (listener: Listener) => () => void;
-}
-
-type QueryLifecycleMessage = Extract<
-  ManagedClientMessage,
-  { readonly type: "Subscribe" | "Unsubscribe" }
->;
-
-interface QueryCache {
-  readonly invalidate: (ids?: ReadonlyArray<SubscriptionId>) => void;
-  readonly invalidatePrivate: () => void;
-  readonly entries: () => Iterable<QueryEntry>;
-  readonly getById: (id: SubscriptionId) => QueryEntry | undefined;
-  readonly setResult: (
-    id: SubscriptionId,
-    result: QueryResult<unknown, ErrorValue> | ClientInfrastructureError,
-    revision?: AppStateRevision,
-  ) => void;
-  readonly observe: (
-    functionAddress: FunctionAddress,
-    args: Schema.Json,
-  ) => Effect.Effect<QueryObserver>;
-}
-
-const queryKey = (functionAddress: FunctionAddress, args: Schema.Json): string =>
-  encodeCanonicalJson([functionAddress, args]);
-
-const subscribeMessage = (entry: QueryEntry): QueryLifecycleMessage => ({
-  type: "Subscribe",
-  id: entry.subscriptionId,
-  function: entry.function,
-  args: entry.args,
-});
-
-const makeQueryCache = (
-  allocateId: Effect.Effect<SubscriptionId>,
-  sendLifecycleMessage: (message: QueryLifecycleMessage) => Effect.Effect<void>,
-) => {
-  const queries = new Map<string, QueryEntry>();
-  const queriesById = new Map<SubscriptionId, QueryEntry>();
-
-  const observe = Effect.fn("SyncClient.QueryCache.observe")(function* (
-    functionAddress: FunctionAddress,
-    args: Schema.Json,
-  ) {
-    const key = queryKey(functionAddress, args);
-    let entry = queries.get(key);
-
-    if (entry === undefined) {
-      const created: QueryEntry = {
-        args,
-        function: functionAddress,
-        generation: 0,
-        listeners: new Set(),
-        revision: undefined,
-        references: 0,
-        result: pending(),
-        subscriptionId: yield* allocateId,
-      };
-      queries.set(key, created);
-      queriesById.set(created.subscriptionId, created);
-      yield* sendLifecycleMessage(subscribeMessage(created));
-      entry = created;
-    }
-
-    const observed = entry;
-    observed.references += 1;
-    observed.generation += 1;
-    let released = false;
-    return {
-      getSnapshot: () => observed.result,
-      subscribe: (listener: Listener) => {
-        observed.listeners.add(listener);
-        return () => observed.listeners.delete(listener);
-      },
-      release: Effect.gen(function* () {
-        if (released) return;
-        released = true;
-        observed.references -= 1;
-        if (observed.references !== 0) return;
-        const generation = ++observed.generation;
-
-        // Preact and HMR may release and reacquire an observer during one render handoff.
-        // Keep the server subscription alive long enough for that handoff to reuse it.
-        yield* Effect.sleep("25 millis");
-        if (
-          observed.references !== 0 ||
-          observed.generation !== generation ||
-          queries.get(key) !== observed
-        ) {
-          return;
-        }
-
-        queries.delete(key);
-        queriesById.delete(observed.subscriptionId);
-        yield* sendLifecycleMessage({
-          type: "Unsubscribe",
-          id: observed.subscriptionId,
-        });
-      }),
-    } satisfies QueryObserver;
-  });
-
-  const clear = (entry: QueryEntry) => {
-    entry.result = pending();
-    entry.revision = undefined;
-    for (const listener of entry.listeners) listener();
-  };
-  return {
-    invalidate: (ids) => {
-      for (const entry of queries.values())
-        if (ids === undefined || ids.includes(entry.subscriptionId)) clear(entry);
-    },
-    invalidatePrivate: () => {
-      for (const entry of queries.values()) if (entry.dependsOnId !== false) clear(entry);
-    },
-    entries: () => queries.values(),
-    getById: (id: SubscriptionId) => queriesById.get(id),
-    observe,
-    setResult: (id, result, revision?: AppStateRevision) => {
-      const entry = queriesById.get(id);
-      if (entry === undefined) return;
-      if (revision !== undefined) {
-        if (entry.revision !== undefined && revision < entry.revision) return;
-        entry.revision = revision;
-      }
-      entry.result = result;
-      for (const listener of entry.listeners) {
-        listener();
-      }
-    },
-  } satisfies QueryCache;
-};
-
-type SnapshotFiles = NonNullable<
-  Extract<ManagedServerMessage, { readonly type: "QuerySnapshot" }>["files"]
->;
-
-const resultFromWire = Effect.fn("SyncClient.resultFromWire")(
-  (wire: WireResult, files: SnapshotFiles = []) =>
-    Effect.try({
-      try: () =>
-        wire.type === "Success"
-          ? Result.succeed(
-              wire.value === undefined
-                ? undefined
-                : applyFileGrants(decodeTransportValue(wire.value, wire.dates ?? []), files),
-            )
-          : failureFromWire(wire.error, wire.dates),
-      catch: (cause) =>
-        InvalidServerMessage.make({
-          cause,
-          message: "The server returned an invalid function result.",
-        }),
-    }),
-);
-
-export const syncClientInternals = {
-  makeQueryCache,
-  queryIdentity: queryKey,
-  resultFromWire,
-};
-
-export interface SyncClientService {
-  readonly mutate: (
-    functionAddress: FunctionAddress,
-    // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Generated reference argument types are deliberately erased at the client transport boundary.
-    args: unknown,
-  ) => Effect.Effect<IgnotumResult<unknown, ErrorValue>, ClientInfrastructureError>;
-  readonly observe: (
-    functionAddress: FunctionAddress,
-    args: Schema.Json,
-  ) => Effect.Effect<QueryObserver, ClientInfrastructureError>;
-}
-
-export class SyncClient extends Context.Service<SyncClient, SyncClientService>()(
-  "ignotum/client/sync/SyncClient",
-) {}
-
-const makeUnmountedSyncRuntime = () =>
-  ManagedRuntime.make(
-    Layer.succeed(SyncClient)({
-      observe: () =>
-        Effect.fail(ConnectionUnavailable.make({ message: "The application has not mounted." })),
-      mutate: () =>
-        Effect.fail(ConnectionUnavailable.make({ message: "The application has not mounted." })),
-    }).pipe(
-      Layer.provideMerge(BrowserSession.layer),
-      Layer.provideMerge(clientErrorReporterLayer),
-      Layer.provideMerge(IdGenerator.layer),
-    ),
-  );
-export let syncRuntime = makeUnmountedSyncRuntime();
-
-export const mountManagedSync = (
-  selection: ExecutionSelection,
-  browser: Window,
-  callbacks: { readonly stopAdmission: () => void; readonly reload: () => void },
-) => {
-  const client = new ManagedBrowserClient(selection, browser, syncClientInternals, callbacks);
-  const previous = syncRuntime;
-  void previous.dispose();
-  syncRuntime = ManagedRuntime.make(
-    Layer.effect(
-      SyncClient,
-      Effect.gen(function* () {
-        client.attachSession(yield* BrowserSession, yield* IdGenerator);
-        return SyncClient.of({ observe: client.observe, mutate: client.mutate });
-      }),
-    ).pipe(
-      Layer.provideMerge(BrowserSession.layer),
-      Layer.provideMerge(clientErrorReporterLayer),
-      Layer.provideMerge(IdGenerator.layer),
-    ),
-  );
-  const runtime = syncRuntime;
-  void runtime.runPromise(SyncClient).then(
-    () => client.start(),
-    () => client.dispose(),
-  );
-  return {
-    client,
-    dispose: () => {
-      client.dispose();
-      void runtime.dispose();
-      if (syncRuntime === runtime) syncRuntime = makeUnmountedSyncRuntime();
-    },
-  };
-};
-
-// SAFETY: Vite adds this optional property to browser development modules.
-const hot = (
-  import.meta as ImportMeta & {
-    readonly hot?: { readonly dispose: (cleanup: () => void) => void };
-  }
-).hot;
-if (hot !== undefined) {
-  hot.dispose(() => void syncRuntime.dispose());
-}
+export * from "@ignotum/platform/versions/1/browser/sync";

package/src/dev-runtime/id.ts

@@ -28,7 +28,7 @@ const ProfilesV1 = Schema.Struct({
 const Profiles = Versioned.initial(ProfilesV1);
 const ProfilesJson = Schema.fromJsonString(Profiles);
 
-export const localIdPath = "/_ignotum/v1/id";
+export const localIdPath = "/_ignotum/v1.0/id";
 export const LocalCompletion = Schema.Struct({
   request: SessionRequest,
   username: DevelopmentUsername,