globals.d.ts

// Copyright (c) Fensak, LLC.
// SPDX-License-Identifier: MPL-2.0

declare var __projectroot: string;
declare var __dirname: string;
declare var __filename: string;

declare var console: Console;
declare var path: Path;

interface Console {
  /**
   * Logs a message to the console at the `TRACE` level with a newline. Multiple arguments can be passed.
   *
   * Each item that is passed will be JSON strigified and space separated before logging to console.
   *
   * ```js
   * const code = 5;
   * const foo = { msg: "hello world" };
   * console.trace(foo, code);
   * // Prints: TRACE: {"msg":"hello world"} 5
   * ```
   */
  trace(...args: any[]): void;

  /**
   * Logs a message to the console at the `DEBUG` level with a newline. Multiple arguments can be passed.
   *
   * Each item that is passed will be JSON strigified and space separated before logging to console.
   *
   * ```js
   * const code = 5;
   * const foo = { msg: "hello world" };
   * console.debug(foo, code);
   * // Prints: DEBUG: {"msg":"hello world"} 5
   * ```
   */
  debug(...args: any[]): void;

  /**
   * Logs a message to the console at the `INFO` level with a newline. Multiple arguments can be passed.
   *
   * Each item that is passed will be JSON strigified and space separated before logging to console.
   *
   * ```js
   * const code = 5;
   * const foo = { msg: "hello world" };
   * console.info(foo, code);
   * // Prints: INFO: {"msg":"hello world"} 5
   * ```
   */
  info(...args: any[]): void;

  /**
   * Logs a message to the console at the `WARN` level with a newline. Multiple arguments can be passed.
   *
   * Each item that is passed will be JSON strigified and space separated before logging to console.
   *
   * ```js
   * const code = 5;
   * const foo = { msg: "hello world" };
   * console.warn(foo, code);
   * // Prints: WARN: {"msg":"hello world"} 5
   * ```
   */
  warn(...args: any[]): void;

  /**
   * Logs a message to the console at the `ERROR` level with a newline. Multiple arguments can be passed.
   *
   * Each item that is passed will be JSON strigified and space separated before logging to console.
   *
   * ```js
   * const code = 5;
   * const foo = { msg: "hello world" };
   * console.error(foo, code);
   * // Prints: ERROR: {"msg":"hello world"} 5
   * ```
   */
  error(...args: any[]): void;

  /**
   * Alias for info.
   */
  log(...args: any[]): void;
}

interface Path {
  /**
   * Returns the relative path from `base` to `p`. Joining the result to `base` will return `p`.
   *
   * ```js
   * const base = "/home/senc/example"
   * const p = "/home/senc/example/some/path/to/file.js"
   * const r = path.rel(base, p)
   * // r is "some/path/to/file.js"
   * ```
   */
  rel(base: string, p: string): string;
}

declare namespace senc {
  /**
   * Special class that indicates to senc that there is output metadata.
   * This is useful to control the output behavior of the IaC objects, such as specifying the file format and extension.
   */
  class OutData {
    /**
     * @params out_path The path of the output file, relative to the output dir. Only one of out_path or out_ext can be
     *                  set.
     * @params out_ext The extension of the output file, including the preceding `.` (e.g., `.json`).
     * @params out_type The type of the output file. Either JSON or YAML.
     * @params out_prefix An optional string to prepend to the file output. This is useful for adding comments such as a
     *                    license header or a note about the file being autogenerated.
     * @params schema_path An optional path to a schema file to use for validating the rendered data. The path is
     *                     relative to the directory of the entrypoint. Currently only supports jsonschema.
     * @params data The data to output to the output file. This can be any JSON/YAML serializable object.
     */
    constructor(attrs: {
      out_path?: string;
      out_ext?: string;
      out_type: "yaml" | "json";
      out_prefix?: string;
      schema_path?: string;
      data: any;
    });

    /**
     * A special marker function to indicate this is a senc OutData object to the runtime.
     */
    __is_senc_out_data(): void;
  }

  /**
   * A list of OutData objects. We use a class instead of a type so that we can bind a function that indicates this is
   * an OutDataArray to the runtime.
   */
  class OutDataArray extends Array {
    constructor(...args: OutData[]);
    push(...args: OutData[]): any;
    __is_senc_out_data_array(): void;
  }

  /**
   * Import the given file path as a JSON object. This equivalent to loading the file from disk and parsing it using
   * JSON.parse.
   *
   * NOTE:
   * - The provided path must be an absolute path. Use `__dirname` to construct the import path.
   * - For security purposes, this only supports importing files in the project root as configured through the senc CLI.
   *
   * ```js
   * const cfg = await import_json(`${__dirname}/someconfig.json`);
   * ```
   */
  function import_json(p: string): Promise<any>;

  /**
   * Import the given file path as a YAML object. This equivalent to loading the file from disk and parsing it using
   * YAML.parse.
   *
   * NOTE:
   * - The provided path must be an absolute path. Use `__dirname` to construct the import path.
   * - For security purposes, this only supports importing files in the project root as configured through the senc CLI.
   *
   * ```js
   * const cfg = await import_yaml(`${__dirname}/someconfig.yaml`);
   * ```
   */
  function import_yaml(p: string): Promise<any>;
}