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.

33.0 KB
Raw Blame
import type { CalendarBlockProps } from '@block-calendar/types';
import type { BlockCanvasProps } from '@block-canvas/component/Block';
import type { BlockChannelProps } from '@block-channel/component/NewChannelBlockAdapter';
import type { BlockMarkdownProps } from '@block-md/component/Block';
import type { IDocumentStorageServiceFile } from '@filesystem/file';
import type {
  InitialSync,
  LiveSyncSource,
  SyncError,
} from '@macro-inc/collaboration/collab/source';
import type { Span } from '@macro-inc/observability';
import type { AccessLevel } from '@service-storage/generated/schemas/accessLevel';
import type { DocumentMetadata } from '@service-storage/generated/schemas/documentMetadata';
import type { GetDocumentResponseData } from '@service-storage/generated/schemas/getDocumentResponseData';
import type { Project } from '@service-storage/generated/schemas/project';
import type { ResultAsync } from 'neverthrow';
import { err, ok, type Result } from 'neverthrow';
import type {
  Accessor,
  Component,
  FlowProps,
  InitializedResource,
  InitializedResourceOptions,
  lazy,
  Owner,
  Resource,
  ResourceActions,
  ResourceFetcher,
  ResourceOptions,
  ResourceSource,
  Setter,
  SignalOptions,
} from 'solid-js';
import {
  createComponent,
  createContext,
  createResource,
  createSignal,
  getOwner,
  onCleanup,
  useContext,
} from 'solid-js';
import { createStore, type SetStoreFunction, type Store } from 'solid-js/store';
import {
  type BlockAliasRegistry,
  BlockRegistry,
} from '../constants/block-registry';
import { ENABLE_PDF_MULTISPLIT } from './constant/featureFlags';
import { blockDataSignal } from './internal/BlockLoader';
import type { Source, SourcePreload } from './source';
import type { ObjectLike, ResultError } from './util/result';

export { BlockAliasRegistry, BlockRegistry } from '../constants/block-registry';

type BlockNameKeys = keyof typeof BlockRegistry & number;

/**
 * Represents a block name which is one of the predefined block types in {@link BlockRegistry}.
 */
export type BlockName = (typeof BlockRegistry)[BlockNameKeys];

type BlockAliasKeys = keyof typeof BlockAliasRegistry & number;

/**
 * Represents a block-alias. Which a a valid, differentiated entity type with
 * the same behavior as a true block.
 */
export type BlockAlias = (typeof BlockAliasRegistry)[BlockAliasKeys];

/**
 * Represents the block types that do not correspond to a document type.
 */
export const NonDocumentBlockTypes = [
  'call',
  'calendar',
  'chat',
  'database',
  'form',
  'channel',
  'project',
  'email',
  'contact',
  'company',
  'routine',
  'pr',
  'agent',
  'initiative',
  'pipeline',
] as const as (BlockName | BlockAlias)[];

/**
 * Represents the type of a possible 2-block combination used in split layouts.
 * The key is block on the left of the the split and the value is a set of
 * allowed blocks on the right.
 */
type BlockCombinationRules = {
  [Key in BlockName | BlockAlias]: Set<BlockName>;
};

export type PreviewState = {
  canvas?: {
    onLocationChange?: (location: {
      x: number;
      y: number;
      scale: number;
    }) => void;
  };
};

export type NestedState<Name extends BlockName> = {
  parentId?: string;
  parentName?: Name;
  parentContext?: PreviewState;
};

const allBlockNames = new Set([...BlockRegistry]);
function exclude(excludeSet: BlockName[]) {
  return new Set(BlockRegistry.filter((x) => !excludeSet.includes(x)));
}
/**
 * Defines the block combinations that are valid.
 */
const _ValidBlockCombinations: BlockCombinationRules = {
  call: allBlockNames,
  calendar: allBlockNames,
  chat: allBlockNames,
  database: allBlockNames,
  form: allBlockNames,
  pdf: ENABLE_PDF_MULTISPLIT ? allBlockNames : exclude(['pdf']),
  write: exclude(['write']),
  md: allBlockNames,
  code: exclude(['code']),
  image: allBlockNames,
  channel: allBlockNames,
  email: allBlockNames,
  canvas: allBlockNames,
  spreadsheet: allBlockNames,
  pptx: allBlockNames,
  psd: allBlockNames,
  fig: allBlockNames,
  ai: allBlockNames,
  project: allBlockNames,
  unknown: allBlockNames,
  video: allBlockNames,
  contact: allBlockNames,
  company: allBlockNames,
  task: allBlockNames,
  snippet: allBlockNames,
  skill: allBlockNames,
  routine: allBlockNames,
  csv: allBlockNames,
  pr: allBlockNames,
  agent: allBlockNames,
  initiative: allBlockNames,
  pipeline: allBlockNames,
} as const;

