optional-require
Description: Documentation for optional-require

## Index

### Type aliases

- LogFunction
- OptionalRequireFunction
- OptionalRequireOpts

### Variables

- optionalRequire
- optionalRequireCwd

### Functions

- makeOptionalRequire
- setDefaultLog
- tryRequire
- tryResolve

## Type aliases

### LogFunction

LogFunction: (message: string, path: string) => void

- Defined in index.ts:44

function to log in case require module was not found

params

  message - message to log

params

  path - path of the module that user tried to require

#### Type declaration

- - (message: string, path: string): void

  - #### Parameters

    - ##### message: string

    - ##### path: string

    #### Returns void

### OptionalRequireFunction

OptionalRequireFunction<T>: { log: LogFunction; resolve: (path: string, opsOrMsg?: OptionalRequireOpts | string | true) => string }

- Defined in index.ts:218

function to require a module with optional handling in case it's not found or fail to require

#### Type parameters

- #### T = any

#### Type declaration

- - (path: string, optsOrMsg?: string | true | OptionalRequireOpts): T

  - #### Parameters

    - ##### path: string

      path to module to require

    - ##### Optional optsOrMsg: string | true | OptionalRequireOpts

      options or message to log when module not found

    #### Returns T

- ##### log: LogFunction

  function to log message, default to use `console.log`, you can replace this with another function.

- ##### resolve: (path: string, opsOrMsg?: OptionalRequireOpts | string | true) => string

  resolve the module's full path

  param

    path to module to resolve

  param

    options or message to log when module not found

  returns

    resolve result

  - - (path: string, opsOrMsg?: OptionalRequireOpts | string | true): string

    - #### Parameters

      - ##### path: string

      - ##### Optional opsOrMsg: OptionalRequireOpts | string | true

      #### Returns string

### OptionalRequireOpts

OptionalRequireOpts: { default?: unknown; fail?: (err: Error) => unknown; log?: LogFunction; message?: true | string; notFound?: (err: Error) => unknown; require?: NodeRequire; resolve?: boolean }

- Defined in index.ts:49

Options for calling optionalRequire

#### Type declaration

- ##### Optional default?: unknown

  The value to return if error was `MODULE_NOT_FOUND` but `notFound` is not provided.

- ##### Optional fail?: (err: Error) => unknown

  `fail` is a function. If error from require was something other than `MODULE_NOT_FOUND`, for example, the module contains syntax error, then:

  - call `fail` if it's provided
  - else rethrow the error
  remark

    This is a separate callback from `notFound` so user can handle real `MODULE_NOT_FOUND` exception separately, or let the `default` be returned.

  param

    the error from require

  - - (err: Error): unknown

    - #### Parameters

      - ##### err: Error

      #### Returns unknown

- ##### Optional log?: LogFunction

  function to log the module not found message, default log function uses `console.log`

- ##### Optional message?: true | string

  Tell optional require to log a message if the module is not found.

  - note: it doesn't log if the error is not due to the module not found

  This field can have these values:

  1. `true` - log with default message
  2. string - a string to prepend to the message being logged
  remarks

    to further customize logging, set the `log` function.

- ##### Optional notFound?: (err: Error) => unknown

  `notFound` is a function. If error from require was `MODULE_NOT_FOUND`, then:

  - call `notFound` if it's provided
  - else return the `default` value.
  remark

    in case the error was not `MODULE_NOT_FOUND`, will instead call the `fail` function if it's provided.

  param

    the error from require

  - - (err: Error): unknown

    - #### Parameters

      - ##### err: Error

      #### Returns unknown

- ##### Optional require?: NodeRequire

  `require` is the node.js require function from caller's context.

  If not provided, then use the one received when creating the optional require function

- ##### Optional resolve?: boolean

  If `true`, then do an optional `require.resolve` and return the full path

## Variables

### Const optionalRequire

optionalRequire: OptionalRequireFunction<any> = ...

- Defined in index.ts:276

A default optionalRequire function using `require` from optional-require's context.

remarks

  because `require` is from optional-require's context, you won't be able to do `optionalRequire("./my-module")`.

  You can still override the `require` using `options.require` with the one from your calling context.

### Const optionalRequireCwd

optionalRequireCwd: OptionalRequireFunction<any> = ...

- Defined in index.ts:287

An optionalRequire function using `require` from CWD context

remarks

  because `require` is from CWD context, if you do `optionalRequireCwd("./my-module")` then it will look for `my-module` in CWD.

remarks

  You can still override the `require` using `options.require` with the one from your calling context.

## Functions

### makeOptionalRequire

- makeOptionalRequire<T>(callerRequire: NodeRequire, log?: (message: string, path: string) => void): OptionalRequireFunction<T>

- - Defined in index.ts:246

  Make an optional require function, using the `require` from caller's context.

  #### Type parameters

  - #### T = any

  #### Parameters

  - ##### callerRequire: NodeRequire

    `require` from caller's context

  - ##### Optional log: (message: string, path: string) => void

    function to log if module is not found

    - - (message: string, path: string): void

      - #### Parameters

        - ##### message: string

        - ##### path: string

        #### Returns void

  #### Returns OptionalRequireFunction<T>

  required module

### setDefaultLog

- setDefaultLog(log: LogFunction): void

- - Defined in index.ts:123

  #### Parameters

  - ##### log: LogFunction

  #### Returns void

### tryRequire

- tryRequire(callerRequire: NodeRequire, path: string, optsOrMsg?: OptionalRequireOpts | string | true): unknown

- - Defined in index.ts:187

  try to require a module with optional handling in case it's not found or fail to require

  #### Parameters

  - ##### callerRequire: NodeRequire

    `require` from caller context

  - ##### path: string

    path to module to require

  - ##### Optional optsOrMsg: OptionalRequireOpts | string | true

    options or message to log in case of exceptions

  #### Returns unknown

  require result

### tryResolve

- tryResolve(callerRequire: NodeRequire, path: string, optsOrMsg?: OptionalRequireOpts | string | true): string

- - Defined in index.ts:205

  try to resolve a module with optional handling in case it's not found or fail to require

  #### Parameters

  - ##### callerRequire: NodeRequire

    `require` from caller context

  - ##### path: string

    path to module to require

  - ##### Optional optsOrMsg: OptionalRequireOpts | string | true

    options or message to log in case of exceptions

  #### Returns string

  resolve result

Generated using TypeDoc