diff --git a/src/arts/active-app/types.ts b/src/arts/active-app/types.ts index 14b6340..3b8ace5 100644 --- a/src/arts/active-app/types.ts +++ b/src/arts/active-app/types.ts @@ -177,30 +177,25 @@ export interface ActiveAppOptions< */ cache?: Omit; /** - * Defaults for `App.createActiveConnections()`. App injects Logger, - * Timers and Bus automatically. Automatic reactions live in the - * connection registry (`autoReauthOn`), not in App orchestration. + * @deprecated Pair with the deprecated `App.createActiveConnections()`. + * Use `services: { connections: defineActiveConnections(...) }` instead. */ connections?: Omit; /** - * Defaults for `App.createActivePerms()`. App injects Logger, Http - * and Bus automatically; the endpoint remains explicit because the client - * only reflects server decisions. Automatic app-event invalidation is - * controlled by `autoInvalidateOn`. + * @deprecated Pair with the deprecated `App.createActivePerms()`. + * Use `services: { perm: defineActivePerm(...) }` instead. */ permissions?: Omit; /** - * Defaults for `App.createActiveAuth()`. App injects Http and Cache - * automatically; the authoritative auth engine still lives server-side - * under `$svrs/auth`. + * @deprecated Pair with the deprecated `App.createActiveAuth()`. + * Use `services: { auth: defineActiveAuth(...) }` instead. */ auth?: Omit; /** - * Cross-artifact orchestration policy. App always exposes `App.Bus`; - * orchestration only controls translators from module events to stable - * `app.*` events. Destructive reactions are configured in each consumer - * factory (`cache.autoInvalidateOn`, `permissions.autoInvalidateOn`, - * `connections.autoReauthOn`). + * @deprecated The legacy translator system is being replaced by the + * orca-based presets in `arts/active-app/presets/`. Apply + * `applyStandardOrca(App)` after construction to register equivalent + * reactions, or cherry-pick individual presets. */ orchestration?: ActiveAppOrchestrationOptions; } @@ -259,94 +254,59 @@ export interface ActiveAppLegacy { /** * Build an `EngineSium` wired to this App's `Lang`, `Logger` and current - * locale. Sium is not part of the App composition (validation is - * page-scoped); pages that need it call this method to get a one-line - * construction: + * locale. * - * ```ts - * const sium = App.createSiumEngine(); - * const result = await sium.validate(LoginSchema, input); - * ``` - * - * Each call returns a fresh engine. No options accepted — Lang, Logger - * and locale all flow from App. + * @deprecated Declare `sium: defineEngineSium()` in the App service + * schema and use `App.sium` instead. Each `App.sium` access returns the + * same instance; cleanup runs on `App.dispose()`. */ createSiumEngine: () => EngineSium; /** - * Build the App-scoped `ActiveSession`. App injects `App.Logger` - * automatically; the consumer supplies the rest (`schemas`, `storage`, - * `onRefresh`, `onRevoke`, `broadcastChannel`). - * - * Single session per App — the second call throws - * `SessionAlreadyCreatedError`. Multi-account scenarios compose multiple - * App instances. The session is auto-disposed by `App.dispose()`. - * - * Generics let the caller declare the exact shape: + * Build the App-scoped `ActiveSession`. * - * ```ts - * interface User { id: string; email: string } - * interface Credential { accessToken: string; refreshToken: string } - * - * const Sess = App.createActiveSession({ - * schemas: { user: UserSchema }, - * storage: { adapter: localAdapter, key: 'app:session' }, - * onRefresh: async (current) => { - * const r = await App.Http.post('/api/refresh', { - * body: { refreshToken: current.credential.refreshToken } - * }); - * return r.ok ? r.value : null; - * }, - * onRevoke: async (current) => { - * const r = await App.Http.post('/api/logout', { - * body: { refreshToken: current.credential.refreshToken } - * }); - * return r.ok; - * } - * }); - * ``` - * - * `App.Sess` is set as a side effect — pages can read it without - * keeping the return value around. + * @deprecated Declare `session: defineActiveSession({ ... })` + * in the App service schema and use `App.session` instead. The schema- + * driven session is built lazily on first access, gets `App.Logger` and + * `App.Bus` injected automatically, and is disposed by `App.dispose()`. */ createActiveSession( options?: Omit, 'logger' | 'bus'> ): ActiveSession; /** - * Build an App-scoped realtime connection registry. Each call returns a - * fresh registry; App injects `Logger`, `Timers` and `Bus`. Automatic - * reauth is controlled by the registry's `autoReauthOn` option and each - * connection's own `session` option. + * @deprecated Declare `connections: defineActiveConnections({ ... })` + * in the App service schema and use `App.connections` instead. */ createActiveConnections( options?: Omit ): ActiveConnections; /** - * Build the App-scoped reactive permissions client. The authoritative - * runtime is `createEnginePerms()` from `$svrs/perm`; this client - * is only for UI/UX reflection, snapshots and cache. + * @deprecated Declare `perm: defineActivePerm({ endpoint, ... })` in the + * App service schema and use `App.perm` instead. */ createActivePerms( options?: Partial> ): ActivePerms; /** - * Build the App-scoped active authentication client. The server-side - * authority is `createEngineAuth()` from `$svrs/auth`; this client only - * reflects `/api/auth/*` state, sends CSRF headers and exposes pending / - * error state for UI. + * @deprecated Declare `auth: defineActiveAuth({ http, ... })` in the + * App service schema and use `App.auth` instead. */ createActiveAuth(options?: Omit): ActiveAuth; /** * The active session, when one has been built via - * `App.createActiveSession(...)`. `undefined` until then. Pages narrow - * with `if (App.Sess) { ... }`. + * `App.createActiveSession(...)`. `undefined` until then. + * + * @deprecated Use `App.session` (lowercase) declared via + * `services: { session: defineActiveSession(...) }` instead. */ readonly Sess: ActiveSession | undefined; + /** @deprecated Use `App.perm` (lowercase) declared via the schema. */ readonly Perms: ActivePerms | undefined; + /** @deprecated Use `App.auth` (lowercase) declared via the schema. */ readonly Auth: ActiveAuth | undefined; /** Tear down owned instances in reverse construction order. Idempotent. */ diff --git a/src/arts/cache/types.ts b/src/arts/cache/types.ts index 433ea4f..f20d757 100644 --- a/src/arts/cache/types.ts +++ b/src/arts/cache/types.ts @@ -58,10 +58,19 @@ export type ActiveCacheAutoInvalidateOn = | readonly ActiveCacheAutoInvalidateTarget[]; export interface ActiveCacheOptions extends EngineCacheOptions { + /** + * @deprecated Pass through `arts/active-app/presets/applyStandardOrca` + * (or the individual preset `applyCacheClearOnIdentityChange`) instead. + * The internal subscription mechanism is kept temporarily for back- + * compat and will be removed when the ecosystem tests migrate to + * orca-based reactions. + */ readonly bus?: AppEventBus; /** - * Automatic reactions to public app events. Defaults to `'none'` so - * `createActiveApp()` can publish facts without destructive side-effects. + * @deprecated Use the orca preset + * `arts/active-app/presets/applyCacheClearOnIdentityChange` (or the + * aggregator `applyStandardOrca`) instead. The recommended path is to + * leave this option unset and register reactions on `App.Orca`. */ readonly autoInvalidateOn?: ActiveCacheAutoInvalidateOn; } diff --git a/src/arts/perm/types.ts b/src/arts/perm/types.ts index 0d36095..4552b35 100644 --- a/src/arts/perm/types.ts +++ b/src/arts/perm/types.ts @@ -124,10 +124,15 @@ export interface ActivePerms } export interface ActivePermsOptions extends PermClientOptions { + /** + * @deprecated Use the orca preset `applyPermInvalidateOnIdentityChange` + * (or the aggregator `applyStandardOrca`) instead. Kept for back-compat + * until the ecosystem tests migrate to orca. + */ readonly bus?: AppEventBus; /** - * Automatic reactions to public app events. Defaults to `'none'`; the - * permissions client only clears its local cache when explicitly enabled. + * @deprecated Use the orca preset + * `arts/active-app/presets/applyPermInvalidateOnIdentityChange`. */ readonly autoInvalidateOn?: PermAutoInvalidateOn; } diff --git a/src/libs/active-app/events.ts b/src/libs/active-app/events.ts index 211b30d..0697fec 100644 --- a/src/libs/active-app/events.ts +++ b/src/libs/active-app/events.ts @@ -157,6 +157,12 @@ function currentRuntime(): typeof APP_EVENT_RUNTIME_CLIENT | 'server' { return typeof window === 'undefined' ? 'server' : APP_EVENT_RUNTIME_CLIENT; } +/** + * @deprecated The session art publishes `SESSION_EVENT_IDENTITY_CHANGED` + * directly. Subscribe to that event (or use the orca preset + * `applyCacheClearOnIdentityChange` / `applyPermInvalidateOnIdentityChange`) + * instead of republishing as `APP_EVENT_USER_IDENTITY_CHANGED`. + */ export function publishAppUserIdentityChanged( bus: EventPublisher, payload: AppUserIdentityChangedPayload, @@ -167,6 +173,11 @@ export function publishAppUserIdentityChanged( return bus.publish(APP_EVENT_USER_IDENTITY_CHANGED, payload, options); } +/** + * @deprecated `PERMISSIONS_REFRESH_REQUESTED` is a command disguised as an + * event. Call `App.perm.refresh()` (or the legacy `App.Perms?.refresh()`) + * directly instead of routing through the bus. + */ export function publishAppPermsRefreshRequested( bus: EventPublisher, payload: AppPermsRefreshRequestedPayload, @@ -177,6 +188,12 @@ export function publishAppPermsRefreshRequested( return bus.publish(APP_EVENT_PERMISSIONS_REFRESH_REQUESTED, payload, options); } +/** + * @deprecated Tenant switching does not currently have a module owner. + * Apps that switch tenant should expose their own event or call + * `App.cache.clear()` / `App.perm.invalidate()` directly. Slated for + * removal in the orca-based migration. + */ export function publishAppTenantSwitched( bus: EventPublisher, payload: AppTenantSwitchedPayload, @@ -187,6 +204,11 @@ export function publishAppTenantSwitched( return bus.publish(APP_EVENT_TENANT_SWITCHED, payload, options); } +/** + * @deprecated `arts/connection` should publish its own + * `CONNECTION_EVENT_*` and the application orchestrates from there. + * Slated for removal once consumers migrate. + */ export function publishAppConnectivityChanged( bus: EventPublisher, payload: AppConnectivityChangedPayload, @@ -197,6 +219,11 @@ export function publishAppConnectivityChanged( return bus.publish(APP_EVENT_CONNECTIVITY_CHANGED, payload, options); } +/** + * @deprecated `CACHE_INVALIDATE_REQUESTED` is a command disguised as an + * event. Call `App.cache.clear()` / `App.Cache.clear()` directly + * instead of routing through the bus. + */ export function publishAppCacheInvalidateRequested( bus: EventPublisher, payload: AppCacheInvalidateRequestedPayload,