// maps block name to valid parents
export const ValidNestingCombinations: BlockCombinationRules = {
  call: new Set([]),
  calendar: new Set([]),
  canvas: new Set(['md']),
  spreadsheet: new Set([]),
  pptx: new Set([]),
  psd: new Set([]),
  fig: new Set([]),
  ai: new Set([]),
  database: new Set([]),
  // A form card fills in place inside messages and documents (RFC 03 §1).
  form: new Set(['md', 'channel']),
  chat: new Set([]),
  pdf: new Set(['md']),
  write: new Set([]),
  md: new Set([]),
  code: new Set(['md']),
  image: new Set([]),
  channel: new Set([]),
  email: new Set([]),
  project: new Set([]),
  unknown: new Set([]),
  video: new Set([]),
  contact: new Set([]),
  company: new Set([]),
  task: new Set([]),
  snippet: new Set([]),
  skill: new Set([]),
  routine: new Set([]),
  csv: new Set([]),
  pr: new Set([]),
  agent: new Set([]),
  initiative: new Set([]),
  pipeline: new Set([]),
};

export const LoadErrors = {
  UNAUTHORIZED: err<never, ResultError<'UNAUTHORIZED'>[]>([
    { code: 'UNAUTHORIZED', message: 'Unauthorized access' },
  ]),
  MISSING: err<never, ResultError<'MISSING'>[]>([
    { code: 'MISSING', message: 'Not found' },
  ]),
  INVALID: err<never, ResultError<'INVALID'>[]>([
    { code: 'INVALID', message: 'Unable to load invalid document' },
  ]),
  GONE: err<never, ResultError<'GONE'>[]>([
    { code: 'GONE', message: 'Document no longer exists' },
  ]),
} as const;

type LoadErrorCodes = keyof typeof LoadErrors;

/**
 * Converts a Result to a Result with a load error code.
 * @template T - The type of the input result value.
 * @param {Result<T, ResultError<string>[]>} result - The result to convert.
 * @returns {Result<T, ResultError<keyof typeof LoadErrors>[]>} A new Result with a load error code.
 */
function toLoadResult<E extends string, T extends ObjectLike>(
  result: Result<T, ResultError<E>[]>
): Result<T, ResultError<keyof typeof LoadErrors>[]> {
  if (result.isErr() && result.error.some((error) => error.code === 'GONE')) {
    return err(LoadErrors.GONE.error);
  }
  if (
    result.isErr() &&
    result.error.some((error) => error.code === 'UNAUTHORIZED')
  ) {
    return err(LoadErrors.UNAUTHORIZED.error);
  }
  if (
    result.isErr() &&
    result.error.some((error) => error.code === 'NOT_FOUND')
  ) {
    return err(LoadErrors.MISSING.error);
  }
  if (result.isErr()) return err(LoadErrors.INVALID.error);
  return ok(result.value);
}

/**
 * Awaits a load result and returns a new load result with the same value or a load error.
 * @template T - The type of the input result value.
 * @param {Promise<Result<T, ResultError<string>[]>>} result - The result to await.
 * @returns {Promise<Result<T, ResultError<keyof typeof LoadErrors>[]>>} A new Result with the same value or a load error.
 */
export async function loadResult<
  T extends Promise<Result<ObjectLike, ResultError<string>[]>>,
>(
  result: T
): Promise<
  Result<ExtractSuccessType<Awaited<T>>, ResultError<keyof typeof LoadErrors>[]>
> {
  return toLoadResult(await result) as any; // any because TypeScript gets confused and loses the ObjectLike's specific type
}

/**
 * Maps over an ok result, or passes through a load error.
 * @template T - The type of the input result value.
 * @template U - The type of the output result value.
 * @param {Result<T, ResultError<string>[]>} result - The result to map.
 * @param {(value: T) => U} fn - The function to apply to the ok value.
 * @returns {Result<U, ResultError<LoadErrorCodes>[]>} A new Result with the mapped value or a load error.
 */
