types.ts

import type { Context, Element, RawHtml, Utilities } from "./htmlisp/types.ts";
type Utility = {
  utility: string;
  parameters?: (string | Utility)[];
};

type Props = Record<string, string | undefined>;
type Attributes = Record<string, any>;
type Category = { id: string; title: string; url: string };

type DataContext = Record<string, unknown> | Record<string, unknown>[];
type ParentCategory = { title: string; children: Category[] };

type DataSourcesModule = {
  init(o: DataSourcesApi): DataSources;
};
type DataSourcesApi = {
  load: LoadApi;
  render: Render;
  renderRaw: RenderRaw;
  renderSync: RenderSync;
};
type Render = (
  o: {
    componentName?: string;
    htmlInput?: string;
    context?: Context;
    props?: Context;
  },
) => Promise<string>;
type RenderSync = (
  o: {
    componentName?: string;
    htmlInput?: string;
    context?: Context;
    props?: Context;
  },
) => string;
type RenderRaw = (value: unknown) => RawHtml;

type DataSource = { operation: string; parameters?: unknown[] };
type NamedDataSource = DataSource & { name: string };
type RouteDataSources = Record<string, DataSource> | NamedDataSource[];
type DataSources = Record<string, (...args: any) => unknown>;
type BuildDiagnostics = {
  dataSourceCache?: Map<string, Promise<unknown>>;
  recordDataSourceCall?(result: {
    cacheHit: boolean;
    durationMs: number;
    name: string;
    operation: string;
    parameters: unknown[];
  }): void;
  recordComponentRender?(result: {
    componentName: string;
    durationMs: number;
    url?: string;
  }): void;
};

type LoadedPlugin = {
  plugin: {
    meta: Plugin["meta"];
    api: PluginApi;
    context: Context;
    moduleTasks?: Tasks;
    tasks: Tasks;
  };
  tasks: Tasks;
};
type PluginsDefinition = {
  env: Record<string, string>;
  plugins: PluginOptions[];
};
type PluginOptions = {
  // The idea is that the consumer can provide an already loaded module. This
  // is needed for environments like the browser or edge computing platforms.
  module: Plugin;
  path: never;
  options: Record<string, unknown>;
} | {
  module: never;
  path: string;
  options: Record<string, unknown>;
};

type Meta = Record<string, unknown>;
type Mode = "development" | "production";

// TODO: Rename as PluginModule for clarity
type Plugin<O = Record<string, unknown>, C = Context> = {
  meta: {
    name: string;
    description: string;
    dependsOn?: string[];
  };
  init(args: PluginParameters<O>): Promise<PluginApi<C>> | PluginApi<C>;
};

type PluginParameters<O = Record<string, unknown>> = {
  cwd: string;
  load: LoadApi;
  renderComponent: Render;
  renderComponentSync: RenderSync;
  mode: Mode;
  outputDirectory: string;
  options: O;
};

type InitLoadApi = (tasks: Tasks) => LoadApi;
type LoadApi = {
  dir({ path, extension, recursive, type }: {
    path: string;
    type: string;
    extension?: string;
    recursive?: boolean;
  }): Promise<{ name: string; path: string }[]>;
  json<T>({ path, type }: { path: string; type: string }): Promise<T>;
  module<T>({ path, type }: { path: string; type: string }): Promise<T>;
  textFile(path: string): Promise<string>;
  textFileSync(path: string): string;
};

