Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.5 KB
Raw Blame
import {
  EphemeralStore,
  type EphemeralStoreEvent,
  type PeerID,
  type Value,
} from 'loro-crdt';
import {
  type Accessor,
  createSignal,
  getOwner,
  onCleanup,
  untrack,
} from 'solid-js';
import { getRandomPaletteColor } from '../internal/palette';
import type { RawUpdate } from './shared';

/** The default timeout for a user's awareness is 10 seconds */
const DEFAULT_AWARENESS_TIMEOUT = 10_000;

type PeerAwarenessRaw<EncodedSelection extends Value = Value> = {
  user: { userId: string | undefined; color: string; peerId: PeerID };
  selection: EncodedSelection | undefined;
};

export type PeerAwareness<DecodedSelection> = {
  user: { userId: string | undefined; color: string; peerId: PeerID };
  selection: DecodedSelection | undefined;
};

/**
 * A codec for encoding and decoding selections
 *
 * Selections require encoding / decoding, because they likely contain a [LoroCursor]
 * Which is a wasm ptr, which is not structured clonable.
 *
 * To transmit LoroCursor over the wire, we need to use the LoroCursor.encode() method
 *
 * The `encode` method on the codec, is responsible for encoding all cursors in the selection
 *
 * @typeParam DecodedSelection - The decoded selection type
 * @typeParam EncodedSelection - The encoded selection type, should be Structured Clonable
 */
export type SelectionCodec<DecodedSelection, EncodedSelection extends Value> = {
  /** Encodes a decoded selection into an encoded selection
   *
   * @param selection - The decoded selection
   * @returns The encoded selection
   * */
  encode: (selection: DecodedSelection) => EncodedSelection;
  /** Decodes an encoded selection into a decoded selection
   *
   * @param serialized - The encoded selection
   * @returns The decoded selection
   * */
  decode: (encoded: EncodedSelection) => DecodedSelection;
};

export type Awareness<DecodedSelection> = {
  /** Signal containing the decoded local awareness */
  readonly local: Accessor<PeerAwareness<DecodedSelection>>;
  /** Signal containing the all decoded remote awarenesses */
  readonly remote: Accessor<PeerAwareness<DecodedSelection>[]>;
  updateRemoteAwareness: (
    peerId: PeerID,
    selection: DecodedSelection | undefined
  ) => void;
  updateLocalAwareness: (selection: DecodedSelection | undefined) => void;
  /** Imports remote awareness updates
   *
   * @param update - The update to import
   * */
  importRemoteAwareness: (update: RawUpdate) => void;
  /** Returns the encoded local awareness as a [RawUpdate] */
  getEncodedLocalAwareness: () => RawUpdate;
};

/** Creates a new awareness object
 * that keeps track of each peer's "awareness" within the document
 * The awareness is defined by a selection, which stores arbitrary information
 * about the user's cursor position, selection, etc.
 *
 * @param peerId - The peer ID of the awareness
 * @param userId - The user ID of the awareness
 * @param selectionCodec - The codec to use for encoding and decoding selections
 * @param options - Optional options for the awareness
 * @returns The new awareness object
 */
export function createAwareness<
  EncodedSelection extends Value,
  DecodedSelection,