function _mapLoadResult<T extends ObjectLike, U extends ObjectLike>(
  result: Result<T, ResultError<string>[]>,
  fn: (value: T) => U
): Result<U, ResultError<LoadErrorCodes>[]> {
  const loadResult = toLoadResult(result);
  if (loadResult.isErr()) return err(loadResult.error);
  return ok(fn(loadResult.value));
}

// Magic type that when used at sites where generic types are inferred from, will prevent those sites from being involved in the inference.
// https://github.com/microsoft/TypeScript/issues/14829
// TypeScript Discord conversation: https://discord.com/channels/508357248330760243/508357248330760249/911266491024949328
export type NoInfer<T> = [T][T extends any ? 0 : never];

export type FileLike = { file: Blob } & GetDocumentResponseData;
export type TextLike = { text: string } & GetDocumentResponseData;
export type FileOrTextLike = FileLike | TextLike;

// RoutePreloadFuncArgs['intent'] from '@solidjs/router';
type Intent = 'initial' | 'native' | 'navigate' | 'preload';
/**
 * A function type that returns a resource for the given data type.
 *
 * @template T - The data type being used.
 * @param {Source} [source] - Source to be used with the resource.
 * @returns {Promise<T>} - The data type tied to the block type.
 */
export type LoadFunction<
  T extends ObjectLike,
  P extends SourcePreload<Record<string, any>>,
  S extends Source | P = Source | P,
> = (
  source: NoInfer<S>,
  intent: Intent,
  parentSpan?: Span
) => Promise<
  Result<S extends Source ? T | P : T, ResultError<keyof typeof LoadErrors>[]>
>;

type ExtractSuccessType<T> =
  T extends Result<infer S, ResultError<any>[]>
    ? Exclude<S, { type: 'preload' }>
    : never;

/**
 * Extracts the non-error, non-preload return type of a load function.
 *
 * This utility type unwraps the Promise, extracts the success type from Result,
 * and excludes the SourcePreload type. It's useful for getting the actual data type
 * returned by a load function in the successful, non-preload case.
 *
 * @template T - The type of the load function, which should extend LoadFunction<any>.
 * @returns The extracted data type from the load function's return type.
 *
 * @example
 * const definition = defineBlock({
 *   // ... other properties ...
 *   async load(source, intent) {
 *     // Implementation that returns Promise<Result<Data | Preload, ResultError<Error>[]>>
 *   },
 * });
 *
 * type WriterData = ExtractLoadDataType<typeof definition['load']>;
 * // WriterData will be the type of 'Data' in the successful, non-preload case
 */
export type ExtractLoadType<T extends LoadFunction<any, any>> =
  ExtractSuccessType<Awaited<ReturnType<T>>>;

export interface BlockComponentProps extends Record<BlockName, ObjectLike> {
  calendar: CalendarBlockProps;
  canvas: BlockCanvasProps;
  channel: BlockChannelProps;
  md: BlockMarkdownProps;
}

interface BlockComponentLoadData extends Record<BlockName, ObjectLike> {
  canvas: DocumentBlockData &
    ({ shared: true; dssFile?: never } | (DssFileData & { shared?: false }));
  pdf: DocumentBlockData;
  video: DocumentBlockData;
  md: DocumentBlockData &
    DssFileData & {
      syncSource: LiveSyncSource;
      doInitialSync: () => ResultAsync<InitialSync, SyncError>;
    };
  code: DocumentBlockData;
  project: ProjectBlockData;
  // TODO: uncomment when email block is ready, it is currently using unknown
  // unknown: DocumentBlockData;
  image: DocumentBlockData & DssFileData;
}

/**
 * A component type representing a block.
 *
 * Note that it intentionally does not take any props. This is because block data should be
 * context-based and rely on a {@link LoadFunction}
 */
export type BlockComponent<Name extends BlockName> =
  | ReturnType<typeof lazy<Component<BlockComponentProps[Name]>>>
  | (Component<BlockComponentProps[Name]> & { preload?: undefined });

export type FileTypeString = string & {};
export type MimeType = string & {};

/**
 * Defines a block and its associated metadata and behavior.
 *
 * @template Service - The service associated with this block.
 * @template Data - The data type used by the block.
 * @template Name - The specific block name from the {@link BlockName} type.
 */
export type BlockDefinition<
  Data extends ObjectLike,
  Name extends BlockName,
  P extends SourcePreload<Record<string, any>>,
  L extends LoadFunction<Data, P>,