type PluginApi<C = Context> = {
  // Set up initial plugin context during plugin initialization phase.
  initPluginContext?(): C | Promise<C>;
  // Send messages to other plugins before other hooks are applied. This
  // is useful for giving specific instructions on what to do.
  sendMessages?(
    { send, pluginContext }: { send: Send; pluginContext: C },
  ): Promise<Tasks | void> | Tasks | void;
  // Return additional tasks to perform per build preparation
  prepareBuild?(
    { send, pluginContext }: { send: Send; pluginContext: C },
  ): Promise<Tasks | void> | Tasks | void;
  // Return additional tasks to perform per build finishing
  finishBuild?(
    { send, pluginContext }: { send: Send; pluginContext: C },
  ): Promise<Tasks | void> | Tasks | void;
  // Optional cleanup for global operations that should happen only once per process
  cleanUp?(
    { routes, pluginContext }: { routes: Routes; pluginContext: C },
  ): void;
  // Run setup before context is resolved or add something to it
  prepareContext?(o: {
    send: Send;
    route: Route;
    url: string;
    pluginContext: C;
  }):
    | Promise<{ context: Record<string, unknown> } | void>
    | {
      context: Record<string, unknown>;
    }
    | void;
  beforeEachRender?(o: {
    context: Context;
    matchRoute: MatchRoute;
    send: Send;
    route: Route;
    url: string;
    pluginContext: C;
  }):
    | Promise<
      Tasks | void
    >
    | Tasks
    | void;
  renderLayout?(o: {
    buildDiagnostics?: BuildDiagnostics;
    matchRoute: MatchRoute;
    route: Route;
    context: Context;
    send: Send;
    url: string;
    pluginContext: C;
  }): Promise<string> | string;
  renderComponent?(o: {
    buildDiagnostics?: BuildDiagnostics;
    matchRoute: MatchRoute;
    componentName?: string;
    htmlInput?: string;
    context: Context;
    props: Context;
    pluginContext: C;
  }): Promise<string>;
  renderComponentSync?(o: {
    buildDiagnostics?: BuildDiagnostics;
    matchRoute: MatchRoute;
    componentName?: string;
    htmlInput?: string;
    context: Context;
    props: Context;
    pluginContext: C;
  }): string;
  afterEachRender?(o: {
    markup: string;
    context: Context;
    route: Route;
    send: Send;
    url: string;
    pluginContext: C;
  }): Promise<{ markup: string }> | { markup: string };
  onMessage?(o: { message: SendMessageEvent; pluginContext: C; send: Send }):
    | void
    | {
      send?: SendMessageEvent[];
      pluginContext?: Partial<C>;
      result?: unknown;
    }
    | Promise<
      void | {
        send?: SendMessageEvent[];
        pluginContext?: Partial<C>;
        result?: unknown;
      }
    >;
  getAllRoutes?(o: {
    buildDiagnostics?: BuildDiagnostics;
    pluginContext: C;
    routeConcurrency?: number;
  }):
    | Promise<{ routes: Record<string, Route>; tasks: Tasks }>
    | { routes: Record<string, Route>; tasks: Tasks };
  matchRoute?(
    url: string,
    pluginContext: C,
    buildDiagnostics?: BuildDiagnostics,
  ): Promise<Route | undefined> | undefined;
  onTasksRegistered?({ send, tasks }: { tasks: Tasks; send: Send }): void;
};

type Send = (
  pluginName: string,
  { type, payload }: SendMessageEvent,
) => Promise<unknown> | unknown;

// TODO: Compose this from plugin types
// TODO: Model an accurate return type for each event (fixes plugins.ts a lot)
type SendMessageEvent =
  | { type: "ping"; payload: undefined }
  | { type: "getStyleSetupPath"; payload: undefined }
  | { type: "getMeta"; payload: undefined }
  | { type: "getComponents"; payload: undefined }
  | {
    type: "getRenderContext";
    payload: { matchRoute: MatchRoute; url: string };
  }
  | { type: "getComponentDependencyGraph"; payload: undefined }
  | { type: "updateComponents"; payload: Record<string, Element> }
  | { type: "getRenderer"; payload: string }
  // websocket plugin
  | { type: "reloadPage"; payload: undefined }
  | {
    type: "fileChanged";
    payload: {
      path: string;
      // Keep the event shape inline so shared types do not depend on a runtime-specific fs event type.
      event: {
        /** The kind/type of the file system event. */
        kind:
          | "any"
          | "access"
          | "create"
          | "modify"
          | "remove"
          | "other"
          | "rename";
        /** An array of paths that are associated with the file system event. */
        paths: string[];
        /** Any additional flags associated with the event. */
        flag?: "rescan";
      };
      extension: string;
      name: string;
      type: string;
    };
  }
  // router plugin
  | {
    type: "addDynamicRoute";
    payload: {
      path: string;
    };
  }
  // editor plugin
  | {
    type: "addGlobalScripts";
    payload: {
      type: string;
      src: string;
    }[];
  }
  | {
    type: "addScripts";
    payload: {
      isExternal?: boolean;
      localPath: string;
      remotePath: string;
      name: string;
      externals?: string[];
    }[];
  };

