@supernova-studio/client 1.96.6 → 1.96.7

package/src/sync/project-content-repo.ts

@@ -0,0 +1,215 @@
+import { OmitStrict } from "@supernova-studio/model";
+import PQueue from "p-queue";
+import * as Y from "yjs";
+import { DTOForgeProjectAction, DTOForgeProjectActionOfType } from "../api";
+import { ForgeProjectRoomBaseYDoc, ForgeProjectRoomBaseYDocState } from "../yjs";
+import { applyProjectActionsLocally } from "./project-local-action-executor";
+import { ProjectContentState } from "./types";
+
+type YObserver = () => void;
+type ProjectContentObserver = (projectContent: ProjectContentState) => void;
+type ErrorObserver<T> = (error: unknown, actionMetadata: T | undefined) => void;
+
+type TransactionExecutor = (trx: DTOForgeProjectAction) => Promise<void>;
+type InternalTransactionExecutor<T> = (trx: InternalAction<T>) => Promise<void>;
+type TransactionIdGenerator = () => string;
+
+type Action = DTOForgeProjectActionOfType<DTOForgeProjectAction["type"]>;
+type InputAction<T> = OmitStrict<Action, "tId">;
+type InternalAction<T> = { action: Action; metadata?: T };
+
+export class ForgeProjectContentRepository<T> {
+  private userId: string;
+  private projectId: string;
+
+  private readonly yDoc: Y.Doc;
+  private readonly yObserver: YObserver;
+  private _yState: ForgeProjectRoomBaseYDocState | undefined;
+
+  private _currentProjectContent: ProjectContentState | undefined;
+
+  private localActions: DTOForgeProjectAction[] = [];
+  private readonly actionQueue: TransactionQueue<T>;
+  private readonly projectContentObservers = new Set<ProjectContentObserver>();
+  private readonly errorObservers = new Set<ErrorObserver<T>>();
+  private readonly initCallbacks = new Set<() => void>();
+
+  private readonly transactionIdGenerator: TransactionIdGenerator;
+  private readonly transactionExecutor: TransactionExecutor;
+
+  constructor(config: {
+    userId: string;
+    projectId: string;
+    yDoc: Y.Doc;
+    transactionExecutor: TransactionExecutor;
+    transactionIdGenerator: TransactionIdGenerator;
+  }) {
+    this.userId = config.userId;
+    this.projectId = config.projectId;
+    this.yDoc = config.yDoc;
+
+    this.yObserver = this.yDoc.on("update", () => this.onYUpdate()) as YObserver;
+    this.onYUpdate();
+
+    this.transactionExecutor = config.transactionExecutor;
+    this.transactionIdGenerator = config.transactionIdGenerator;
+
+    this.actionQueue = new TransactionQueue(action => this.executeInternalAction(action));
+  }
+
+  //
+  // Lifecycle
+  //
+
+  get isInitialized(): boolean {
+    return !!this._currentProjectContent;
+  }
+
+  onInitialized(): Promise<void> {
+    if (this.isInitialized) return Promise.resolve();
+    return new Promise(resolve => {
+      this.initCallbacks.add(resolve);
+    });
+  }
+
+  addProjectContentObserver(observer: ProjectContentObserver) {
+    this.projectContentObservers.add(observer);
+    if (this._currentProjectContent) observer(this._currentProjectContent);
+  }
+
+  removeProjectContentObserver(observer: ProjectContentObserver) {
+    this.projectContentObservers.delete(observer);
+  }
+
+  addErrorObserver(observer: ErrorObserver<T>) {
+    this.errorObservers.add(observer);
+  }
+
+  removeErrorObserver(observer: ErrorObserver<T>) {
+    this.errorObservers.delete(observer);
+  }
+
+  dispose() {
+    this.yDoc.off("update", this.yObserver);
+    this.projectContentObservers.clear();
+    this.errorObservers.clear();
+    this.actionQueue.clear();
+  }
+
+  //
+  // Accessors
+  //
+
+  get currentProjectContent(): ProjectContentState {
+    const projectContent = this._currentProjectContent;
+    if (!projectContent) throw new Error(`Project content cannot be accessed while it's still loading`);
+    return projectContent;
+  }
+
+  //
+  // Actions
+  //
+
+  executeAction(action: InputAction<T>, metadata?: T) {
+    void this.executeActionPromise(action, metadata);
+  }
+
+  executeActionPromise(action: InputAction<T>, metadata?: T) {
+    const fullAction: DTOForgeProjectAction = { ...action, tId: this.transactionIdGenerator() };
+    this.localActions.push(fullAction);
+    this.refreshProjectContent();
+    return this.actionQueue.enqueue({ action: fullAction, metadata });
+  }
+
+  private async executeInternalAction(action: InternalAction<T>) {
+    try {
+      return await this.transactionExecutor(action.action);
+    } catch (e: unknown) {
+      // Remove this action from local actions and reload projectContent
+      this.localActions = this.localActions.filter(a => a.tId !== action.action.tId);
+      this.refreshProjectContent();
+
+      this.errorObservers.forEach(o => o(e, action.metadata));
+    }
+  }
+
+  //
+  // Reactions
+  //
+
+  private refreshState() {
+    this.refreshProjectContent();
+  }
+
+  private refreshProjectContent() {
+    const yState = this._yState;
+    if (!yState) return;
+
+    // Calculate new project content
+    const projectContent = this.calculateProjectState(yState);
+    if (!projectContent) return;
+    this._currentProjectContent = projectContent;
+
+    // Invoke observers
+    this.projectContentObservers.forEach(o => o(projectContent));
+  }
+
+  private calculateProjectState(yState: ForgeProjectRoomBaseYDocState): ProjectContentState {
+    // Remove local actions that have been applied remotely
+    const executedTransactionIds = new Set(yState.executedTransactionIds);
+    const localActions = this.localActions.filter(a => a.tId && !executedTransactionIds.has(a.tId));
+    this.localActions = localActions;
+
+    // Apply local actions onto the Yjs state
+    const state = applyProjectActionsLocally({
+      userId: this.userId,
+      projectId: this.projectId,
+      remoteState: yState,
+      actions: localActions,
+    });
+
+    return {
+      artifacts: state.artifacts,
+      features: state.features,
+      artifactSections: state.artifactSections,
+      featureSections: state.featureSections,
+      // we don't apply local actions to relations, so we can just use the Yjs state
+      relations: yState.relations,
+    };
+  }
+
+  private onYUpdate() {
+    const newState = new ForgeProjectRoomBaseYDoc(this.yDoc).getState();
+    if (newState.isLoaded) {
+      this._yState = newState;
+      this.refreshState();
+
+      // Flush init callbacks
+      this.initCallbacks.forEach(f => f());
+      this.initCallbacks.clear();
+    }
+  }
+}
+
+class TransactionQueue<T> {
+  private readonly executor: InternalTransactionExecutor<T>;
+  private readonly queue = new PQueue({
+    concurrency: 1,
+  });
+
+  constructor(executor: InternalTransactionExecutor<T>) {
+    this.executor = executor;
+  }
+
+  enqueue(trx: InternalAction<T>) {
+    return this.queue.add(() => this.executor(trx));
+  }
+
+  onEmpty() {
+    return this.queue.onEmpty();
+  }
+
+  clear() {
+    this.queue.clear();
+  }
+}