> = {
  /** The name of the block. */
  name: Name;

  /** A brief description of what the block does. */
  description: string;
  /** Function to retrieve the data resource for this block. */
  load: L;

  /** The component for the block. */
  component: BlockComponent<Name>;

  /** Lightweight placeholder while the block's component or data loads. */
  loading?: Component;

  /** flag to indicate wether this block should enable collaborative features. */
  liveTrackingEnabled?: boolean;

  /** Whether mounting this block records an entity-open history row and page view. */
  openTrackingEnabled?: boolean;

  /**
   * Whether mounting this block sends `open_entity`. Defaults to
   * `openTrackingEnabled`; set it on a block without a history row whose opens
   * are still a product signal, as `block-database` does.
   */
  openAnalyticsEnabled?: boolean;

  accepted: Record<string, string>;

  /** The default name of the file when creating a new block of this type. */
  defaultFilename?: string;

  syncServiceEnabled?: boolean;

  editPermissionEnabled?: boolean;

  /** Alias block names that should route to this block type with optional custom default filenames */
  aliases?: Array<{ name: BlockAlias; defaultFileName?: string }>;
};

export type AnyBlockDefinition = BlockDefinition<any, any, any, any>;

export type BlockAliasContext = {
  /** The original alias used in the URL (e.g., 'task') */
  alias: BlockAlias;
  /** The resolved base block type (e.g., 'md') */
  baseType: BlockName;
};

type DocumentBlockData = {
  userAccessLevel: AccessLevel;
  documentMetadata: DocumentMetadata;
};

type ProjectBlockData = {
  projectMetadata: Project;
  userAccessLevel: AccessLevel;
};

type DssFileData = {
  dssFile: IDocumentStorageServiceFile;
};

/**
 * Defines a block.
 *
 * @template S - The service associated with the block.
 * @template D - The data type used by the block.
 * @template N - The specific block name from the {@link BlockName} type.
 * @param {BlockDefinition<S, D, N>} blockDef - The block definition to be returned.
 * @returns {BlockDefinition<S, D, N>} - The same block definition passed in.
 */
export function defineBlock<
  N extends BlockName,
  D extends BlockComponentLoadData[N],
  P extends SourcePreload<Record<string, any>>,
  L extends LoadFunction<D, P>,
>(blockDef: BlockDefinition<D, N, P, L>): BlockDefinition<D, N, P, L> {
  return blockDef as any;
}

/**
 * Represents a function that can be used as a block effect.
 */
type BlockEffect = (...args: any[]) => any;

/**
 * After the the render phase, automatically reruns the function whenever the block's signal and
 * store dependencies update.
 *
 * Should only be defined at the top level of a module.
 *
 * @deprecated
 * @param {BlockEffect} fn - The function to be used as a block effect.
 */
export const [globalBlockEffects] = createSignal<BlockEffect[]>([]);
export const [globalBlockRenderEffects] = createSignal<BlockEffect[]>([]);

/** @deprecated */
export function createBlockEffect(fn: BlockEffect): void {
  globalBlockEffects().push(fn);
}

export function createBlockRenderEffect(fn: BlockEffect): void {
  globalBlockRenderEffects().push(fn);
}

/**
 * A component that provides the scope and context for blocks, including signals, stores, and effects.
 */
export const Block = <Name extends BlockName>(
  props: FlowProps<{
    id: string;
    name: Name;
    nested?: NestedState<Name>;
    aliasContext?: BlockAliasContext;
  }>
) => {
  const [state] = createSignal<BlockState>({
    entities: new Map(),
    memos: new Map(),
    id: props.id,
    name: props.name,
    nested: props.nested,
    owner: getOwner(),
    aliasContext: props.aliasContext,
  });

  onCleanup(() => {
    state().entities.clear();
    state().memos.clear();
  });

  const blockComponent = createComponent(BlockContext.Provider, {
    get value() {
      return state();
    },
    get children() {
      return props.children;
    },
  });

  return blockComponent;
};

/**
 * Hook to access the current block's ID.
 * This will throw if used outside a Block component.
 * @throws {Error} When used outside of a Block context
 * @returns The current block ID
 */
export const useBlockId = (): string => {
  const context = useContext(BlockContext);
  if (!context) {
    throw new Error('hook must be used within a Block component');
  }
  return context.id;
};

