@byamoah/studio-state 0.0.0-stage → 0.1.0-beta.0

package/delivery.d.ts

@@ -0,0 +1,47 @@
+import { type ContentContract } from "./delivery-contract.js";
+export interface ContentStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+export interface DeliveryState<D> {
+  phase?: "hydrating" | "fetching" | "preparing" | "idle";
+  channel?: "draft" | "published" | "unknown";
+  checkedAt?: number | null;
+  document: D | null;
+  ready: boolean;
+  source: "none" | "bundled" | "cache" | "remote" | "development" | "published";
+  revision: string | null;
+  hydrated: boolean;
+  refreshing: boolean;
+  error: string | null;
+}
+export interface DeliveryOptions<D> extends ContentContract<D> {
+  endpoint?: string;
+  initialContent?: D;
+  mode?: "development" | "production";
+  storage: ContentStorage;
+  allowHttp?: boolean;
+  timeoutMs?: number;
+  maxCharacters?: number;
+  fetch?: typeof fetch;
+  /** Resolve/cache required media before a newly downloaded revision is activated. */
+  prepare?: (document: D, signal: AbortSignal) => Promise<void>;
+}
+export declare function createContentClient<D>(options: DeliveryOptions<D>): {
+  cacheKey: string;
+  getSnapshot: () => DeliveryState<D>;
+  subscribe(listener: () => void): () => void;
+  start(): Promise<void>;
+  refresh(): Promise<void>;
+  stop(): void;
+};
+
+export type ContentClient<D> = ReturnType<typeof createContentClient<D>>;
+
+export { validateRevision } from "./delivery-contract.js";
+export type { ContentContract, ContentRevision } from "./delivery-contract.js";
+
+export function studioDevelopmentEndpoint(
+  link: string | null,
+  development: boolean,
+): string | null | undefined;

package/delivery.js

