@microsoft/rayfin-app-state-fabric 1.35.0-alpha.1412

package/dist/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Public types for the deep-link application state client.
+ */
+/**
+ * A single JSON-compatible value permitted inside {@link FabricAppState}.
+ *
+ * `undefined`, functions, symbols, `NaN`, and `Infinity` are excluded
+ * because they cannot survive a JSON round trip through the URL.
+ */
+export type FabricAppStateValue = string | number | boolean | null | FabricAppStateValue[] | {
+    [key: string]: FabricAppStateValue;
+};
+/**
+ * Application state persisted into the shareable Fabric portal URL.
+ *
+ * **Never place secrets, access tokens, or personal data here.** The
+ * value is visible in browser history, screenshots, copied links,
+ * corporate proxy logs, and anywhere the link is pasted.  Use an opaque
+ * identifier that maps to server-side data when the state is sensitive
+ * or large.
+ */
+export interface FabricAppState {
+    [key: string]: FabricAppStateValue;
+}
+/** Options accepted by `createFabricAppStateClient`. */
+export interface FabricAppStateClientOptions {
+    /** Host window. Defaults to `window.parent`. */
+    target?: Window;
+    /**
+     * Expected origin of the Fabric host.
+     *
+     * Strongly recommended.  When omitted, messages are posted with `"*"`
+     * and inbound events are not origin-checked.
+     */
+    targetOrigin?: string;
+    /** Per-request timeout in milliseconds. Defaults to the bridge default. */
+    timeoutMs?: number;
+    /** Override for the default encoded-size ceiling. */
+    maxEncodedBytes?: number;
+    /** Override for the default nesting-depth ceiling. */
+    maxDepth?: number;
+    /**
+     * Query string to read seeded launch state from.
+     *
+     * Defaults to the live `window.location.search`.  Injectable for
+     * tests and for hosts that supply the value by another route.
+     */
+    launchSearch?: string;
+    /**
+     * Whether to remove the seeded parameter from the app's own URL once
+     * it has been read. Defaults to `true`.
+     *
+     * Leaving it in place would resend the state to the app's own server
+     * on every reload and expose it in referrers to subresources.
+     */
+    scrubLaunchParam?: boolean;
+}
+/**
+ * Limits and features reported by the Fabric host.
+ *
+ * The host is authoritative. The client's own limits exist only to fail
+ * fast before a round trip, so treat these values as the real contract.
+ */
+export interface FabricAppStateCapabilities {
+    /** App-state protocol version implemented by the host. */
+    version: number;
+    /** Largest encoded state the host will accept, in bytes. */
+    maxEncodedBytes: number;
+    /** Deepest nesting the host will accept. */
+    maxDepth: number;
+    /**
+     * Whether the host can create browser history entries.
+     *
+     * When `false`, {@link FabricAppStateClient.setState} still updates the
+     * URL — so links stay shareable — but no history entry is created and
+     * in-app Back and Forward will not work. Hide affordances that depend
+     * on history when this is `false`.
+     */
+    canPush: boolean;
+}
+/**
+ * Listener invoked when the host reports externally-changed state.
+ *
+ * Receives `undefined` when navigation reaches a URL that carries no
+ * state, which means the app should restore its own defaults. Treat the
+ * value as untrusted: anyone can edit a link before sharing it.
+ */
+export type FabricAppStateListener = (state: FabricAppState | undefined) => void;
+/**
+ * Typed client for reading and writing deep-link state.
+ */
+export interface FabricAppStateClient {
+    /**
+     * Read the state the app was launched with.
+     *
+     * Returns `undefined` when the URL carries no state, which is the
+     * normal case for a fresh navigation.
+     *
+     * Resolves **synchronously** from the seeded iframe URL when the host
+     * supports it, so awaiting this does not delay first render.  Falls
+     * back to a bridge round trip only on hosts that do not seed the URL.
+     *
+     * Use {@link FabricAppStateClient.getLaunchStateSync} when the state
+     * is needed in a code path that cannot be asynchronous at all.
+     */
+    getLaunchState(): Promise<FabricAppState | undefined>;
+    /**
+     * Read seeded launch state without awaiting.
+     *
+     * Returns `undefined` when the host did not seed the URL, in which
+     * case {@link FabricAppStateClient.getLaunchState} must be awaited.
+     * Intended for the first render path, where launch state must be
+     * available before paint.
+     */
+    getLaunchStateSync(): FabricAppState | undefined;
+    /**
+     * Resolve the host's capabilities, or `undefined` when the host does
+     * not support deep-link state.
+     *
+     * Deep linking rolls out per tenant, so check this before showing a
+     * share button rather than letting the user click one that cannot
+     * work. The result is cached.
+     *
+     * @example
+     * ```ts
+     * const capabilities = await appState.isSupported();
+     * if (capabilities?.canPush) enableBackForwardHints();
+     * ```
+     */
+    isSupported(): Promise<FabricAppStateCapabilities | undefined>;
+    /**
+     * Commit state as a new browser history entry.
+     *
+     * Choose between this and {@link FabricAppStateClient.replaceState} by
+     * **who caused the change**:
+     *
+     * - The *user* caused it — a click, a filter change, opening a record.
+     *   Use `setState`, so Back returns them to where they were.
+     * - The *app* caused it — restoring, reconciling, or normalising state
+     *   the user did not ask for. Use `replaceState`, so Back is not
+     *   cluttered with entries the user never navigated to.
+     *
+     * @example
+     * ```ts
+     * // The user picked a region: Back should undo it.
+     * await appState.setState({ view: 'sales', region: 'AT' });
+     * ```
+     */
+    setState(state: FabricAppState): Promise<void>;
+    /**
+     * Commit state by replacing the current history entry.
+     *
+     * Use for app-initiated changes and for high-frequency updates such as
+     * a slider drag, where one history entry per update would make Back
+     * unusable.  See {@link FabricAppStateClient.setState} for the rule.
+     *
+     * **Platform caveat:** the Fabric host downgrades a replace to a push
+     * when the previous history entry belongs to a different extension, to
+     * stop one extension overwriting another's history.  The first
+     * `replaceState()` after the user arrives from elsewhere in Fabric may
+     * therefore create an entry.  This is platform behaviour and cannot be
+     * overridden.
+     *
+     * @example
+     * ```ts
+     * // Continuous updates while dragging: do not grow history.
+     * await appState.replaceState({ view: 'sales', threshold: value });
+     * ```
+     */
+    replaceState(state: FabricAppState): Promise<void>;
+    /**
+     * Observe state changes the app did not initiate: browser Back or
+     * Forward, or a deep link opened in the current tab.
+     *
+     * Echoes of the app's own writes are suppressed by the host.
+     *
+     * @returns An unsubscribe function.
+     */
+    onStateChange(listener: FabricAppStateListener): () => void;
+    /** Remove all listeners and release the underlying bridge subscription. */
+    dispose(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Public types for the deep-link application state client.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/validation.d.ts

@@ -0,0 +1,23 @@
+/**
+ * State validation: what may be stored, how large, and how deeply
+ * nested.
+ */
+import type { FabricAppState } from './types.js';
+/**
+ * Default ceiling on the *encoded* state, in bytes.
+ *
+ * Shared links must survive corporate proxies, mail gateways, Teams, and
+ * SharePoint, which commonly truncate beyond roughly 8 000 characters.
+ * The canonical item path plus existing portal parameters already
+ * consume several hundred, so 4 KiB of encoded state leaves headroom.
+ */
+export declare const DEFAULT_MAX_ENCODED_BYTES = 4096;
+/** Default ceiling on nesting depth; the root object counts as depth 1. */
+export declare const DEFAULT_MAX_DEPTH = 20;
+/**
+ * Validate a state object and return its serialised form.
+ *
+ * @internal Exported for unit tests.
+ */
+export declare function validateAppState(state: FabricAppState, maxEncodedBytes: number, maxDepth: number): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.js

@@ -0,0 +1,117 @@
+/**
+ * State validation: what may be stored, how large, and how deeply
+ * nested.
+ */
+import { FabricAppStateError } from './errors.js';
+import { LAUNCH_STATE_PREFIX } from './launchState.js';
+/**
+ * Default ceiling on the *encoded* state, in bytes.
+ *
+ * Shared links must survive corporate proxies, mail gateways, Teams, and
+ * SharePoint, which commonly truncate beyond roughly 8 000 characters.
+ * The canonical item path plus existing portal parameters already
+ * consume several hundred, so 4 KiB of encoded state leaves headroom.
+ */
+export const DEFAULT_MAX_ENCODED_BYTES = 4096;
+/** Default ceiling on nesting depth; the root object counts as depth 1. */
+export const DEFAULT_MAX_DEPTH = 20;
+/**
+ * base64url expands binary by 4/3, so the raw JSON budget is three
+ * quarters of the encoded budget.  Validating against the raw size lets
+ * the SDK fail fast without duplicating the host's encoder.
+ */
+const BASE64_EXPANSION_NUMERATOR = 3;
+const BASE64_EXPANSION_DENOMINATOR = 4;
+/**
+ * Reject values that cannot survive a JSON round trip, and enforce the
+ * depth limit.
+ *
+ * `JSON.stringify` is not sufficient on its own: it *silently drops*
+ * `undefined` and function-valued properties rather than failing, which
+ * would let an app believe it saved state that never reached the URL.
+ * The explicit walk also produces an actionable error path.
+ *
+ * @param seen - Ancestors on the current branch, used for cycle
+ *   detection.  A `Set` of the current path is correct here; a global
+ *   `WeakSet` would wrongly reject the same object appearing twice as
+ *   siblings, which serialises fine.
+ */
+function assertSerializable(value, path, depth, maxDepth, seen) {
+    if (value === null)
+        return;
+    const type = typeof value;
+    if (type === 'string' || type === 'boolean')
+        return;
+    if (type === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new FabricAppStateError(`State value at "${path}" is NaN or Infinity, which cannot be represented in JSON.`, 'INVALID_STATE');
+        }
+        return;
+    }
+    if (type === 'undefined') {
+        throw new FabricAppStateError(`State value at "${path}" is undefined. Omit the property or use null.`, 'INVALID_STATE');
+    }
+    if (type === 'function' || type === 'symbol' || type === 'bigint') {
+        throw new FabricAppStateError(`State value at "${path}" is of unsupported type "${type}".`, 'INVALID_STATE');
+    }
+    // Objects and arrays from here on.
+    if (depth > maxDepth) {
+        throw new FabricAppStateError(`State nesting exceeds the maximum depth of ${maxDepth} at "${path}".`, 'STATE_TOO_DEEP');
+    }
+    const obj = value;
+    if (seen.has(obj)) {
+        throw new FabricAppStateError(`State contains a circular reference at "${path}".`, 'INVALID_STATE');
+    }
+    // Dates, Maps, Sets, and class instances all survive structuredClone
+    // but lose their identity through JSON, so reject them explicitly
+    // rather than silently degrading them to {} or an ISO string.
+    if (!Array.isArray(obj) && Object.getPrototypeOf(obj) !== Object.prototype) {
+        throw new FabricAppStateError(`State value at "${path}" must be a plain object or array.`, 'INVALID_STATE');
+    }
+    seen.add(obj);
+    if (Array.isArray(obj)) {
+        // Indexed rather than `forEach`, which skips holes. `JSON.stringify`
+        // turns a hole into `null`, so skipping one would silently change the
+        // state the app believes it saved.
+        for (let index = 0; index < obj.length; index++) {
+            if (!(index in obj)) {
+                throw new FabricAppStateError(`State value at "${path}[${index}]" is an empty slot in a sparse array, which JSON turns into null. Use null explicitly.`, 'INVALID_STATE');
+            }
+            assertSerializable(obj[index], `${path}[${index}]`, depth + 1, maxDepth, seen);
+        }
+    }
+    else {
+        for (const [key, item] of Object.entries(obj)) {
+            assertSerializable(item, `${path}.${key}`, depth + 1, maxDepth, seen);
+        }
+    }
+    seen.delete(obj);
+}
+/**
+ * Validate a state object and return its serialised form.
+ *
+ * @internal Exported for unit tests.
+ */
+export function validateAppState(state, maxEncodedBytes, maxDepth) {
+    if (typeof state !== 'object' ||
+        state === null ||
+        Array.isArray(state) ||
+        Object.getPrototypeOf(state) !== Object.prototype) {
+        throw new FabricAppStateError('State must be a plain object.', 'INVALID_STATE');
+    }
+    assertSerializable(state, 'state', 1, maxDepth, new Set());
+    const json = JSON.stringify(state);
+    // The host measures the prefix as part of its budget, so leaving it out
+    // here would pass states the host then rejects on the round trip.
+    const rawBudget = Math.floor(((maxEncodedBytes - LAUNCH_STATE_PREFIX.length) *
+        BASE64_EXPANSION_NUMERATOR) /
+        BASE64_EXPANSION_DENOMINATOR);
+    const byteLength = new TextEncoder().encode(json).length;
+    if (byteLength > rawBudget) {
+        throw new FabricAppStateError(`State is ${byteLength} bytes, which exceeds the ${rawBudget}-byte limit ` +
+            `(${maxEncodedBytes} bytes once encoded). Store large state server-side ` +
+            `and put an identifier in the URL instead.`, 'STATE_TOO_LARGE');
+    }
+    return json;
+}
+//# sourceMappingURL=validation.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@microsoft/rayfin-app-state-fabric",
+  "version": "1.35.0-alpha.1412",
+  "description": "Deep-link application state for Rayfin apps embedded in the Fabric portal",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "assets/docs/**/*.md",
+    "!dist/**/__tests__/**",
+    "LICENSE"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@microsoft/fabric-embedded-host": "1.35.0-alpha.1412",
+    "@microsoft/rayfin-lib": "1.35.0-alpha.1412"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "@vitest/coverage-v8": "~3.2.4",
+    "rimraf": "~6.0.1"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "rayfinDocs": {
+    "version": 1,
+    "dir": "assets/docs",
+    "module": "rayfin-app-state-fabric",
+    "kind": "api-reference"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rayfin.git",
+    "directory": "packages/typescript-sdk/app-state-fabric"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc && node ../scripts/fix-esm-extensions.mjs ./dist",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist && rimraf .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}