Replace browser alias initialization with loader

Author: James Zhang

packages/aliases/src/browser.ts

@@ -42,7 +42,7 @@ export const DEFAULT_DEPLOYMENT_CONFIG_PATH =
 /** The author's declaration file, so it carries the declared defaults. */
 export const DEFAULT_DECLARATIONS_PATH = "resources.json";
 
-export interface InitAliasesOptions {
+export interface LoadAliasesOptions {
   /**
    * Escape hatch to force one specific file, relative to `document.baseURI`.
    * Setting it disables the fallback, so a missing file throws. Normal
@@ -56,18 +56,36 @@ export interface InitAliasesOptions {
   fetch?: typeof globalThis.fetch;
 }
 
+/** Aliases loaded for this application. */
+export interface LoadedAliases {
+  /** Returns a resolved custom alias. */
+  custom(alias: string): Custom;
+}
+
 let cachedCustomAliases: Record<string, string> | undefined;
 let inFlight: Promise<void> | undefined;
 
+const loadedAliases: LoadedAliases = Object.freeze({ custom });
+
 /**
- * Fetches and caches the resolved aliases for this installation. Call once at
- * application startup and await it before reading any aliases. Repeated calls
- * are deduplicated and become no-ops once the aliases are cached.
+ * Loads and caches the aliases for this installation, then returns a
+ * synchronous reader. Repeated and concurrent calls share the same load.
  *
  * @experimental Exposed only via "@osdk/aliases/experimental". Both custom
  * aliases and the shape of this API are provisional and may change.
  */
-export async function initAliases(options?: InitAliasesOptions): Promise<void> {
+export async function load(
+  options?: LoadAliasesOptions,
+): Promise<LoadedAliases> {
+  await initAliases(options);
+  return loadedAliases;
+}
+
+/**
+ * Populates the alias cache. Concurrent calls share a request, and failed
+ * requests may be retried.
+ */
+export async function initAliases(options?: LoadAliasesOptions): Promise<void> {
   if (cachedCustomAliases !== undefined) {
     return;
   }
@@ -81,12 +99,12 @@ export async function initAliases(options?: InitAliasesOptions): Promise<void> {
   await inFlight;
 }
 
-async function loadAliases(options?: InitAliasesOptions): Promise<void> {
+async function loadAliases(options?: LoadAliasesOptions): Promise<void> {
   const fetchImpl = options?.fetch ?? globalThis.fetch;
   if (typeof fetchImpl !== "function") {
     throw new TypeError(
       "No fetch implementation available to load aliases. Pass one via " +
-        "initAliases({ fetch }).",
+        "Aliases.load({ fetch }).",
     );
   }
 

packages/aliases/src/experimental.test.ts

@@ -19,31 +19,31 @@
 // breaking change for consumers, and that should fail a test rather than pass
 // review unnoticed.
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import * as browser from "./browser.js";
 import { resetAliasesCache } from "./browser.js";
 import {
   Aliases,
-  custom,
   DEFAULT_DECLARATIONS_PATH,
   DEFAULT_DEPLOYMENT_CONFIG_PATH,
-  initAliases,
+  load,
 } from "./public/experimental.js";
 
 const DECLARATIONS = {
   aliases: { custom: { apiBaseUrl: { value: "https://api.example.com" } } },
 };
 
 function mockFetch(): typeof globalThis.fetch {
-  return (() =>
+  return vi.fn(() =>
     Promise.resolve({
       ok: true,
       status: 200,
       statusText: "OK",
       headers: { get: () => "application/json" },
       text: () => Promise.resolve(JSON.stringify(DECLARATIONS)),
-    })) as unknown as typeof globalThis.fetch;
+    }),
+  ) as unknown as typeof globalThis.fetch;
 }
 
 describe("experimental browser entry point", () => {
@@ -52,16 +52,33 @@ describe("experimental browser entry point", () => {
   });
 
   it("exposes the Aliases namespace", async () => {
-    await Aliases.initAliases({ path: "resources.json", fetch: mockFetch() });
+    const aliases = await Aliases.load({
+      path: "resources.json",
+      fetch: mockFetch(),
+    });
 
-    expect(Aliases.custom("apiBaseUrl")).toBe("https://api.example.com");
+    expect(aliases.custom("apiBaseUrl")).toBe("https://api.example.com");
+  });
+
+  it("caches concurrent and repeated loads", async () => {
+    const fetchImpl = mockFetch();
+    const options = { path: "resources.json", fetch: fetchImpl };
+
+    const [first, second] = await Promise.all([
+      Aliases.load(options),
+      Aliases.load(options),
+    ]);
+    const third = await Aliases.load(options);
+
+    expect(first).toBe(second);
+    expect(first).toBe(third);
+    expect(fetchImpl).toHaveBeenCalledOnce();
   });
 
   it("exposes the same members as named exports", () => {
     // Same function identities, not merely same names, so the two styles can
     // never drift apart.
-    expect(Aliases.custom).toBe(custom);
-    expect(Aliases.initAliases).toBe(initAliases);
+    expect(Aliases.load).toBe(load);
     expect(Aliases.DEFAULT_DECLARATIONS_PATH).toBe(DEFAULT_DECLARATIONS_PATH);
     expect(Aliases.DEFAULT_DEPLOYMENT_CONFIG_PATH).toBe(
       DEFAULT_DEPLOYMENT_CONFIG_PATH,
@@ -73,6 +90,7 @@ describe("experimental browser entry point", () => {
     // into a browser bundle.
     expect(Aliases).not.toHaveProperty("dataset");
     expect(Aliases).not.toHaveProperty("source");
+    expect(Aliases).not.toHaveProperty("custom");
   });
 
   it("keeps the test-only cache reset out of the public surface", () => {

packages/aliases/src/public/experimental.ts

@@ -14,47 +14,31 @@
  * limitations under the License.
  */
 
-// EXPERIMENTAL browser-safe alias runtime, for applications served to a browser
-// such as Developer Console apps.
+// Experimental browser-safe aliases for Developer Console apps.
 //
 //   import { Aliases } from "@osdk/aliases/experimental";
-//   await Aliases.initAliases();
-//   const apiBaseUrl = Aliases.custom("apiBaseUrl");
+//   const aliases = await Aliases.load();
+//   const apiBaseUrl = aliases.custom("apiBaseUrl");
 //
-// Behind the "experimental" subpath deliberately: both custom aliases and the
-// shape of this API are provisional, so the import path says so at every call
-// site. Expect it to move to the package root once the design settles, with this
-// subpath deprecated rather than removed.
-//
-// Code running in Node with a filesystem (Functions) wants "@osdk/aliases/node".
+// Functions and other Node runtimes use "@osdk/aliases/node".
 
 import {
-  custom,
   DEFAULT_DECLARATIONS_PATH,
   DEFAULT_DEPLOYMENT_CONFIG_PATH,
-  initAliases,
+  load,
 } from "../browser.js";
 
-// Assembled member by member, not `export * as`, to keep the test-only
-// resetAliasesCache out of the supported surface.
-//
-// Explicitly typed: `--isolatedDeclarations` cannot infer this (TS9016).
+// Explicitly assembled to exclude test helpers. The type annotation is required
+// by `--isolatedDeclarations`.
 export const Aliases: {
-  readonly custom: typeof custom;
-  readonly initAliases: typeof initAliases;
+  readonly load: typeof load;
   readonly DEFAULT_DECLARATIONS_PATH: typeof DEFAULT_DECLARATIONS_PATH;
   readonly DEFAULT_DEPLOYMENT_CONFIG_PATH: typeof DEFAULT_DEPLOYMENT_CONFIG_PATH;
 } = {
-  custom,
-  initAliases,
+  load,
   DEFAULT_DECLARATIONS_PATH,
   DEFAULT_DEPLOYMENT_CONFIG_PATH,
 };
 
-export {
-  custom,
-  DEFAULT_DECLARATIONS_PATH,
-  DEFAULT_DEPLOYMENT_CONFIG_PATH,
-  initAliases,
-};
-export type { Custom, InitAliasesOptions } from "../browser.js";
+export { DEFAULT_DECLARATIONS_PATH, DEFAULT_DEPLOYMENT_CONFIG_PATH, load };
+export type { Custom, LoadAliasesOptions, LoadedAliases } from "../browser.js";