export const useIsNestedBlock = (): boolean => {
  const context = useContext(BlockContext);
  if (!context) {
    throw new Error('hook must be used within a Block component');
  }
  return context.nested !== undefined;
};

export const useBlockNestedContext = <Name extends BlockName>():
  | NestedState<Name>
  | undefined => {
  const context = useContext(BlockContext);
  return context?.nested as NestedState<Name>;
};

export const useBlockOwner = (): Owner | null => {
  const context = useContext(BlockContext);
  if (!context) {
    return null;
  }
  return context.owner;
};

/**
 * Hook to access the current block's name.
 * This will throw if used outside a Block component.
 * @throws {Error} When used outside of a Block context
 * @returns The current block name
 */
export const useBlockName = (): BlockName => {
  const context = useContext(BlockContext);
  if (!context) {
    throw new Error('hook must be used within a Block component');
  }
  return context.name;
};

/**
 * Hook to access the current block's name - will return the alias used to access
 * the block if it exists.
 * This will throw if used outside a Block component.
 * @throws {Error} When used outside of a Block context
 * @returns The current block name or alias.
 */
export const useBlockAliasedName = (): BlockName | BlockAlias => {
  const context = useContext(BlockContext);
  if (!context) {
    throw new Error('hook must be used within a Block component');
  }
  return context.aliasContext?.alias ?? context.name;
};

/**
 * Use the blockId hook without throwing. Must check for undefined.
 * Useful for testing the markdown engine outside of a block.
 * @returns The current block ID or undefined if not in a block
 */
export const useMaybeBlockId = (): string | undefined => {
  const context = useContext(BlockContext);
  if (!context) {
    return;
  }
  return context.id;
};

/**
 * Use the blockName hook without throwing. Must check for undefined.
 * Useful for testing the markdown engine outside of a block.
 * @returns The current block name or undefined if not in a block
 */
export const useMaybeBlockName = (): BlockName | undefined => {
  const context = useContext(BlockContext);
  if (!context) {
    return;
  }
  return context.name;
};

export const useMaybeBlockAliasedName = ():
  | BlockName
  | BlockAlias
  | undefined => {
  const context = useContext(BlockContext);
  if (!context) {
    return;
  }
  return context.aliasContext?.alias ?? context.name;
};

function styledConsoleError(message: string, code: string) {
  if (import.meta.env.DEV) {
    const styles = `
    color: #f8f8f2;
    background-color: #272822;
    display: inline-block;
    width: 100%;
    font-family: monospace;
    line-height: 1.5;
  `;

    const formattedCode = code.replace(/\n/g, '\n    ');

    console.error(`${message}\n%c    ${formattedCode}`, styles);
  }
}

function buildBlockAccessError(kind: string) {
  return [
    `Unable to access block
If you are using block signal in an async method or component, you need to destructure ${kind} before a return or callback or the first \`await\`:
`,
    `function Component() {
// getter and setter
const [get, set] = someBlockSignal;
// setter
const setAnother = anotherBlockSignal.set;
// getter
const getAnother = anotherBlockSignal.get;

createEffect(() => {
  if (get() !== getAnother()) {
    setAnother(get());
  }
})

return (
  <button onClick={() => setAnother('reset!')}>
    Reset
  </button>
);
}

async function refreshSize() {
  // destructured
  const setSize = sizeSignal.set;
  // the first await
  const currentSize = await doc.calculateSize();
  setSize(currentSize);
}

createBlockEffect(() => {
  refreshSize();
});
`,
  ];
}

let longErrorOnce = [false, false];

