@expofp/resolve 3.11.11 → 3.12.0

package/dist/resolve.d.ts

@@ -1,3 +1,24 @@
 import { type Ref, type ResolveOptions } from './types.js';
+/**
+ * Resolve a `$ref` to its document. Non-ref values pass through (they ARE the
+ * value). A ref carrying a `process` hook has it applied to the raw document —
+ * that is the whole extension surface; this package knows nothing about
+ * schemas or assets. The result is deep-frozen and memoized by `$ref` for the
+ * sync {@link getResolved}; repeated resolves of the same ref reuse the fetch
+ * cache, so they cost no extra network round-trip. The memo is keyed by URL
+ * alone — resolving the same URL through refs with different `process` hooks
+ * settles whichever ran last.
+ */
 export declare function resolve<T>(data: Ref<T> | T, options?: ResolveOptions): Promise<T>;
+/**
+ * The settled value of an already-resolved `$ref`, synchronously. Throws when
+ * the ref has not settled (never resolved, still in flight, or failed) — a
+ * boot-ordering mistake that should surface loudly. Non-ref values pass
+ * through. Probe with {@link isResolved} where absence is expected.
+ */
+export declare function getResolved<T>(data: Ref<T> | T): T;
+/** Whether {@link getResolved} would succeed. Non-ref values are always "resolved". */
+export declare function isResolved(data: unknown): boolean;
+/** Drop every cached fetch and settled value (tests; long-lived kiosk refreshes). */
+export declare function clearResolveCache(): void;
 //# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.js

@@ -1,17 +1,94 @@
-import { importJson } from '@expofp/utils';
+import { deepFreeze, importJsAsJson, importJson } from '@expofp/utils';
 const globalResolveCache = new Map();
+/** Settled results by `$ref` — the sync {@link getResolved} reads these. */
+const settledValues = new Map();
+/**
+ * Resolve a `$ref` to its document. Non-ref values pass through (they ARE the
+ * value). A ref carrying a `process` hook has it applied to the raw document —
+ * that is the whole extension surface; this package knows nothing about
+ * schemas or assets. The result is deep-frozen and memoized by `$ref` for the
+ * sync {@link getResolved}; repeated resolves of the same ref reuse the fetch
+ * cache, so they cost no extra network round-trip. The memo is keyed by URL
+ * alone — resolving the same URL through refs with different `process` hooks
+ * settles whichever ran last.
+ */
 // TODO: use json pointer lib to resolve within documents
 export async function resolve(data, options) {
-    const importOptions = {
-        fetchCache: options?.refCache ?? globalResolveCache,
-        forceFetch: options?.forceFetch,
-        signal: options?.signal,
-        importCallback: options?.importCallback,
-    };
-    if (typeof data !== 'object' || data === null || !('$ref' in data)) {
+    if (!isRefShaped(data)) {
         return data;
-        // throw new Error('resolve: data is not a $ref object');
     }
-    const module = await importJson(data.$ref, importOptions);
-    return module;
+    const ref = data.$ref;
+    // Legacy `.js` refs (`data.js`, `fp.svg.js`, …) are scripts that assign
+    // browser globals rather than being JSON documents. Evaluate them and
+    // return the assigned globals.
+    const raw = await (isJsRef(ref)
+        ? resolveJsRef(ref, options)
+        : importJson(ref, {
+            fetchCache: options?.refCache ?? globalResolveCache,
+            forceFetch: options?.forceFetch,
+            signal: options?.signal,
+            importCallback: options?.importCallback,
+        }));
+    const value = data.process ? await data.process(raw, ref) : raw;
+    deepFreeze(value);
+    settledValues.set(ref, value);
+    return value;
+}
+/**
+ * The settled value of an already-resolved `$ref`, synchronously. Throws when
+ * the ref has not settled (never resolved, still in flight, or failed) — a
+ * boot-ordering mistake that should surface loudly. Non-ref values pass
+ * through. Probe with {@link isResolved} where absence is expected.
+ */
+export function getResolved(data) {
+    if (!isRefShaped(data)) {
+        return data;
+    }
+    if (!settledValues.has(data.$ref)) {
+        throw new Error(`resolve: $ref not resolved yet: ${data.$ref}`);
+    }
+    return settledValues.get(data.$ref);
+}
+/** Whether {@link getResolved} would succeed. Non-ref values are always "resolved". */
+export function isResolved(data) {
+    return isRefShaped(data) ? settledValues.has(data.$ref) : true;
+}
+/** Drop every cached fetch and settled value (tests; long-lived kiosk refreshes). */
+export function clearResolveCache() {
+    globalResolveCache.clear();
+    settledValues.clear();
+}
+function isRefShaped(data) {
+    return (typeof data === 'object' && data !== null && '$ref' in data && typeof data.$ref === 'string');
+}
+/**
+ * Matches a `.js` path — bare (`…/data.js`) or with a query/hash
+ * (`…/data.js?v=1`). Anchored to the `.js` extension, not a substring test, so
+ * `.json` refs are left alone.
+ */
+function isJsRef(ref) {
+    return /\.js(\?|#|$)/i.test(ref);
+}
+/** Evaluate a legacy `.js` ref to its globals, deduped through the ref cache. */
+function resolveJsRef(ref, options) {
+    const cache = options?.refCache ?? globalResolveCache;
+    const cacheKey = '__loadJs__' + ref;
+    let promise = options?.forceFetch ? undefined : cache.get(cacheKey);
+    if (!promise) {
+        const fetched = importJsAsJson(ref, { signal: options?.signal });
+        cache.set(cacheKey, fetched);
+        // A rejection must not poison the URL for the cache's life (one transient
+        // fetch drop would replay as a permanent failure) — evict it so the next
+        // resolve retries. Guarded: a forceFetch may have replaced the entry.
+        fetched.catch(() => {
+            if (cache.get(cacheKey) === fetched)
+                cache.delete(cacheKey);
+        });
+        promise = fetched;
+    }
+    // Fire importCallback once per resolve call (after load), mirroring importJson.
+    return promise.then((result) => {
+        options?.importCallback?.(ref);
+        return result;
+    });
 }

package/dist/types.d.ts

@@ -1,5 +1,12 @@
 export interface Ref<T> {
     $ref: string;
+    /**
+     * Post-resolution hook: turns the raw fetched/evaluated document into the
+     * value to memoize (validate, absolutize resource URLs, …). Attached in
+     * code by whoever mints the ref — `JSON.stringify` drops it, so serialized
+     * refs stay plain `{ $ref }` data.
+     */
+    process?: (raw: unknown, refUrl: string) => unknown;
     __type?: T;
 }
 export type RefTarget<R> = R extends Ref<infer T> ? T : never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expofp/resolve",
-  "version": "3.11.11",
+  "version": "3.12.0",
   "type": "module",
   "description": "ExpoFP SDK internal: asset and resource resolution",
   "homepage": "https://developer.expofp.com/",
@@ -27,6 +27,6 @@
   ],
   "dependencies": {
     "tslib": "^2.3.0",
-    "@expofp/utils": "3.11.11"
+    "@expofp/utils": "3.12.0"
   }
 }