package/src/sync/project-local-action-executor.ts

@@ -0,0 +1,415 @@
+import { mapByUnique } from "@supernova-studio/model";
+import {
+  DTOForgeProjectAction,
+  DTOForgeProjectActionOfType,
+  DTOForgeProjectArtifact,
+  DTOForgeProjectFeature,
+  DTOForgeSection,
+} from "../api";
+
+//
+// Interface
+//
+
+type Input = LocalExecutorConfig & {
+  actions: DTOForgeProjectAction[];
+};
+
+export function applyProjectActionsLocally(input: Input) {
+  const actionExecutor = new LocalProjectActionExecutor(input);
+  actionExecutor.applyActions(input.actions);
+  return actionExecutor.localState;
+}
+
+//
+// Executor
+//
+
+type LocalExecutorConfig = {
+  userId: string;
+  projectId: string;
+  remoteState: ForgeProjectYDocState;
+};
+
+type ForgeProjectYDocState = {
+  artifacts: DTOForgeProjectArtifact[];
+  features: DTOForgeProjectFeature[];
+  artifactSections: DTOForgeSection[];
+  featureSections: DTOForgeSection[];
+};
+
+export class LocalProjectActionExecutor {
+  private readonly userId: string;
+  private readonly projectId: string;
+
+  private readonly artifacts: Map<string, DTOForgeProjectArtifact>;
+  private readonly features: Map<string, DTOForgeProjectFeature>;
+  private readonly artifactSections: Map<string, DTOForgeSection>;
+  private readonly featureSections: Map<string, DTOForgeSection>;
+
+  constructor(config: LocalExecutorConfig) {
+    const { projectId, remoteState, userId } = config;
+
+    this.userId = userId;
+    this.projectId = projectId;
+
+    // Seed the state with remote state
+    this.artifacts = mapByUnique(remoteState.artifacts, p => p.id);
+    this.features = mapByUnique(remoteState.features, p => p.id);
+    this.artifactSections = mapByUnique(remoteState.artifactSections, p => p.id);
+    this.featureSections = mapByUnique(remoteState.featureSections, p => p.id);
+  }
+
+  get localState() {
+    return {
+      artifacts: Array.from(this.artifacts.values()),
+      features: Array.from(this.features.values()),
+      artifactSections: Array.from(this.artifactSections.values()),
+      featureSections: Array.from(this.featureSections.values()),
+    };
+  }
+
+  applyActions(trx: DTOForgeProjectAction[]) {
+    trx.forEach(trx => this.applyTransaction(trx));
+  }
+
+  applyTransaction(trx: DTOForgeProjectAction) {
+    switch (trx.type) {
+      case "ArtifactCreate":
+        return this.artifactCreate(trx);
+      case "ArtifactUpdate":
+        return this.artifactUpdate(trx);
+      case "ArtifactDelete":
+        return this.artifactDelete(trx);
+      case "ArtifactMove":
+        return this.artifactMove(trx);
+      case "FeatureCreate":
+        return this.featureCreate(trx);
+      case "FeatureDelete":
+        return this.featureDelete(trx);
+      case "FeatureUpdate":
+        return this.featureUpdate(trx);
+      case "FeatureMove":
+        return this.featureMove(trx);
+      case "SectionCreate":
+        return this.sectionCreate(trx);
+      case "SectionUpdate":
+        return this.sectionUpdate(trx);
+      case "SectionDelete":
+        return this.sectionDelete(trx);
+      case "SectionMove":
+        return this.sectionMove(trx);
+    }
+  }
+
+  //
+  // Artifacts
+  //
+
+  public calculateSectionSortOrder(items: Map<string, DTOForgeSection>, afterItemId?: string | null) {
+    const sortedItems = Array.from(items.values()).sort((a, b) => a.sortOrder - b.sortOrder);
+    const sortOrder = this.calculateSortOrderNoDb(
+      pId => sortedItems.find(s => s.projectId === pId),
+      pId => sortedItems.findLast(s => s.projectId === pId),
+      (pId, id) => sortedItems.find(s => s.projectId === pId && s.id === id),
+      (pId, sortOrder) => sortedItems.find(s => s.projectId === pId && s.sortOrder > sortOrder),
+      (pId, sortOrder, step) =>
+        items.forEach(s => (s.sortOrder > sortOrder && s.projectId === pId ? (s.sortOrder += step) : {})),
+      this.projectId,
+      afterItemId
+    );
+    return sortOrder ?? 0;
+  }
+
+  public calculateItemSortOrder<T extends DTOForgeProjectArtifact | DTOForgeProjectFeature>(
+    items: Map<string, T>,
+    afterItemId?: string | null,
+    sectionId?: string | null
+  ) {
+    const sortedItems = Array.from(items.values()).sort((a, b) => a.sortOrder - b.sortOrder);
+    const matchIds = (i: T, pId: string, sId?: string) => i.sectionId === sId && i.projectId === pId;
+    const sortOrder = this.calculateSortOrderNoDb(
+      (pId, sId) => sortedItems.find(i => matchIds(i, pId, sId)),
+      (pId, sId) => sortedItems.findLast(i => matchIds(i, pId, sId)),
+      (pId, id, sId) => sortedItems.find(i => i.id === id && matchIds(i, pId, sId)),
+      (pId, sortOrder, sId) => sortedItems.find(i => i.sortOrder > sortOrder && matchIds(i, pId, sId)),
+      (pId, sortOrder, step, sId) =>
+        items.forEach(i => (i.sortOrder > sortOrder && matchIds(i, pId, sId) ? (i.sortOrder += step) : {})),
+      this.projectId,
+      afterItemId,
+      sectionId ?? undefined
+    );
+    return sortOrder ?? 0;
+  }
+
+  // See also calculateSectionSortOrder and calculateSectionedItemSortOrder
+  public calculateSortOrderNoDb(
+    findFirst: (projectId: string, sectionId?: string) => { sortOrder: number } | null | undefined,
+    findLast: (projectId: string, sectionId?: string) => { sortOrder: number } | null | undefined,
+    findUnique: (projectId: string, id: string, sectionId?: string) => { sortOrder: number } | null | undefined,
+    findNext: (projectId: string, sortOrder: number, sectionId?: string) => { sortOrder: number } | null | undefined,
+    shiftAfter: (projectId: string, sortOrder: number, step: number, sectionId?: string) => void,
+    projectId: string,
+    afterItemId?: string | null,
+    sectionId?: string
+  ): number | null {
+    const SORT_ORDER_STEP = 1000;
+    if (afterItemId === undefined) {
+      // Move to END: last.sortOrder + step
+      const lastSection = findLast(projectId, sectionId);
+      return (lastSection?.sortOrder ?? 0) + SORT_ORDER_STEP;
+    } else if (afterItemId === null) {
+      // Move to BEGINNING: first.sortOrder - step
+      const firstSection = findFirst(projectId, sectionId);
+      return (firstSection?.sortOrder ?? SORT_ORDER_STEP) - SORT_ORDER_STEP;
+    } else {
+      // Move AFTER target section: average of neighbors
+      const targetSection = findUnique(projectId, afterItemId, sectionId);
+      if (!targetSection) return null;
+
+      // Find the next section after target (if any)
+      const nextSection = findNext(projectId, targetSection.sortOrder, sectionId);
+      if (nextSection) {
+        // Position between target and next: average of neighbors
+        let newSortOrder = Math.floor((targetSection.sortOrder + nextSection.sortOrder) / 2);
+
+        // If average would be same as target (too close), use target + step
+        if (newSortOrder <= targetSection.sortOrder) {
+          newSortOrder = targetSection.sortOrder + SORT_ORDER_STEP / 2;
+          shiftAfter(projectId, targetSection.sortOrder, SORT_ORDER_STEP, sectionId);
+        }
+        return newSortOrder;
+      } else {
+        // No next section: position at end (target + step)
+        return targetSection.sortOrder + SORT_ORDER_STEP;
+      }
+    }
+  }
+
+  private artifactCreate(trx: DTOForgeProjectActionOfType<"ArtifactCreate">) {
+    const { input } = trx;
+    const { id, afterArtifactId, sectionId } = input;
+    const sortOrder = this.calculateItemSortOrder(this.artifacts, afterArtifactId, sectionId);
+
+    this.artifacts.set(id, {
+      id,
+      projectId: this.projectId,
+      sectionId: sectionId,
+      sortOrder: sortOrder,
+      title: input.title,
+      updatedAt: new Date(),
+      createdAt: new Date(),
+      createdByUserId: this.userId,
+      isArchived: false,
+    });
+  }
+
+  //
+  // Feature
+  //
+
+  private artifactUpdate(trx: DTOForgeProjectActionOfType<"ArtifactUpdate">) {
+    const { input } = trx;
+    const { id } = input;
+
+    const existingArtifact = this.artifacts.get(id);
+    if (!existingArtifact) {
+      throw new Error(`Cannot update artifact: artifact ${id} was not found in local storage`);
+    }
+
+    const mergedArtifact: DTOForgeProjectArtifact = {
+      ...existingArtifact,
+      title: input.title ?? existingArtifact.title,
+      isArchived: input.isArchived ?? existingArtifact.isArchived,
+      updatedAt: new Date(),
+    };
+
+    this.artifacts.set(id, mergedArtifact);
+  }
+
+  private artifactMove(trx: DTOForgeProjectActionOfType<"ArtifactMove">) {
+    const { input } = trx;
+    const { id, afterId, sectionId } = input;
+
+    const existingArtifact = this.artifacts.get(id);
+    if (!existingArtifact) {
+      throw new Error(`Cannot move artifact: artifact ${id} was not found in local storage`);
+    }
+
+    const sortOrder = this.calculateItemSortOrder(this.artifacts, afterId, sectionId);
+
+    const mergedArtifact: DTOForgeProjectArtifact = {
+      ...existingArtifact,
+      sortOrder,
+      updatedAt: new Date(),
+    };
+
+    this.artifacts.set(id, mergedArtifact);
+  }
+
+  private artifactDelete(trx: DTOForgeProjectActionOfType<"ArtifactDelete">) {
+    const { input } = trx;
+    const { id } = input;
+
+    if (!this.artifacts.delete(id)) {
+      throw new Error(`Cannot delete artifact: artifact ${id} was not found in local storage`);
+    }
+  }
+
+  private featureCreate(trx: DTOForgeProjectActionOfType<"FeatureCreate">) {
+    const { input } = trx;
+    const { id, afterFeatureId, sectionId } = input;
+    const sortOrder = this.calculateItemSortOrder(this.features, afterFeatureId, sectionId);
+
+    this.features.set(id, {
+      id,
+      projectId: this.projectId,
+      description: input.description,
+      isArchived: false,
+      sectionId: input.sectionId,
+      sortOrder: sortOrder,
+      name: input.name ?? "New Feature",
+      status: "Draft",
+      updatedAt: new Date(),
+      createdAt: new Date(),
+      createdByUserId: this.userId,
+      lastReplyTimestamp: undefined,
+      numberOfIterations: 0,
+      numberOfBookmarkedIterations: 0,
+    });
+  }
+
+  //
+  // Sections
+  //
+
+  private featureUpdate(trx: DTOForgeProjectActionOfType<"FeatureUpdate">) {
+    const { input } = trx;
+    const { id } = input;
+
+    const existingFeature = this.features.get(id);
+    if (!existingFeature) {
+      throw new Error(`Cannot update feature: feature ${id} was not found in local storage`);
+    }
+
+    let publishedState = existingFeature.publishedState;
+
+    if (input.publishedState === null) {
+      publishedState = undefined;
+    } else if (input.publishedState) {
+      publishedState = {
+        ...input.publishedState,
+        lastPublishedAt: new Date(),
+      };
+    }
+
+    const mergedFeature: DTOForgeProjectFeature = {
+      ...existingFeature,
+      name: input.name ?? existingFeature.name,
+      description: input.description ?? existingFeature.description,
+      isArchived: input.isArchived ?? existingFeature.isArchived,
+      status: input.status ?? existingFeature.status,
+      updatedAt: new Date(),
+      publishedState,
+    };
+
+    this.features.set(id, mergedFeature);
+  }
+
+  private featureMove(trx: DTOForgeProjectActionOfType<"FeatureMove">) {
+    const { input } = trx;
+    const { id, afterId, sectionId } = input;
+
+    const existingFeature = this.features.get(id);
+    if (!existingFeature) {
+      throw new Error(`Cannot move feature: feature ${id} was not found in local storage`);
+    }
+
+    const sortOrder = this.calculateItemSortOrder(this.features, afterId, sectionId);
+
+    const mergedFeature: DTOForgeProjectFeature = {
+      ...existingFeature,
+      sortOrder,
+      updatedAt: new Date(),
+    };
+
+    this.features.set(id, mergedFeature);
+  }
+
+  private featureDelete(trx: DTOForgeProjectActionOfType<"FeatureDelete">) {
+    const { input } = trx;
+    const { id } = input;
+
+    if (!this.features.delete(id)) {
+      throw new Error(`Cannot delete feature: feature ${id} was not found in local storage`);
+    }
+  }
+
+  private sectionCreate(trx: DTOForgeProjectActionOfType<"SectionCreate">) {
+    const { input } = trx;
+    const { id, afterSectionId } = input;
+    const sections = input.childType === "Artifact" ? this.artifactSections : this.featureSections;
+    const sortOrder = this.calculateSectionSortOrder(sections, afterSectionId);
+
+    sections.set(id, {
+      id,
+      projectId: this.projectId,
+      name: input.name,
+      childType: input.childType,
+      sortOrder: sortOrder,
+      updatedAt: new Date(),
+      createdAt: new Date(),
+    });
+  }
+
+  private sectionUpdate(trx: DTOForgeProjectActionOfType<"SectionUpdate">) {
+    const { input } = trx;
+    const { id } = input;
+
+    const existingSection = this.artifactSections.get(id) ?? this.featureSections.get(id);
+    if (!existingSection) {
+      throw new Error(`Cannot update section: section ${id} was not found in local storage`);
+    }
+
+    const mergedSection: DTOForgeSection = {
+      ...existingSection,
+      name: input.name ?? existingSection.name,
+      updatedAt: new Date(),
+    };
+
+    const sections = existingSection.childType === "Artifact" ? this.artifactSections : this.featureSections;
+    sections.set(id, mergedSection);
+  }
+
+  private sectionMove(trx: DTOForgeProjectActionOfType<"SectionMove">) {
+    const { input } = trx;
+    const { id, afterSectionId } = input;
+
+    const existingSection = this.artifactSections.get(id) ?? this.featureSections.get(id);
+    if (!existingSection) {
+      throw new Error(`Cannot move section: section ${id} was not found in local storage`);
+    }
+
+    const sections = existingSection.childType === "Artifact" ? this.artifactSections : this.featureSections;
+    const sortOrder = this.calculateSectionSortOrder(sections, afterSectionId);
+
+    const mergedSection: DTOForgeSection = {
+      ...existingSection,
+      sortOrder,
+      updatedAt: new Date(),
+    };
+
+    sections.set(id, mergedSection);
+  }
+
+  private sectionDelete(trx: DTOForgeProjectActionOfType<"SectionDelete">) {
+    const { input } = trx;
+    const { id } = input;
+
+    const isArtifactSection = this.artifactSections.delete(id);
+    const isFeatureSection = this.featureSections.delete(id);
+    if (!isArtifactSection && !isFeatureSection) {
+      throw new Error(`Cannot delete section: section ${id} was not found in local storage`);
+    }
+  }
+}

