fix(types): add generics to the normalize args, clean up comments in index

Author: jonluca

lib/index.ts

@@ -178,19 +178,6 @@ export class $RefParser {
     options: ParserOptions,
     callback: $RefsCallback,
   ): Promise<void>;
-  /**
-   * Parses the given JSON schema and resolves any JSON references, including references in
-   * externally-referenced files.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed and resolved
-   * @param [callback]
-   * - An error-first callback. The second parameter is a {@link $Refs} object containing the resolved JSON references
-   *
-   * @returns
-   * The returned promise resolves with a {@link $Refs} object containing the resolved JSON references
-   */
   async resolve() {
     const args = normalizeArgs(arguments);
 
@@ -231,17 +218,6 @@ export class $RefParser {
     return instance.resolve.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and bundles all external references
-   * into the main JSON schema. This produces a JSON schema that only has *internal* references,
-   * not any *external* references.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the bundled JSON schema object
-   * @returns - The returned promise resolves with the bundled JSON schema object.
-   */
   /**
    * Bundles all referenced files/URLs into a single schema that only has internal `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.
    *
@@ -269,17 +245,6 @@ export class $RefParser {
     return instance.bundle.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and bundles all external references
-   * into the main JSON schema. This produces a JSON schema that only has *internal* references,
-   * not any *external* references.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the bundled JSON schema object
-   * @returns - The returned promise resolves with the bundled JSON schema object.
-   */
   /**
    * Bundles all referenced files/URLs into a single schema that only has internal `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.
    *
@@ -314,16 +279,6 @@ export class $RefParser {
     }
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
-   * That is, all JSON references are replaced with their resolved values.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
-   * @returns - The returned promise resolves with the dereferenced JSON schema object.
-   */
   /**
    * Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
    *
@@ -351,16 +306,6 @@ export class $RefParser {
     return instance.dereference.apply(instance, arguments as any);
   }
 
-  /**
-   * Parses the given JSON schema, resolves any JSON references, and dereferences the JSON schema.
-   * That is, all JSON references are replaced with their resolved values.
-   *
-   * @param [path] - The file path or URL of the JSON schema
-   * @param [schema] - A JSON schema object. This object will be used instead of reading from `path`.
-   * @param [options] - Options that determine how the schema is parsed, resolved, and dereferenced
-   * @param [callback] - An error-first callback. The second parameter is the dereferenced JSON schema object
-   * @returns - The returned promise resolves with the dereferenced JSON schema object.
-   */
   /**
    * Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain any `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
    *

lib/normalize-args.ts

@@ -2,20 +2,18 @@ import { getNewOptions } from "./options.js";
 import type { JSONSchema, SchemaCallback } from "./types";
 import type $RefParserOptions from "./options";
 
-export default normalizeArgs;
-
 // I really dislike this function and the way it's written. It's not clear what it's doing, and it's way too flexible
 // In the future, I'd like to deprecate the api and accept only named parameters in index.ts
-export interface NormalizedArguments {
+export interface NormalizedArguments<T = $RefParserOptions> {
   path: string;
   schema: JSONSchema;
-  options: $RefParserOptions;
+  options: T;
   callback: SchemaCallback;
 }
 /**
  * Normalizes the given arguments, accounting for optional args.
  */
-function normalizeArgs(_args: Partial<IArguments>): NormalizedArguments {
+export function normalizeArgs<T = $RefParserOptions>(_args: Partial<IArguments>): NormalizedArguments<T> {
   let path, schema, options, callback;
   const args = Array.prototype.slice.call(_args) as any[];
 
@@ -61,3 +59,5 @@ function normalizeArgs(_args: Partial<IArguments>): NormalizedArguments {
     callback,
   };
 }
+
+export default normalizeArgs;