function createBlockEntity<T extends any[], R extends [any, any]>(
  this: any,
  creator: Creator<T, R>,
  ...initialArgs: T
) {
  const key = Symbol();

  const getEntry = (): R | undefined => {
    const context =
      useContext(BlockContext) ?? (isInBlockFn(this) ? this.block : undefined);
    if (!context) {
      return undefined;
    }

    let entry = context.entities.get(key);
    if (!entry) {
      const clonedArgs = initialArgs.map((arg) =>
        typeof arg === 'object' && arg !== null ? structuredClone(arg) : arg
      );
      entry = creator(...(clonedArgs as T));
      context.entities.set(key, entry);
    }
    return entry as R;
  };

  return new Proxy(() => {}, {
    get(_target, prop) {
      const entry = getEntry();

      // DEBUG HELPING CODE: {
      if (!entry) {
        if (import.meta.env.DEV) {
          const kind = ['0', 'get'].includes(prop as string)
            ? 'the getter'
            : ['1', 'set'].includes(prop as string)
              ? 'the setter'
              : '';
          if (longErrorOnce[0]) {
            console.error(`Unable to access block
If you are using block signal in an async method or component, you need to destructure ${kind} before a return or callback or the first \`await\``);
            return;
          }
          longErrorOnce[0] = true;

          const [errorMessage, code] = buildBlockAccessError(kind);

          styledConsoleError(errorMessage, code);
        }
        return;
      }
      // DEBUG HELPING CODE: }

      if (prop === '0') return entry[0];
      if (prop === '1') return entry[1];
      if (prop === 'get') return entry[0];
      if (prop === 'set') return entry[1];
      if (prop === Symbol.iterator) {
        return function* () {
          yield entry[0];
          yield entry[1];
        };
      }
      return undefined;
    },
    apply(_target, thisArg, argumentsList) {
      const entry = getEntry();

      // DEBUG HELPING CODE: {
      if (!entry) {
        if (import.meta.env.DEV) {
          if (longErrorOnce[1]) {
            console.error(`Unable to access block
If you are calling a block signal directly in an async method, you need to destructure the getter before the first \`await\``);
            console.trace();
            return;
          }
          longErrorOnce[1] = true;
          styledConsoleError(
            `Unable to access block
If you are calling a block signal directly in an async method, you need to destructure the getter before the first \`await\` or wrap the callback in \`createCallback\`:
`,
            `async function refreshSize() {
  const setSize = sizeSignal.set;
  const currentSize = await doc.calculateSize();
  setSize(currentSize);
}
`
          );
          console.trace();
        }
        return;
      }
      // DEBUG HELPING CODE: }

      return entry[0].apply(thisArg, argumentsList);
    },
  }) as unknown as R[0] & {
    0: R[0];
    1: R[1];
    [Symbol.iterator]: () => IterableIterator<R[0] | R[1]>;
  };
}

type BlockSignal<T> = [get: Accessor<T>, set: Setter<T>] & {
  (): T;
  get: Accessor<T>;
  set: Setter<T>;
};

/**
 * Creates a block-scoped signal to set and get state.
 *
 * Should only be defined at the top level of a module.
 *
 * @deprecated
 * @template T - The type of the signal value.
 * @returns {BlockSignal<T | undefined>} A block signal object.
 *
 * @example
 * const nameSignal = createBlockSignal('Macro');
 *
 * // traditional signal usage
 * function Organization() {
 *  const [name, setName] = nameSignal;
 *
 *  return (
 *    <>
 *    <div>Name: {name()}</div>
 *    <button onclick={() => setName('Micro')}>Change Name</button>
 *    </>
 *  )
 * }
 *
 * // derived signal
 * const nameLength = () => nameSignal().length
 *
 * // simpler setter, direct accessor
 * function Organization() {
 *  // to assign context scope, it must be assigned
 *  const setName = nameSignal.set;
 *
 *  return (
 *    <>
 *    <div>Name: {nameSignal()}</div>
 *    <button onclick={() => setName('Micro')}>Change Name</button>
 *    </>
 *  )
 * }
 */
export function createBlockSignal<T>(): BlockSignal<T | undefined>;
export function createBlockSignal<T>(
  value: T,
  options?: SignalOptions<T>
): BlockSignal<T>;
export function createBlockSignal<T>(
  value?: T,
  options?: SignalOptions<T>
): BlockSignal<T | undefined> {
  return createBlockEntity(createSignal, value, options as any) as BlockSignal<
    T | undefined
  >;
}

export type BlockStore<T> = [Store<T>, SetStoreFunction<T>] & {
  (): T;
  get: Store<T>;
  set: SetStoreFunction<T>;
};