@@ -0,0 +1,256 @@
+import { validateRevision } from "./delivery-contract.js";
+
+export function createContentClient(options) {
+  if (
+    !/^[a-z0-9][a-z0-9-]*$/.test(options.projectId) ||
+    !Number.isSafeInteger(options.schemaVersion) ||
+    options.schemaVersion < 1 ||
+    ((options.initialContent ?? options.defaults) !== undefined &&
+      options.validate(options.initialContent ?? options.defaults).length)
+  )
+    throw new Error("Invalid content delivery configuration.");
+  if (
+    options.contractId !== undefined &&
+    !/^[a-f0-9]{64}$/.test(options.contractId)
+  )
+    throw new Error("Invalid Studio contract identity.");
+  const initial = options.initialContent ?? options.defaults;
+  const endpoint = options.endpoint ? new URL(options.endpoint) : null;
+  if (
+    endpoint &&
+    (endpoint.username ||
+      endpoint.password ||
+      endpoint.hash ||
+      (endpoint.protocol !== "https:" &&
+        !(options.allowHttp && endpoint.protocol === "http:")))
+  )
+    throw new Error(
+      "Content delivery requires a credential-free HTTPS endpoint.",
+    );
+  if (endpoint) {
+    endpoint.searchParams.set("projectId", options.projectId);
+    if (options.contractId)
+      endpoint.searchParams.set("contractId", options.contractId);
+  }
+  const cacheKey = `studio:content:${options.projectId}:${options.schemaVersion}:${options.contractId ?? "legacy"}:${options.mode ?? "remote"}:${endpoint?.href ?? "bundled"}`;
+  const max = options.maxCharacters ?? 4_000_000;
+  let state = {
+    phase: endpoint ? "hydrating" : "idle",
+    channel: options.mode === "development" ? "draft" : options.mode === "production" ? "published" : "unknown",
+    checkedAt: null,
+    document: initial ?? null,
+    ready: initial !== undefined,
+    source: initial === undefined ? "none" : "bundled",
+    revision: null,
+    hydrated: !endpoint,
+    refreshing: false,
+    error:
+      !endpoint && initial === undefined
+        ? "No Studio content endpoint configured."
+        : null,
+  };
+  const listeners = new Set();
+  let generation = 0,
+    active = null;
+  let starting = null,
+    refreshing = null;
+  const emit = (patch) => {
+    state = { ...state, ...patch };
+    for (const listener of listeners) listener();
+  };
+  const decode = (raw) => {
+    if (raw.length > max)
+      throw new Error("Content revision exceeds the size limit.");
+    return validateRevision(JSON.parse(raw), options);
+  };
+  const bounded = (task, signal) =>
+    new Promise((resolve, reject) => {
+      const abort = () =>
+        reject(new Error("Content request timed out or was cancelled."));
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener("abort", abort, { once: true });
+      task
+        .then(resolve, reject)
+        .finally(() => signal.removeEventListener("abort", abort));
+    });
+  async function request(epoch) {
+    if (!endpoint || epoch !== generation) return;
+    const controller = new AbortController();
+    active = controller;
+    const timer = setTimeout(
+      () => controller.abort(),
+      options.timeoutMs ?? 8000,
+    );
+    emit({ refreshing: true, phase: "fetching", error: null });
+    try {
+      const response = await bounded(
+        (options.fetch ?? fetch)(endpoint.href, {
+          signal: controller.signal,
+          headers: state.revision
+            ? { "If-None-Match": `"${state.revision}"` }
+            : {},
+          cache: "no-cache",
+        }),
+        controller.signal,
+      );
+      if (response.status === 304) {
+        if (!state.revision)
+          throw new Error(
+            "Server returned unchanged content without a local revision.",
+          );
+        return;
+      }
+      if (!response.ok)
+        throw new Error(`Content service returned ${response.status}.`);
+      const raw = await bounded(response.text(), controller.signal);
+      const revision = decode(raw);
+      // Never compare revision ordering: selecting an older immutable revision is a valid rollback.
+      if (revision.revision === state.revision) return;
+      if (options.prepare) {
+        emit({ phase: "preparing" });
+        await bounded(
+          options.prepare(revision.document, controller.signal),
+          controller.signal,
+        );
+      }
+      if (controller.signal.aborted || epoch !== generation) return;
+      let storageError = null;
+      try {
+        await bounded(
+          options.storage.setItem(cacheKey, JSON.stringify(revision)),
+          controller.signal,
+        );
+      } catch {
+        storageError = "Content updated, but offline storage is unavailable.";
+      }
+      if (controller.signal.aborted || epoch !== generation) return;
+      emit({
+        document: revision.document,
+        ready: true,
+        revision: revision.revision,
+        source:
+          options.mode === "development"
+            ? "development"
+            : options.mode === "production"
+              ? "published"
+              : "remote",
+        error: storageError,
+      });
+    } catch (error) {
+      if (epoch === generation)
+        emit({
+          error:
+            error instanceof Error ? error.message : "Content refresh failed.",
+        });
+    } finally {
+      clearTimeout(timer);
+      if (active === controller) active = null;
+      if (epoch === generation) emit({ hydrated: true, refreshing: false, phase: "idle", checkedAt: Date.now() });
+    }
+  }
+  async function hydrate(epoch) {
+    if (!endpoint) return;
+    try {
+      // Slow/broken storage must not prevent the network request or bundled fallback.
+      const controller = new AbortController();
+      const timer = setTimeout(
+        () => controller.abort(),
+        options.timeoutMs ?? 8000,
+      );
+      let raw;
+      try {
+        raw = await bounded(
+          options.storage.getItem(cacheKey),
+          controller.signal,
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+      if (raw) {
+        const revision = decode(raw);
+        if (epoch === generation)
+          emit({
+            document: revision.document,
+            ready: true,
+            source: "cache",
+            revision: revision.revision,
+            hydrated: true,
+          });
+      }
+    } catch {
+      /* A corrupt/foreign/unavailable cache never replaces bundled defaults. */
+    }
+    if (epoch === generation) await request(epoch);
+  }
+  return {
+    cacheKey,
+    getSnapshot: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    start() {
+      if (!starting) {
+        const epoch = generation;
+        starting = hydrate(epoch);
+      }
+      return starting;
+    },
+    async refresh() {
+      if (!endpoint) return;
+      const epoch = generation;
+      if (!starting) {
+        starting = hydrate(epoch);
+        await starting;
+        return;
+      }
+      if (!state.hydrated || (state.refreshing && !refreshing)) {
+        await starting;
+        return;
+      }
+      if (epoch !== generation) return;
+      if (!refreshing)
+        refreshing = request(epoch).finally(() => {
+          if (epoch === generation) refreshing = null;
+        });
+      await refreshing;
+    },
+    stop() {
+      generation++;
+      active?.abort();
+      active = null;
+      starting = null;
+      refreshing = null;
+      emit({ refreshing: false, phase: "idle" });
+    },
+  };
+}
+
+export { validateRevision } from "./delivery-contract.js";
+
+export function studioDevelopmentEndpoint(link, development) {
+  if (!development || !link) return;
+  try {
+    const endpoint = new URL(link).searchParams.get("studioDev");
+    if (endpoint === "off") return null;
+    if (!endpoint || endpoint.length > 1500) return;
+    const url = new URL(endpoint);
+    if (
+      !["http:", "https:"].includes(url.protocol) ||
+      url.username ||
+      url.password ||
+      url.hash ||
+      url.search ||
+      !/^\/__studio\/dev\/[a-f0-9]{48}\/content\.json$/.test(url.pathname)
+    )
+      return;
+    return url.href;
+  } catch {
+    return;
+  }
+}

package/index.d.ts

@@ -0,0 +1,102 @@
+export interface StudioField {
+  path: string;
+  type: "text" | "image" | "color" | "number" | "boolean" | "enum" | "array";
+  optional?: boolean;
+  conditions?: Array<Record<string,string>>;
+  itemType?: "string" | "number" | "boolean";
+  min?: number;
+  max?: number;
+  maxLength?: number;
+  values?: (string | number)[];
+}
+export interface StudioContract {
+  contractId?: string;
+  fields: StudioField[];
+  collections?: Record<
+    string,
+    {
+      template?: { id: string; [key: string]: unknown };
+      minItems?: number;
+      maxItems?: number;
+      direction?: "vertical" | "horizontal" | "grid";
+      conditions?: Array<Record<string,string>>;
+      cases?: Array<{types:string[];conditions?:Array<Record<string,string>>}>;
+      ownedCollections?: string[];
+  variants?: Record<string, { label?: string; template: { id: string; type: string; [key: string]: unknown } }>;
+    }
+  >;
+}
+export function defineStudioDefaults<T>(value: T): T;
+export function getStudioValue(value: unknown, path: string): unknown;
+export function validateStudioState(
+  value: unknown,
+  contract: StudioContract,
+): string[];
+
+export function studioItemSegment(id: string): string;
+export function expandStudioPath(document: unknown, pattern: string): string[];
+
+export function duplicateStudioItem(
+  document: unknown,
+  path: string,
+  id: string,
+  options?: {
+    position?: "before" | "after";
+    maxItems?: number;
+    ownedCollections?: string[];
+    createId?: () => string;
+  },
+): string;
+
+export function createStudioItem<T extends { id: string }>(
+  template: T,
+  existing?: unknown[],
+  options?: { ownedCollections?: string[]; createId?: () => string },
+): T;
+export function mergeStudioDefaults<T>(base: T, authored: unknown): T;
+
+export function subscribeStudioReveal(
+  listener: (target: { path: string; id: string }) => void,
+): () => boolean;
+export function requestStudioItemReveal(path: string, id: string): void;
+
+export function moveStudioItem(document: unknown, path: string, id: string, offset: -1 | 1): boolean;
+export function removeStudioItem(document: unknown, path: string, id: string, options?: { minItems?: number }): void;
+
+export interface StudioBlockCollection {
+  conditions?: Array<Record<string,string>>;
+  cases?: Array<{types:string[];conditions?:Array<Record<string,string>>}>;
+  variants?: Record<string, { label?: string; template: { id: string; type: string; [key: string]: unknown } }>;
+  maxItems?: number;
+  ownedCollections?: string[];
+}
+export function insertStudioBlock(document: unknown, path: string, type: string, definition: StudioBlockCollection, options?: {
+  relativeTo?: string;
+  position?: "before" | "after" | "replace";
+  createId?: () => string;
+}): string;
+
+export function matchesStudioConditions(document: unknown, concretePath: string, conditions?: Array<Record<string,string>>): boolean;
+export function studioCollectionPattern(path: string): string;
+export function studioBindingAncestors(path: string): Array<{path:string;id:string}>;
+
+export function studioCollectionDefinition(document: unknown, definitions: StudioContract["collections"], path: string): NonNullable<StudioContract["collections"]>[string] | undefined;
+
+export interface StudioPreset {
+  protocolVersion: 1;
+  id: string;
+  projectId: string;
+  contractId: string;
+  name: string;
+  createdAt: string;
+  sourcePath: string;
+  item: { id: string; [key: string]: unknown };
+}
+export function createStudioPreset(document: unknown, path: string, id: string, options: {projectId:string;contract:StudioContract;name:string}): StudioPreset;
+export function insertStudioPreset(document: unknown,path: string,preset: StudioPreset,options:{projectId:string;contract:StudioContract;relativeTo?:string;position?:"before"|"after"|"replace";createId?:()=>string}): string;
+
+export interface StudioMigrationMapping {from:string;to:string;conversion?:"copy"|"text"|"number"|"boolean";}
+export interface StudioContractChange {scope:"field"|"collection";key:string;path:string;kind:"added"|"removed"|"changed";before?:unknown;after?:unknown;}
+export function studioMigrationFieldKey(field:Pick<StudioField,"path"|"conditions">):string;
+export function compareStudioContracts(previous:StudioContract,next:StudioContract):StudioContractChange[];
+export function previewStudioMigration(source:unknown,document:unknown,previous:StudioContract,next:StudioContract,mappings?:StudioMigrationMapping[]):{document:unknown;changes:Array<{from:string;to:string;before:unknown;after:unknown}>;errors:string[];valid:boolean;};