generators.mjs

'use strict';

import { coerce, major } from 'semver';

import { lazy } from './misc.mjs';

/**
 * Groups all the API metadata nodes by module (`api` property) so that we can process each different file
 * based on the module it belongs to.
 *
 * @param {Array<import('../generators/metadata/types').MetadataEntry>} nodes The API metadata Nodes to be grouped
 */
export const groupNodesByModule = nodes => {
  /** @type {Map<string, Array<import('../generators/metadata/types').MetadataEntry>>} */
  const groupedNodes = new Map();

  for (const node of nodes) {
    if (!groupedNodes.has(node.api)) {
      groupedNodes.set(node.api, []);
    }

    groupedNodes.get(node.api).push(node);
  }

  return groupedNodes;
};

/**
 * Parses the SemVer string into a Node.js-alike version
 *
 * @param {import('semver').SemVer} version The version to be parsed
 */
export const getVersionFromSemVer = version =>
  version.minor === 0
    ? `${version.major}.x`
    : `${version.major}.${version.minor}.x`;

/**
 * @TODO: This should not be necessary, and indicates errors within the API docs
 * @TODO: Hookup into a future Validation/Linting API
 *
 * This is a safe fallback to ensure that we always have a SemVer compatible version
 * even if the input is not a valid SemVer string
 *
 * @param {string|import('semver').SemVer} version SemVer compatible version (maybe)
 * @returns {import('semver').SemVer} SemVer compatible version
 */
export const coerceSemVer = version => {
  const coercedVersion = coerce(version);

  if (coercedVersion === null) {
    // @TODO: Linter to complain about invalid SemVer strings
    return coerce('0.0.0-REPLACEME');
  }

  return coercedVersion;
};

/**
 * Gets compatible versions for an entry
 *
 * @param {string | import('semver').SemVer} introduced
 * @param {Array<import('../parsers/types').ReleaseEntry>} releases
 * @returns {Array<import('../parsers/types').ReleaseEntry>}
 */
export const getCompatibleVersions = (introduced, releases) => {
  const coercedMajor = major(coerceSemVer(introduced));
  // All Node.js versions that support the current API; If there's no "introduced_at" field,
  // we simply show all versions, as we cannot pinpoint the exact version
  return releases.filter(release => release.version.major >= coercedMajor);
};

/**
 * Assigns properties from one or more source objects to the target object
 * **without overwriting existing keys** in the target.
 *
 * Similar to `Object.assign`, but preserves the target's existing keys.
 * The target object is mutated in place.
 *
 * @param {Object} target - The object to assign properties to.
 * @param {Object} source - The source object
 */
export const leftHandAssign = (target, source) =>
  Object.keys(source).forEach(k => k in target || (target[k] = source[k]));

/**
 * Transforms an object to JSON output consistent with the JSON version.
 * @param {import('../generators/legacy-json/types').Section} section - The source object
 * @param {any[]} args
 * @returns {string} - The JSON output
 */
export const legacyToJSON = (
  {
    api,
    type,
    source,
    introduced_in,
    meta,
    stability,
    stabilityText,
    classes,
    methods,
    properties,
    miscs,
    modules,
    globals,
  },
  ...args
) =>
  JSON.stringify(
    api == null
      ? {
          // all.json special order
          miscs,
          modules,
          classes,
          globals,
          methods,
        }
      : {
          type,
          source,
          introduced_in,
          meta,
          stability,
          stabilityText,
          classes,
          methods,
          properties,
          miscs,
          // index.json shouldn't have a `modules` key:
          ...(api === 'index' ? undefined : { modules }),
          globals,
        },
    ...args
  );

/**
 * Creates a generator with the provided metadata.
 * @template T
 * @param {T} metadata - The metadata object
 * @returns {Promise<T>} The metadata object with generator methods
 */
export const createLazyGenerator = metadata => {
  const generator = lazy(
    () => import(`../generators/${metadata.name}/generate.mjs`)
  );
  return {
    ...metadata,
    /**
     * Processes a chunk using the lazily-loaded generator.
     * @param {...any} args - Arguments to pass to the processChunk method
     * @returns {Promise<any>} Result from the generator's processChunk method
     */
    processChunk: async (...args) => (await generator()).processChunk(...args),
    /**
     * Generates output using the lazily-loaded generator.
     * @param {...any} args - Arguments to pass to the generate method
     * @returns {Promise<any>} Result from the generator's generate method
     */
    generate: async (...args) => (await generator()).generate(...args),
  };
};