/**
 * Creates a block-scoped store to set and get state.
 *
 * Should only be defined at the top level of a module.
 *
 * @template T - The type of the store value, must be an object.
 * @param {T} initialValue - The initial value for the store.
 * @returns {BlockStore<T>} A block store object.
 *
 * @example
 *
 * // traditional usage
 * function UserInfo() {
 *   const [user, setUser] = userStore;
 *   createEffect(() => {
 *     console.log(user.name, 'is', user.age, 'years old');
 *   });
 *   return (
 *     <div>
 *       <p>
 *         User: {user.name} (Age: {user.age})
 *       </p>
 *       <button onClick={() => setUser('name', 'Bob')}>Set Name to Bob</button>
 *       <button onClick={() => setUser('age', (a) => a + 1)}>
 *         Increment Age
 *       </button>
 *     </div>
 *   );
 * }
 *
 * // simpler setter
 * function UserUpdate() {
 *   const setUser = userStore.set;
 *   return (
 *     <div>
 *       <button onClick={() => setUser('name', 'Alice')}>
 *         Set Name to Alice
 *       </button>
 *     </div>
 *   );
 * }
 */
export function createBlockStore<T extends object>(
  initialValue: T
): BlockStore<T> {
  return createBlockEntity(createStore, structuredClone(initialValue)) as any;
}

type BlockInitializedResource<T, R = unknown> = [
  get: InitializedResource<T>,
  set: ResourceActions<T, R>,
] & {
  (): T;
  get: InitializedResource<T>;
  set: ResourceActions<T, R>;
};

type BlockResource<T, R = unknown> = [
  get: Resource<T>,
  set: ResourceActions<T, R>,
] & {
  (): T;
  get: Resource<T>;
  set: ResourceActions<T, R>;
};

/**
 * Creates a block-scoped resource that wraps a promise in a reactive pattern.
 *
 * Should only be defined at the top level of a module.
 *
 * @deprecated
 * @template T - The type of the resource value.
 * @template S - The type of the source value (optional).
 * @template R - The type of the refetching value (optional).
 *
 * @param {ResourceFetcher<S, T, R>} fetcher - Function that returns a value or a Promise.
 * @param {ResourceOptions<T, S>} [options] - Optional configuration for the resource.
 *
 * @returns {BlockResource<T, R>} A block resource object.
 *
 * @example
 * // Without source
 * const userResource = createBlockResource(fetchUser);
 *
 * function UserProfile() {
 *   const user = userResource();
 *   return (
 *     <Show when={!user.loading} fallback={<div>Loading...</div>}>
 *       <div>Name: {user().name}</div>
 *     </Show>
 *   );
 * }
 *
 * // With source and mutate
 * const userIdSignal = createBlockSignal(1);
 * const userResource = createBlockResource(userIdSignal, fetchUserById);
 *
 * function UserManager() {
 *   const userId = userIdSignal();
 *   const [user, { mutate, refetch }] = userResource;
 *
 *   return (
 *     <>
 *       <div>Current User: {user()?.name}</div>
 *       <button onClick={() => userIdSignal.set(userId() + 1)}>Next User</button>
 *       <button onClick={() => mutate({ ...user(), name: 'Updated Name' })}>Update Name</button>
 *       <button onClick={() => refetch()}>Refresh</button>
 *     </>
 *   );
 * }
 */
export function createBlockResource<T, R = unknown>(
  fetcher: ResourceFetcher<true, T, R>,
  options: InitializedResourceOptions<NoInfer<T>, true>
): BlockInitializedResource<T, R>;
export function createBlockResource<T, R = unknown>(
  fetcher: ResourceFetcher<true, T, R>,
  options?: ResourceOptions<NoInfer<T>, true>
): BlockResource<T, R>;
export function createBlockResource<T, S, R = unknown>(
  source: ResourceSource<S>,
  fetcher: ResourceFetcher<S, T, R>,
  options: InitializedResourceOptions<NoInfer<T>, S>
): BlockInitializedResource<T, R>;
export function createBlockResource<T, S, R = unknown>(
  source: ResourceSource<S>,
  fetcher: ResourceFetcher<S, T, R>,
  options?: ResourceOptions<NoInfer<T>, S>
): BlockResource<T, R>;
export function createBlockResource<T, S, R>(
  pSource: ResourceSource<S> | ResourceFetcher<S, T, R>,
  pFetcher?: ResourceFetcher<S, T, R> | ResourceOptions<T, S>,
  pOptions?: ResourceOptions<T, S> | undefined
): BlockResource<T, R> {
  return createBlockEntity(
    createResource,
    pSource,
    pFetcher as any,
    pOptions as any
  ) as any;
}

type BlockMemo<T> = Accessor<T>;