>(
  peerId: PeerID,
  userId: string | undefined,
  selectionCodec: SelectionCodec<DecodedSelection, EncodedSelection>,
  options?: {
    timeout?: number;
  }
): Awareness<DecodedSelection> {
  // Initialize the ephemeral store
  // By default, each peer awareness will timeout after 5 seconds of inactivity
  const store = new EphemeralStore<
    Record<string, PeerAwarenessRaw<EncodedSelection> | undefined>
  >(options?.timeout ?? DEFAULT_AWARENESS_TIMEOUT);
  let disposed = false;
  if (getOwner())
    onCleanup(() =>
      queueMicrotask(() => {
        disposed = true;
        store.destroy();
        store.inner.free();
      })
    );

  // Initialize user awareness with a random color
  const color = getRandomPaletteColor();

  // Initialize the local peer's awareness
  const initialLocalPeerAwarenessRaw: PeerAwarenessRaw<EncodedSelection> = {
    user: {
      userId,
      color,
      peerId,
    },
    selection: undefined,
  };

  store.set(peerId, initialLocalPeerAwarenessRaw);

  // The local signal contains the deserialized version
  const [local, setLocal] = createSignal<PeerAwareness<DecodedSelection>>({
    user: initialLocalPeerAwarenessRaw.user,
    selection: undefined,
  });

  const [remote, setRemote] = createSignal<PeerAwareness<DecodedSelection>[]>(
    []
  );

  const updateRemoteAwarenessSignal = () => {
    const allStates = store.getAllStates();

    const remoteAwareness: PeerAwareness<DecodedSelection>[] = Object.entries(
      allStates
    )
      .filter(([id, awareness]) => {
        return (
          peerId !== id && !!awareness && awareness?.selection !== undefined
        );
      })
      .map(([id, awareness]) => {
        return [id, decodeAwareness(awareness, selectionCodec)];
      })
      .map(([_, awareness]) => awareness as PeerAwareness<DecodedSelection>);

    setRemote(remoteAwareness);
  };

  /** Update the local awareness signal with the vaue from the store */
  const updateLocalAwarenessSignal = () => {
    const awareness = store.get(peerId);
    const decodedAwareness = decodeAwareness(awareness, selectionCodec);
    if (decodedAwareness) {
      setLocal(decodedAwareness);
    }
  };

  const updateAwarenessSignals = (update: EphemeralStoreEvent) => {
    const changes = [...update.added, ...update.removed, ...update.updated];
    if (changes.length === 0) return;

    if (update.by === 'local' && changes.includes(peerId)) {
      updateLocalAwarenessSignal();
      return;
    } else {
      updateRemoteAwarenessSignal();
      return;
    }
  };

  const updatePeerAwareness = (
    id: PeerID,
    selection: DecodedSelection | undefined
  ) => {
    if (disposed) return;
    if (selection === undefined) {
      store.set(id, undefined);
      return;
    }

    const currAwareness = untrack(local);
    const newAwareness = encodeAwareness(
      {
        user: currAwareness.user,
        selection: selection,
      },
      selectionCodec
    );
    store.set(id, newAwareness);
  };

  const updateLocalAwareness = (selection: DecodedSelection | undefined) => {
    updatePeerAwareness(peerId, selection);
  };

  const updateRemoteAwareness = (
    id: PeerID,
    selection: DecodedSelection | undefined
  ) => {
    if (id === peerId) {
      return;
    }
    updatePeerAwareness(id, selection);
  };

  const importRemoteAwareness = (update: RawUpdate) => {
    if (disposed) return;
    store.apply(update);
  };

  const getEncodedLocalAwareness = () => {
    if (disposed) return new Uint8Array();
    return store.encode(peerId);
  };

  // Listen for changes to the ephemeral store
  store.subscribe((update) => {
    // HACK: loro-crdt has a bug with [`EphemeralStore.subscribe`] which breaks
    // recursive aliasing. This is a workaround for now.
    queueMicrotask(() => {
      if (disposed) return;
      updateAwarenessSignals(update);
    });
  });

  return {
    local,
    remote,
    updateLocalAwareness,
    updateRemoteAwareness,
    importRemoteAwareness,
    getEncodedLocalAwareness,
  };
}

/** Decodes an awareness object from a raw update */
function decodeAwareness<EncodedSelection extends Value, DecodedSelection>(
  awareness: PeerAwarenessRaw<EncodedSelection> | undefined,
  codec: SelectionCodec<DecodedSelection, EncodedSelection>
): PeerAwareness<DecodedSelection> | undefined {
  if (!awareness) {
    return undefined;
  }

  if (!awareness.selection) {
    return {
      user: awareness.user,
      selection: undefined,
    };
  }
  const encodedSelection = awareness.selection;

  return {
    user: awareness.user,
    selection: codec.decode(encodedSelection),
  };
}

/** Encodes an awareness object into a decoded awareness to be stored in the store
 *
 * @param awareness - The awareness object to encode
 * @param codec - The codec to use for encoding
 * @returns The encoded awareness
 */
function encodeAwareness<DecodedSelection extends Value>(
  awareness: PeerAwareness<unknown>,
  codec: SelectionCodec<any, DecodedSelection>
) {
  if (!awareness.selection) {
    return {
      user: awareness.user,
      selection: undefined,
    };
  }

  const encodedSelection = codec.encode(awareness.selection);

  return {
    user: awareness.user,
    selection: encodedSelection,
  };
}

/** Checks if an awareness object has a selection */
export function isAwarenessWithSelection<DecodedSelection>(
  awareness: PeerAwareness<DecodedSelection | undefined>
): awareness is PeerAwareness<DecodedSelection> {
  return awareness?.selection !== undefined;
}