AsyncAPI Document Processing

Copyexport async function loadDocument(input: string | AsyncAPIObject): Promise<{
  bundled: AsyncAPIObject;
}> {
  try {
    const bundled = await bundle<AsyncAPIObject>(input);
    if (!bundled.asyncapi) {
      throw new Error('Missing required `asyncapi` field.');
    }
 
    return { bundled };
  } catch (e) {
    throw new Error(`[AsyncAPI] Failed to resolve input: ${input}`, {
      cause: e,
    });
  }

Copytype SchemaRecord = Record<
  string,
  string | AsyncAPIObject | (() => Awaitable<string | AsyncAPIObject>)
>;
interface LoadedDocument {
  bundled: AsyncAPIObject;
}
 
export interface AsyncAPIOptions {
  input?: string[] | SchemaRecord;
  disableCache?: boolean;
}

Copyexport function createAsyncAPI(options: AsyncAPIOptions = {}): AsyncAPIServer {
  const { disableCache = false } = options;
  const schemaMap = new Map<string, Promise<LoadedDocument>>();
 
  let resolvedInput: SchemaRecord = {};
  if (Array.isArray(options.input)) {
    for (const item of options.input) resolvedInput[item] = item;
  } else if (options.input) {
    resolvedInput = options.input;
  }
 
  function getSchema(schemaId: string): Promise<LoadedDocument> {
    if (!(schemaId in resolvedInput)) {
      console.warn(
        `[Fumadocs AsyncAPI] the document "${schemaId}" is not listed in the input array, this may be unexpected and won't be cached properly.`,
      );
      return loadDocument(schemaId);
    }
 
    if (!disableCache) {
      const cached = schemaMap.get(schemaId);
      if (cached) return cached;
    }
 
    const raw = resolvedInput[schemaId];
    const output = Promise.resolve(typeof raw === 'function' ? raw() : raw).then(loadDocument);
    if (!disableCache) schemaMap.set(schemaId, output);
    return output;
  }

Copyexport function dereferenceBundledDocument(bundled: AsyncAPIObject): DereferencedDocument {
  const dereferenceMap = new Map<object, string>();
 
  return {
    bundled,
    dereferenced: dereferenceSync(bundled as JSONSchema, {
      setOriginalRef(schema, ref) {
        dereferenceMap.set(schema as object, ref);
      },
    }) as NoReference<AsyncAPIObject>,
    getRawRef(obj: object) {
      return dereferenceMap.get(obj);
    },
  };

Copyexport interface DereferenceOptions {
  /**
   * Return `true` to keep the Reference Object at `pointer` without inlining.
   */
  preserveRef?: (pointer: string) => boolean;
  setOriginalRef?: (schema: JSONSchema, ref: string) => void;
}

Copyexport function dereferenceShallow<T>(schema: T, full: unknown): NoReferenceShallow<T> {
  if (isPlainObject(schema)) {
    if (typeof schema.$ref !== 'string') return schema as never;
 
    const { $ref, ...rest } = schema;
    const resolved = dereferenceShallow(resolveRefSync($ref, full), full);
 
    if (typeof resolved !== 'object') throw new Error(`invalid schema referenced via "${$ref}"`);
    return { ...resolved, ...rest } as never;
  }
 
  return schema as never;

Copyasync function getVirtualFiles(server: AsyncAPIServer, options: AsyncAPISourceOptions) {
  const { baseDir = '', meta = false } = options;
  const { createAutoPreset } = await import('@/utils/pages/preset-auto');
  const { fromSchema } = await import('@/utils/pages/builder');
  const files: VirtualFile<{
    pageData: AsyncAPIPageData;
    metaData: MetaData;
  }>[] = [];
 
  const schemas = await server.getSchemas();
  const builderOptions = createAutoPreset(options);
 
  for (const [id, schema] of Object.entries(schemas)) {
    const list = fromSchema(id, schema.bundled, builderOptions);
 
    onEntries(list);
 
    function onEntry(entry: PageOutput | OperationOutput) {
      const props = getPageProps(entry);
 
      files.push({
        type: 'page',
        path: `${baseDir}/${entry.path}`,
        data: {
          ...entry.info,
          getAsyncAPIPageProps() {
            return {
              payload: {
                bundled: schema.bundled,
              },
              ...props,
            };
          },
          getSchema() {
            return {
              id,
              bundled: schema.bundled,
            };
          },
          ...toStaticData(props, schema.bundled),
          _asyncapi: {
            action: entry.type === 'operation' ? entry.item.action : undefined,
            deprecated: entry.info.deprecated,
          },
        },
      });
    }

Copyexport interface PagesBuilder {
  id: string;
  document: AsyncAPIObject;
  dereferenceShallow: <T>(schema: T) => NoReferenceSwallow<T>;
  create: (entry: OutputEntry) => void;
  routePathToFilePath: (path: string) => string;
}
 
export function fromSchema(
  schemaId: string,
  bundled: AsyncAPIObject,
  config: PagesBuilderConfig,
): OutputEntry[] {
  const files: OutputEntry[] = [];
  const { toPages } = config;
 
  toPages({
    id: schemaId,
    document: bundled,
    dereferenceShallow: (s) => dereferenceShallow(s, bundled),
    create(entry) {
      files.push(entry);
    },
    routePathToFilePath(path) {
      return path
        .toLowerCase()
        .replaceAll('.', '-')
        .split('/')
        .flatMap((v) => {
          if (v.startsWith('{') && v.endsWith('}')) return v.slice(1, -1);
          if (v.length === 0) return [];
          return v;
        })
        .join('/');
    },
  });

Copyexport function toStaticData(
  page: GeneratedPageProps,
  doc: AsyncAPIObject,
): {
  toc: TOCItemType[];
  structuredData: StructuredData;
} {
  const slugger = new Slugger();
  const toc: TOCItemType[] = [];
  const structuredData: StructuredData = { headings: [], contents: [] };
 
  for (const item of page.operations ?? []) {
    const operation = dereferenceShallow(doc.operations?.[item.id], doc);
    if (!operation) continue;
 
    if (page.showTitle) {
      const title = getOperationDisplayName(item.id, operation);
      const id = slugger.slug(title);
 
      toc.push({
        depth: 2,
        title,
        url: `#${id}`,
      });
      structuredData.headings.push({
        content: title,
        id,
      });
    }
 
    if (operation.description) {
      structuredData.contents.push({
        content: operation.description,
        heading: structuredData.headings.at(-1)?.id,
      });
    }
  }
 
  return { toc, structuredData };

Copyinterface OperationConfig extends BaseConfig {
  per?: 'operation';
  groupBy?:
    | 'tag'
    | 'channel'
    | 'none'
    | ((entry: DistributiveOmit<OperationOutput, 'path'>) => string);
  name?: NameFn<OperationOutput> | NameFnOptions;
}
 
interface TagConfig extends BaseConfig {
  per: 'tag';
  name?: NameFn<PageOutput> | NameFnOptions;
}
 
interface SchemaConfig extends BaseConfig {
  per: 'file';
  name?: NameFn<PageOutput> | NameFnOptions;
}
 
export type SchemaToPagesOptions =
  | SchemaConfig
  | TagConfig
  | OperationConfig
  | ({
      per: 'custom';
    } & PagesBuilderConfig);
 
type NameFn<Entry extends OperationOutput | PageOutput = OperationOutput | PageOutput> = (
  this: PagesBuilder,
  output: DistributiveOmit<Entry, 'path'>,
) => string;
 
interface NameFnOptions {
  algorithm?: 'v2' | 'v1';
}
 
interface BaseConfig {
  slugify?: (name: string) => string;
}

Copyfunction group(
  builder: PagesBuilder,
  entries: DistributiveOmit<OperationOutput, 'path'>[],
): OutputEntry[] {
  const groups = new Map<string, OutputGroup>();
  const rest: OutputEntry[] = [];
  const doc = builder.document;
  const { groupBy = 'none' } = options as OperationConfig;
 
  for (const entry of entries) {
    switch (groupBy) {
      case 'channel': {
        const operation = dereferenceShallow(doc.operations?.[entry.item.id], doc);
        const channel = operation ? dereferenceShallow(operation.channel, doc) : undefined;
        const groupName = slugify(channel?.address || entry.item.id);
 
        let group = groups.get(groupName);
        if (!group) {
          group = {
            type: 'group',
            info: {
              title: channel?.title || channel?.address || groupName,
              description: channel?.description,
            },
            entries: [],
            schemaId: builder.id,
            path: groupName,
          };
          groups.set(groupName, group);
        }
 
        group.entries.push({
          ...entry,
          path: path.join(groupName, `${entry.item.action}.mdx`),
        });
        break;
      }
      case 'tag': {
        const operation = dereferenceShallow(doc.operations?.[entry.item.id], doc)!;
        let tags = operation.tags?.map((t) => dereferenceShallow(t, doc));
 
        if (!tags || tags.length === 0) {
          console.warn(
            'When `groupBy` is set to `tag`, make sure a `tags` is defined for every operation schema.',
          );
          tags = [{ name: 'unknown' }];
        }
 
        for (const tag of tags) {
          const groupId = slugify(tag.name);
          let group = groups.get(groupId);
          if (!group) {
            group = {
              type: 'group',
              info: { title: getTagDisplayName(tag), description: tag.description },
              tag,
              entries: [],
              schemaId: builder.id,
              path: groupId,
            };
            groups.set(groupId, group);
          }
 
          group.entries.push({
            ...entry,
            path: path.join(groupId, `${nameFn.call(builder, entry)}.mdx`),
          });
        }
 
        break;
      }

Copylet nameFn: NameFn;
 
if (typeof options.name === 'function') {
  nameFn = options.name as NameFn;
} else {
  const { algorithm = 'v2' } = options.name ?? {};
 
  nameFn = function (result) {
    if (result.type === 'page') {
      if (result.tag) return slugify(result.tag.name);
      const schemaId = result.schemaId;
 
      return schemaId.startsWith('http://') || schemaId.startsWith('https://')
        ? 'index'
        : path.basename(schemaId, path.extname(schemaId));
    }
 
    if (algorithm === 'v2') {
      return result.item.id;
    }
 
    return path.join(this.routePathToFilePath(result.item.id), result.item.action);
  };
}

Copyexport interface PagesToTextOptions {
  imports?: {
    names: string[];
    from: string;
  }[];
  frontmatter?: (
    title: string,
    description: string | undefined,
    context: DocumentContext,
  ) => Record<string, unknown>;
  includeDescription?: boolean;
  addGeneratedComment?: boolean | string;
}

Copyexport function generateDocument(
  frontmatter: unknown,
  content: string,
  options: PagesToTextOptions,
): string {
  const { addGeneratedComment = true, imports } = options;
  const out: string[] = [];
  const banner = dump(removeUndefined(frontmatter as object)).trimEnd();
  if (banner.length > 0) out.push(`---\n${banner}\n---`);
 
  if (addGeneratedComment) {
    let commentContent =
      'This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again.';
 
    if (typeof addGeneratedComment === 'string') {
      commentContent = addGeneratedComment;
    }
 
    commentContent = commentContent.replaceAll('/', '\\/');
    out.push(`{/* ${commentContent} */}`);
  }
 
  if (imports) {
    out.push(
      ...imports
        .map((item) => `import { ${item.names.join(', ')} } from ${doubleQuote(item.from)};`)
        .join('\n'),
    );
  }
 
  out.push(content);
  return out.join('\n\n');
}

Copyexport function mergeTraits<T extends Record<string, unknown>>(
  target: T,
  traits: Record<string, unknown>[],
): T {
  let result: Record<string, unknown> = { ...target };
  for (const trait of traits) {
    result = mergeTraitLayer(result, trait);
  }
  return result as T;
}
 
function mergeTraitLayer(
  target: Record<string, unknown>,
  trait: Record<string, unknown>,
): Record<string, unknown> {
  const result: Record<string, unknown> = { ...target };
 
  for (const [key, traitValue] of Object.entries(trait)) {
    if (key === 'traits') continue;
 
    const targetValue = result[key];
    if (targetValue === undefined) {
      result[key] = traitValue;
    } else if (isPlainObject(targetValue) && isPlainObject(traitValue)) {
      result[key] = mergeTraitLayer(targetValue, traitValue);
    }
  }
 
  return result;
}

Copyexport function applyOperationTraits(
  operation: NoReference<OperationObject>,
): NoReference<OperationObject> {
  const traits = operation.traits;
  if (!traits || traits.length === 0) return operation;
 
  const { traits: _, ...base } = operation;
  return mergeTraits(base, traits);
}
 
export function applyMessageTraits(
  message: NoReference<MessageObject>,
): NoReference<MessageObject> {
  const traits = message.traits;
  if (!traits || traits.length === 0) return message;
 
  const { traits: _, ...base } = message;
  return mergeTraits(base, traits);
}