package/src/sync/types.ts

@@ -0,0 +1,37 @@
+import { DocumentationPageApproval, DocumentationPageV2, ElementGroup, OmitStrict } from "@supernova-studio/model";
+import {
+  DTOElementActionInput,
+  DTOForgeProjectArtifact,
+  DTOForgeProjectFeature,
+  DTOForgeRelation,
+  DTOForgeSection,
+} from "../api";
+
+export type LocalDocsPage = OmitStrict<DocumentationPageV2, "id" | "userSlug"> & { userSlug?: undefined };
+export type LocalDocsPageGroup = OmitStrict<ElementGroup, "id" | "brandPersistentId" | "childType" | "userSlug"> & {
+  userSlug?: undefined;
+};
+
+export type LocalApproval = OmitStrict<DocumentationPageApproval, "id" | "pageId" | "persistentId">;
+
+type NarrowedUnion<T, U extends T> = U;
+export type SupportedElementActionType = NarrowedUnion<
+  DTOElementActionInput["type"],
+  | "DocumentationPageCreate"
+  | "DocumentationPageUpdate"
+  | "DocumentationPageDelete"
+  | "DocumentationPageMove"
+  | "DocumentationGroupCreate"
+  | "DocumentationGroupUpdate"
+  | "DocumentationGroupMove"
+  | "DocumentationPageApprovalStateChange"
+  | "DocumentationTabCreate"
+>;
+
+export type ProjectContentState = {
+  artifacts: DTOForgeProjectArtifact[];
+  features: DTOForgeProjectFeature[];
+  artifactSections: DTOForgeSection[];
+  featureSections: DTOForgeSection[];
+  relations: DTOForgeRelation[];
+};