Add generated lazy pages, version polling, PWA integration, and browser helpers.
Package entry point
@wsagency/wseffect-app · MIT · source · MIT license · WS-AGENCY-NOTICE
This entry point is published in @wsagency/wseffect-app@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.
import * as Wseffect from '@wsagency/wseffect-app'
Exported declarations
activate
export declare function activate<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string, ParentMessage>(pages: PagesHandle<Pages>, slots: PageSlots<Pages>, key: Key, toParentMessage: (message: MessageOf<Pages[Key]>) => ParentMessage): Readonly<{
slots: PageSlots<Pages>;
commands: ReadonlyArray<Command.Command<ParentMessage>>;
}>;
AnyPage
export type AnyPage = PageDefinition<any, any, any, any, any>;
bindKit
export declare function bindKit<Pages extends Record<string, AnyPage>, KitMessage extends object>(config: BindKitConfig<Pages, KitMessage>): KitBinding<Pages, KitMessage>;
BindKitConfig
export interface BindKitConfig<Pages extends Record<string, AnyPage>, KitMessage extends object> {
readonly pages: PagesHandle<Pages>;
readonly KitMessage: {
readonly Type: KitMessage;
};
readonly pageMessageTags: {
readonly [Key in keyof Pages]: string;
};
}
Breakpoint
export type Breakpoint = 'initial' | typeof BREAKPOINTS[number]['name'];
breakpointSubscription
export declare function breakpointSubscription<Message>(toMessage: (value: Breakpoint) => Message): {
readonly 'wseffect:breakpoint': Subscription.EntryWithoutKeepAlive<unknown, Message, {}, never> & {
readonly __subscription: never;
};
};
BrowserCommandResult
export type BrowserCommandResult = {
readonly _tag: 'Succeeded';
} | {
readonly _tag: 'Failed';
readonly reason: string;
};
BUILD_ID
BUILD_ID: string
classifyFailure
export declare function classifyFailure(input: {
readonly isOnline: boolean;
readonly fetchVersion: Effect.Effect<Response, unknown>;
readonly runningBuildId: string;
}): Effect.Effect<FailureCause>;
clipboardCommand
Uses the browser Clipboard API, which generally requires a secure context and user activation; permission policy cannot be bypassed.
export declare function clipboardCommand<M>(text: string, toMessage: (result: BrowserCommandResult) => M): Command.Command<M, never>;
ConflictPolicy
`local-wins` never applies remote values; timestamp arbitration is explicit in the other policy.
export type ConflictPolicy = 'last-writer-wins-by-timestamp' | 'local-wins';
ensure
Loads and registers a page once. Concurrent requests share the same result; failures are evicted for retry.
export declare function ensure<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string>(pages: PagesHandle<Pages>, key: Key, options?: EnsureOptions): Effect.Effect<Pages[Key], PageLoadError>;
FailureCause
export type FailureCause = 'Offline' | 'NewVersion' | 'LoadError';
foldPage
export declare function foldPage<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string, KitMessage extends object>(config: Readonly<{
pages: PagesHandle<Pages>;
key: Key;
toParentMessage: (message: MessageOf<Pages[Key]>) => KitMessage;
}>): (state: KitState<Pages>, message: MessageOf<Pages[Key]>) => Update.ReturnWithOutMessage<KitState<Pages>, KitMessage, OutMessageOf<Pages[Key]>, ServicesOf<Pages[Key]>>;
initKit
export declare function initKit<Pages extends Record<string, AnyPage>>(pages: PagesHandle<Pages>, activeKeys: ReadonlyArray<keyof Pages & string>): KitState<Pages>;
InputsOf
export type InputsOf<P> = P extends PageDefinition<any, any, infer Inputs, any, any> ? Inputs : never;
Island
Explicit Foldkit ownership exception for trusted server-rendered subtrees; not a general app-rendering path, and never pass user-controlled raw HTML.
export declare function Island<M>(props: {
readonly id: string;
/** Mount-time initialization only. Use a new `id`/key to remount with different server HTML. */
readonly html: string;
readonly patches: Stream.Stream<IslandPatch>;
readonly toMessage: (result: IslandResult) => M;
}, h: HtmlBuilder<M>): Html;
IslandPatch
export type IslandPatch = {
readonly _tag: 'OuterHtml';
readonly selector: string;
readonly html: string;
} | {
readonly _tag: 'InnerHtml';
readonly selector: string;
readonly html: string;
};
IslandResult
export type IslandResult = {
readonly _tag: 'Applied';
} | {
readonly _tag: 'RejectedIslandPatch';
readonly reason: string;
};
isUserInputCooldownActive
export declare function isUserInputCooldownActive(messages: object): boolean;
KitBinding
export interface KitBinding<Pages extends Record<string, AnyPage>, KitMessage extends object> {
readonly pages: PagesHandle<Pages>;
readonly toParentMessage: {
readonly [Key in keyof Pages]: (message: MessageOf<Pages[Key]>) => KitMessage;
};
readonly update: (state: KitState<Pages>, message: KitMessage) => Update.ReturnWithOutMessage<KitState<Pages>, KitMessage, OutMessageOf<Pages[keyof Pages]>, ServicesOf<Pages[keyof Pages]>>;
readonly messages: {
readonly requestedPrefetch: (key: keyof Pages & string, source?: PrefetchSource) => KitMessage;
readonly requestedPrefetchSchema: Schema.Codec<KitMessage, unknown>;
readonly clickedRetryPage: (key: keyof Pages & string) => KitMessage;
readonly clickedReloadPage: (key: keyof Pages & string) => KitMessage;
readonly clickedApplyUpdate: () => KitMessage;
readonly newVersionAvailable: (buildId: string) => KitMessage;
readonly gotPwaEvent: (event: typeof PwaEvent.Type) => KitMessage;
};
readonly view: Submodel.View<KitState<Pages>, KitMessage, KitPageViewInputs<Pages>>;
readonly bannerView: Submodel.View<KitState<Pages>, KitMessage>;
readonly subscriptions: Readonly<Record<string, Subscription.Subscription<KitState<Pages>, KitMessage, {
readonly isNeeded: boolean;
}>>>;
readonly commands: {
readonly LoadPageForPrefetch: Command.CommandDefinition;
readonly ClassifyPageFailure: Command.CommandDefinition;
readonly ReloadDocument: Command.CommandDefinition;
};
}
kitMessageFields
export declare function kitMessageFields<Pages extends Record<string, AnyPage>>(pages: PagesHandle<Pages>): KitMessageFields<Pages>;
KitMessageFields
export type KitMessageFields<Pages extends Record<string, AnyPage>> = {
readonly EnteredRoute: {
readonly keys: Schema.Codec<ReadonlyArray<keyof Pages & string>, unknown>;
};
readonly LoadedPageModule: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
};
readonly FailedPageModule: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
readonly cause: typeof FailureCauseSchema;
readonly reason: typeof Schema.String;
};
readonly ClickedRetryPage: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
};
readonly ClickedReloadPage: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
};
readonly RequestedPrefetch: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
readonly source: typeof OptionalPrefetchSourceSchema;
};
readonly CompletedPrefetch: {
readonly key: Schema.Codec<keyof Pages & string, unknown>;
readonly isLoaded: typeof Schema.Boolean;
};
readonly GotPwaEvent: {
readonly event: typeof PwaEvent;
};
readonly NewVersionAvailable: {
readonly buildId: typeof Schema.String;
};
readonly ClickedApplyUpdate: Record<string, never>;
readonly CompletedApplyUpdate: Record<string, never>;
readonly FailedApplyUpdate: {
readonly reason: typeof Schema.String;
};
} & {
readonly [Key in keyof Pages & string as `Got${Capitalize<Key>}PageMessage`]: {
readonly message: Schema.Codec<MessageOf<Pages[Key]>, unknown>;
};
};
KitMessageMatcher
export interface KitMessageMatcher<Message> {
match(message: Message, handlers: Record<string, (payload: unknown) => unknown>): unknown;
}
KitPageMessageHandler
export type KitPageMessageHandler<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string> = (payload: KitPageMessagePayload<Pages, Key>) => unknown;
KitPageMessagePayload
export type KitPageMessagePayload<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string> = Readonly<{
message: MessageOf<Pages[Key]>;
}>;
KitPageViewInputs
export type KitPageViewInputs<Pages extends Record<string, AnyPage>> = Readonly<{
key: keyof Pages & string;
inputs: InputsOf<Pages[keyof Pages]>;
}>;
KitState
export interface KitState<Pages extends Record<string, AnyPage>> {
readonly activeKeys: ReadonlyArray<keyof Pages & string>;
readonly slots: PageSlots<Pages>;
readonly pwa: PwaState;
}
kitStateSchema
export declare function kitStateSchema<Pages extends Record<string, AnyPage>>(pages: PagesHandle<Pages>): Schema.Codec<KitState<Pages>, any, never, never>;
KitUpdateCommands
export interface KitUpdateCommands<Message> {
readonly LoadPageForPrefetch: Command.CommandDefinition;
readonly ReloadDocument: Command.CommandDefinition;
readonly makePrefetch: (key: string, source: 'intent' | 'visible') => Command.Command<Message>;
readonly reload: () => Command.Command<Message>;
}
KitUpdateConfig
export interface KitUpdateConfig<Pages extends Record<string, AnyPage>, KitMessage extends object> {
readonly pages: PagesHandle<Pages>;
readonly KitMessage: KitMessageMatcher<KitMessage>;
readonly pageMessageTags: {
readonly [Key in keyof Pages]: string;
};
readonly toParentMessage: {
readonly [Key in keyof Pages]: (message: MessageOf<Pages[Key]>) => KitMessage;
};
readonly commands: KitUpdateCommands<KitMessage>;
}
loaderSubscriptions
export declare function loaderSubscriptions<Pages extends Record<string, AnyPage>, Model, Message>(config: LoaderSubscriptionsConfig<Pages, Model, Message>): Readonly<Record<string, Subscription.Subscription<Model, Message, {
readonly isNeeded: boolean;
}>>>;
LoaderSubscriptionsConfig
export interface LoaderSubscriptionsConfig<Pages extends Record<string, AnyPage>, Model, Message> {
readonly pages: PagesHandle<Pages>;
readonly isNeeded: (model: Model, key: keyof Pages & string) => boolean;
readonly onLoaded: (key: keyof Pages & string) => Message;
readonly onFailure: (key: keyof Pages & string, error: PageLoadError) => Effect.Effect<Message>;
}
Locale
export interface Locale {
readonly locale: string;
readonly number: (value: number, options?: Intl.NumberFormatOptions) => string;
readonly dateTime: (value: Date | number, options?: Intl.DateTimeFormatOptions) => string;
readonly relativeTime: (value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) => string;
readonly plural: (value: number, options?: Intl.PluralRulesOptions) => Intl.LDMLPluralRule;
}
LocaleService
export declare class LocaleService extends LocaleService_base {
static layer(locale: string): Layer.Layer<LocaleService>;
}
makeApp
export declare function makeApp<Model, Message extends {
_tag: string;
}, Pages extends Record<string, AnyPage>, KitMessage extends {
_tag: string;
}, Resources = never, UserSubscriptions extends SubscriptionType.Subscriptions<Model, Message, Resources | ServiceWorker> = {}>(config: MakeAppConfig<Model, Message, Pages, KitMessage, Resources, UserSubscriptions>): Runtime.MakeRuntimeReturn<undefined, void, Resources | ServiceWorker, 'Application'>;
MakeAppConfig
export type MakeAppConfig<Model, Message extends {
_tag: string;
}, Pages extends Record<string, AnyPage>, KitMessage extends {
_tag: string;
}, Resources = never, UserSubscriptions extends SubscriptionType.Subscriptions<Model, Message, Resources | ServiceWorker> = {}> = Omit<Runtime.RoutingApplicationConfig<Model, Message, Resources | ServiceWorker>, 'resources' | 'subscriptions'> & ResourceConfig<Resources> & {
readonly subscriptions?: UserSubscriptions & SubscriptionKeyCheck<UserSubscriptions>;
readonly kit: Readonly<{
binding: KitBinding<Pages, KitMessage>;
read: (model: Model) => KitState<Pages>;
toParentMessage: (message: KitMessage) => Message;
}>;
readonly versionPollMs?: number;
};
makeKitUpdate
export declare function makeKitUpdate<Pages extends Record<string, AnyPage>, KitMessage extends object>(config: KitUpdateConfig<Pages, KitMessage>): (state: KitState<Pages>, message: KitMessage) => Update.ReturnWithOutMessage<KitState<Pages>, KitMessage, OutMessageOf<Pages[keyof Pages]>, ServicesOf<Pages[keyof Pages]>>;
makeLocale
export declare function makeLocale(locale: string): Locale;
makePages
export declare function makePages<Pages extends Record<string, AnyPage>>(loaders: PageLoaders<Pages>): PagesHandle<Pages>;
makeServiceWorkerLayer
export declare function makeServiceWorkerLayer(register: typeof registerSW): Layer.Layer<ServiceWorker>;
MessageOf
export type MessageOf<P> = P extends PageDefinition<any, infer Message, any, any, any> ? Message : never;
messageSchema
export declare function messageSchema<Pages extends Record<string, AnyPage>, Key extends keyof Pages & string>(pages: PagesHandle<Pages>, key: Key): Schema.Codec<MessageOf<Pages[Key]>, any, never, never>;
ModelOf
export type ModelOf<P> = P extends PageDefinition<infer Model, any, any, any, any> ? Model : never;
OutMessageOf
export type OutMessageOf<P> = P extends PageDefinition<any, any, any, infer OutMessage, any> ? OutMessage : never;
pageContract
export declare function pageContract<Inputs extends PageInputsShape, OutMessage extends {
readonly _tag: string;
}>(config: {
readonly OutMessage: Schema.Codec<OutMessage, any>;
}): PageContract<Inputs, OutMessage>;
PageContract
export interface PageContract<Inputs extends PageInputsShape, OutMessage> {
readonly OutMessage: Schema.Codec<OutMessage, any>;
readonly definePage: <Model, Message, R = never>(page: PageDefinition<Model, Message, Inputs, OutMessage, R>) => PageDefinition<Model, Message, Inputs, OutMessage, R>;
}
PageDefinition
export interface PageDefinition<Model, Message, Inputs extends PageInputsShape, OutMessage, R = never> {
readonly Model: Schema.Codec<Model, any, never, never>;
readonly Message: Schema.Codec<Message, any, never, never>;
readonly init: () => Update.Return<Model, Message, R>;
readonly update: (model: Model, message: Message) => Update.ReturnWithOutMessage<Model, Message, OutMessage, R>;
readonly view: Submodel.View<Model, Message, Inputs>;
}
PageInputsShape
export type PageInputsShape = Readonly<Record<string, string | number | boolean | null>>;
PageLoader
export declare class PageLoader extends PageLoader_base {
}
PageLoadError
export declare class PageLoadError extends PageLoadError_base<{
readonly key: string;
readonly cause: unknown;
}> {
}
PageLoaders
export type PageLoaders<Pages extends Record<string, AnyPage>> = {
readonly [Key in keyof Pages]: () => Promise<Pages[Key]>;
};
PageRegistry
export interface PageRegistry<Pages extends Record<string, AnyPage>> {
register<Key extends keyof Pages & string>(key: Key, page: Pages[Key]): void;
get<Key extends keyof Pages & string>(key: Key): Option.Option<Pages[Key]>;
}
PagesHandle
export interface PagesHandle<Pages extends Record<string, AnyPage>> {
readonly keys: ReadonlyArray<keyof Pages & string>;
readonly loaders: PageLoaders<Pages>;
readonly registry: PageRegistry<Pages>;
}
PageSlot
export type PageSlot<Model> = Readonly<{
_tag: 'Idle';
}> | Readonly<{
_tag: 'Available';
}> | Readonly<{
_tag: 'Loading';
}> | Readonly<{
_tag: 'Failed';
cause: FailureCause;
reason: string;
}> | Readonly<{
_tag: 'Ready';
model: Model;
}> | Readonly<{
_tag: 'Dehydrated';
encoded: SchemaTypes.Json;
}>;
PageSlots
export type PageSlots<Pages> = {
readonly [Key in keyof Pages]: PageSlot<ModelOf<Pages[Key]>>;
};
PageViewMessages
export interface PageViewMessages<Pages extends Record<string, AnyPage>, KitMessage> {
readonly clickedRetryPage: (key: keyof Pages & string) => KitMessage;
readonly clickedReloadPage: (key: keyof Pages & string) => KitMessage;
}
persist
export declare function persist<A, M>(config: PersistConfig<A, M>): Persistence<A, M>;
PersistConfig
export interface PersistConfig<A, M> {
readonly key: string;
readonly version: number;
readonly schema: Schema.Codec<A, any, never, never>;
readonly defaultValue: A;
readonly conflictPolicy: ConflictPolicy;
readonly migrate: (storedVersion: number, data: unknown) => Result.Result<A, unknown>;
readonly debounceMs: number;
readonly toMessage: (value: A) => M;
readonly toFailureMessage: (failure: PersistenceFailure) => M;
}
Persistence
export interface Persistence<A, M> {
readonly restore: Effect.Effect<A>;
readonly save: (value: A) => Effect.Effect<void>;
readonly saveDebounced: (value: A) => Effect.Effect<void>;
readonly subscribe: Stream.Stream<M>;
}
PersistenceFailure
export type PersistenceFailure = {
readonly _tag: 'PersistenceFailure';
readonly operation: 'Restore' | 'Save' | 'Migrate' | 'Sync';
readonly reason: string;
};
prefetchOnIntent
export declare function prefetchOnIntent<Pages extends Record<string, AnyPage>, KitMessage extends object>(binding: Pick<KitBinding<Pages, KitMessage>, 'messages'>, key: keyof Pages & string, h: HtmlBuilder<KitMessage>): ReadonlyArray<Attribute<KitMessage>>;
prefetchOnVisible
export declare function prefetchOnVisible<Pages extends Record<string, AnyPage>, KitMessage extends object>(binding: Pick<KitBinding<Pages, KitMessage>, 'messages'>, key: keyof Pages & string): Extract<Attribute<KitMessage>, {
readonly _tag: 'OnMount';
}>;
PrefetchSource
export type PrefetchSource = 'intent' | 'visible';
projectConstraintValidity
export declare function projectConstraintValidity(control: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement, errorId: string, result: ValidationResult): Result.Result<void, ValidationProjectionError>;
PwaEvent
export type PwaEvent = typeof PwaEvent.Type;
PwaEvent
PwaEvent: import("@wsagency/wseffect-foldkit/schema").TaggedUnion<{
readonly UpdateAvailable: {};
readonly OfflineReady: {};
readonly RegisterFailed: {
reason: Schema.String;
};
readonly ChangedOnlineStatus: {
isOnline: Schema.Boolean;
};
}>
PwaState
export type PwaState = typeof PwaState.Type;
PwaState
PwaState: Schema.Struct<{
readonly isOnline: Schema.Boolean;
readonly isOfflineReady: Schema.Boolean;
readonly isUpdateAvailable: Schema.Boolean;
readonly maybeNewBuildId: Schema.Option<Schema.String>;
}>
resizeObserverMount
Observes read-only dimensions, coalesces to one frame, and does not prevent oscillation caused by consumer layout writes.
export declare function resizeObserverMount<M>(toMessage: (result: ResizeResult) => M): Mount.MountAction<M>;
ResizeResult
export type ResizeResult = {
readonly _tag: 'Resized';
readonly width: number;
readonly height: number;
} | {
readonly _tag: 'ResizeUnavailable' | 'ResizeFailure';
readonly reason?: string;
};
scrollIntoViewCommand
export declare function scrollIntoViewCommand<M>(id: string, options: ScrollIntoViewOptions, toMessage: (result: BrowserCommandResult) => M): Command.Command<M, never>;
ServicesOf
export type ServicesOf<P> = P extends PageDefinition<any, any, any, any, infer R> ? R : never;
ServiceWorker
export declare class ServiceWorker extends ServiceWorker_base {
static get layer(): Layer.Layer<ServiceWorker>;
}
ServiceWorkerUpdateError
export declare class ServiceWorkerUpdateError extends ServiceWorkerUpdateError_base<{
readonly cause: unknown;
}> {
}
setRouteLoadInFlight
export declare function setRouteLoadInFlight(messages: object, isLoading: boolean): void;
SignalBackoff
export interface SignalBackoff {
readonly delaysMs: ReadonlyArray<number>;
readonly jitter: number;
}
SignalOutcome
export type SignalOutcome<A> = {
readonly _tag: 'SignalPatch';
readonly value: A;
readonly onlyIfMissing: boolean;
} | {
readonly _tag: 'RejectedSignalPatch';
readonly reason: 'MalformedJson' | 'UnsupportedEvent' | 'UnsupportedOperation' | 'SchemaFailure';
} | {
readonly _tag: 'SignalTransportFailure';
readonly reason: 'Network' | 'Interrupted';
};
signalSubscription
Subscribes to the JSON-only Datastar `patch-signals` SSE subset.
Reconnection uses `SignalBackoff` for both transports; SSE `id:` and
`retry:` fields are ignored, and EventSource closes on error so neither
Last-Event-ID nor the server retry interval is used.
EventSource observes only `datastar-patch-signals` and the default
`message` event; other named events are platform-unobservable and not
reported. Fetch reports every unsupported event, so choose Fetch when
complete rejection reporting is required.
export declare function signalSubscription<A, M>(config: {
readonly schema: Schema.Codec<A, any, never, never>;
readonly transport: SignalTransport;
readonly backoff?: SignalBackoff;
readonly toMessage: (outcome: SignalOutcome<A>) => M;
}): Subscription.Subscription<unknown, M, Record<string, never>>;
SignalTransport
export type SignalTransport = {
readonly _tag: 'EventSource';
readonly url: string;
readonly withCredentials?: boolean;
} | {
readonly _tag: 'Fetch';
readonly url: string;
readonly init?: RequestInit;
};
Slot
Slot: {
Idle: PageSlot<never>;
Available: PageSlot<never>;
Loading: PageSlot<never>;
failed: (cause: FailureCause, reason: string) => PageSlot<never>;
ready: <Model>(model: Model) => PageSlot<Model>;
dehydrated: (encoded: SchemaTypes.Json) => PageSlot<never>;
}
slotsSchema
export declare function slotsSchema<Pages extends Record<string, AnyPage>>(pages: PagesHandle<Pages>): SchemaTypes.Codec<PageSlots<Pages>, any, never, never>;
ValidationProjectionError
export type ValidationProjectionError = {
readonly _tag: 'InvalidControl';
};
ValidationResult
export type ValidationResult = {
readonly _tag: 'Valid';
} | {
readonly _tag: 'Invalid';
readonly message: string;
};
versionPollSubscription
export declare function versionPollSubscription<Message>(config: VersionPollConfig<Message>): {
readonly 'wseffect:version-poll': Subscription.EntryWithoutKeepAlive<unknown, Message, {}, never> & {
readonly __subscription: never;
};
};
viewPage
export declare function viewPage<Pages extends Record<string, AnyPage>, KitMessage extends object>(config: {
readonly pages: PagesHandle<Pages>;
readonly toParentMessage: {
readonly [Key in keyof Pages]: (message: MessageOf<Pages[Key]>) => KitMessage;
};
readonly messages: PageViewMessages<Pages, KitMessage>;
}): Submodel.View<KitState<Pages>, KitMessage, KitPageViewInputs<Pages>>;