// This type is specific to breezewind-router so it probably doesn't belong here
type Routes = Record<string, Route>;
type Route = {
  context?: DataContext;
  meta?: Meta;
  // TODO: This should come as an extension from the renderer plugin
  // if it is enabled
  layout: string;
  // TODO: This should come as an extension from the script plugin
  // if it is enabled
  scripts?: { name: string }[]; // These point to scripts directory by name
  routes?: Routes;
  parentDataSources?: Record<string, unknown>;
  dataSources?: RouteDataSources;
  expand?: {
    context?: DataContext;
    matchBy?: {
      indexer: DataSource;
      slug: string;
      name?: string;
    };
    dataSources?: RouteDataSources;
    layout: string;
    scripts?: { name: string }[];
  };
};
type Scripts = Script[];
type Script = { type: string; src: string };

type Tasks = (BuildWorkerEvent)[];
type BuildWorkerEvent =
  | {
    type: "init";
    payload: {
      cwd: string;
      pluginDefinitions: PluginOptions[];
      outputDirectory: string;
    };
  }
  | {
    type: "build";
    payload: {
      route: Route;
      dir: string;
      url: string;
    };
  }
  | {
    type: "listDirectory";
    payload: { path: string; type: string };
  }
  | {
    type: "loadJSON";
    payload: { path: string; type: string };
  }
  | {
    type: "loadModule";
    payload: { path: string; type: string };
  }
  | {
    type: "readTextFile";
    payload: { path: string; type: string };
  }
  | {
    type: "writeFile";
    payload: {
      outputDirectory: string;
      file: string;
      data: string | Uint8Array;
    };
  }
  | {
    type: "writeTextFile";
    payload: {
      outputDirectory: string;
      file: string;
      data: string | Uint8Array;
    };
  }
  | {
    type: "copyFiles";
    payload: {
      inputDirectory: string;
      outputDirectory: string;
      outputPath: string;
    };
  };
type BuildWorkerMessageTypes = "finished" | "addTasks";

type MatchRoute = (url: string) => Promise<Route | undefined>;
type UtilityInitContext = {
  load: LoadApi;
  raw: RenderRaw;
  render: Render;
  renderRaw: RenderRaw;
  renderSync: RenderSync;
  matchRoute: MatchRoute;
  url: string;
};
type GlobalUtilities = {
  init: (o: UtilityInitContext) => Utilities;
};

export type {
  Attributes,
  BuildDiagnostics,
  BuildWorkerEvent,
  BuildWorkerMessageTypes,
  Category,
  Context,
  DataContext,
  DataSource,
  DataSources,
  DataSourcesApi,
  DataSourcesModule,
  GlobalUtilities,
  InitLoadApi,
  LoadApi,
  LoadedPlugin,
  MatchRoute,
  Meta,
  Mode,
  ParentCategory,
  Plugin,
  PluginApi,
  PluginOptions,
  PluginParameters,
  PluginsDefinition,
  Props,
  RawHtml,
  Render,
  RenderRaw,
  RenderSync,
  Route,
  RouteDataSources,
  Routes,
  Scripts,
  Send,
  Tasks,
  Utilities,
  Utility,
  UtilityInitContext,
};