/**
 * Creates a block-scoped memo that derives a value from other reactive dependencies.
 *
 * The memo provides referential stability, which is crucial when working with arrays or objects
 * that are derived from multiple reactive sources.
 *
 * Should only be defined at the top level of a module.
 *
 * @deprecated
 * @template T - The type of the memo value.
 * @param {() => T} fn - A function that computes the derived value.
 * @param equal - An optional function that is used to see if the memo should trigger an update
 * @returns {BlockMemo<T>} A block memo object.
 *
 * @example
 * const xSignal = createBlockSignal(0);
 * const ySignal = createBlockSignal(0);
 *
 * // Without memo (not referentially stable)
 * const unstableArray = () => [xSignal(), ySignal()];
 *
 * // With block memo (referentially stable)
 * const stableArray = createBlockMemo(() => [xSignal(), ySignal()]);
 *
 * function PointDisplay() {
 *   return (
 *     <>
 *       <div>Current Point: ({xSignal()}, {ySignal()})</div>
 *       <ChildComponent point={stableArray()} />
 *       <button onClick={() => xSignal.set(x => x + 1)}>Increment X</button>
 *       <button onClick={() => ySignal.set(y => y + 1)}>Increment Y</button>
 *     </>
 *   );
 * }
 *
 * function ChildComponent(props: { point: number[] }) {
 *   // This effect will run only when the array reference changes
 *   createEffect(() => {
 *     console.log("Point updated:", props.point);
 *   });
 *
 *   return <div>Child sees: ({props.point[0]}, {props.point[1]})</div>;
 * }
 */
export function createBlockMemo<T>(
  fn: (...args: any[]) => T,
  equal?: (prev: T | undefined, next: T) => boolean
): BlockMemo<T | undefined> {
  const value = createBlockSignal<T | undefined>(undefined, {
    equals: equal as any,
    internal: true,
  });
  const isInitialized = createBlockSignal(false, {
    internal: true,
  });

  createBlockEffect(() => {
    if (!isInBlock()) return;

    value.set(fn() as any);
    isInitialized.set(true);
  });

  const memoFn = () => {
    const get = value.get;
    if (!isInitialized()) {
      value.set(fn() as any);
      isInitialized.set(true);
    }
    return get();
  };

  return memoFn as BlockMemo<T>;
}

type BlockState<Name extends BlockName = BlockName> = {
  entities: Map<symbol, [any, any]>;
  memos: Map<symbol, () => any>;
  id: string;
  name: Name;
  nested?: NestedState<Name>;
  owner: Owner | null;
  aliasContext?: BlockAliasContext;
};
const BlockContext = createContext<BlockState | undefined>(undefined);

type Creator<T extends any[], R extends [any, any]> = (...args: T) => R;

/**
 * Returns the block data signal cast to Accessor<T | undefined>.
 * @template T - The expected type of the block data
 * @returns The block data signal as Accessor<T | undefined>
 */
export const blockDataSignalAs = <T extends Record<string, any>>(
  key: BlockName
): Accessor<T | undefined> & {
  get: Accessor<T | undefined>;
} => {
  const accessor = () => {
    // this is to prevent a non-related block's effects from running on a mismatching source
    const data = blockDataSignal() as T | undefined;

    // make an exception for start block with chat data
    if (data?.__block === 'start' && key === 'chat') return data;

    return data != null && '__block' in data && data.__block === key
      ? data
      : undefined;
  };

  return Object.assign(accessor, {
    get get() {
      return inBlock(accessor);
    },
  });
};

/**
 * Binds block signal/store getters to a function's first arguments.
 *
 * @param fn Function to bind getters to
 * @param args Block signals or stores
 * @returns New function with bound getters
 */
function _withBlock<A extends any[], B extends any[], R>(
  fn: (...args: [...A, ...B]) => R,
  ...args: A
): (...args: B) => R {
  // @ts-ignore (too strict)
  return fn.bind(this, ...args.map((arg) => arg.get));
}

function isInBlockFn(x: any): x is { block: BlockState | undefined } {
  return x != null && 'block' in x && 'block' != null;
}

export function isInBlock() {
  return useContext(BlockContext) != null;
}

/** You probably shouldn't use this, you probably want createCallback */
export function inBlock<T extends (...args: any[]) => any>(
  this: any,
  fn: T
): T {
  const block = useContext(BlockContext);
  return fn.bind(
    isInBlockFn(this)
      ? this
      : this != null
        ? Object.assign(this, {
            block,
            owner: this?.owner ?? getOwner(),
          })
        : {
            block,
            owner: getOwner(),
          }
  ) as any;
}