Determining the appropriate scenarios for using declare module and declare namespace

Question

Determining the appropriate scenarios for using declare module and declare namespace

Recently, I came across a repository where I was exploring the structure of TypeScript projects. One interesting thing I found was their typings file:

/**
 * react-native-extensions.d.ts
 *
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT license.
 *
 * Type definition file that extends the public React Native type definition file.
 */

    import * as React from 'react';
    import * as RN from 'react-native';
    import * as RNW from 'react-native-windows';
    
    declare module 'react-native' {
        interface ExtendedViewProps extends RN.ViewProps

 {

Now, I'm puzzled about when to use declare module or declare namespace. Although I found a stackoverflow answer explaining the difference between them, it didn't provide guidance on when and which one to use.

In the TypeScript handbook, there is an explanation of different ways to organize code using modules and namespaces in TypeScript, but it was quite confusing for me to understand.

typescript

Answer 1

Answer №1

In my personal experience, the utilization of declare module and declare namespace has proven to be most valuable within the realm of Declaration Merging. Essentially, since it is possible in JavaScript to patch the prototypes of classes or append properties to third-party classes, declaration merging provides a method of exposing these dynamic modifications to the behavior of an object in the type system.

For instance, let's consider the Request object from express.js. The API offered by Express does not inherently provide a field for a request ID. However, within the context of JavaScript, it is customary to simply modify the request object accordingly.

middlware(req, res, next) {
  req.id = uuid.v4()
  next()
}

Nevertheless, TypeScript does not approve of this practice because, according to the standard express type definitions, id is not recognized as a property of request. This issue can be resolved using the combination of declare module and a declaration similar to the following:

import { Request } from "express";
import core from "express-serve-static-core";

declare module "express" {
  interface Request<
    P extends core.Params = core.ParamsDictionary,
    ResBody = any,
    ReqBody = any,
    ReqQuery = core.Query
  > {
    /**
     * An optional request id that can be attached to the request. Useful for correlating
     * and searching log messages.
     */
    id?: string;
  }
}

By including this file within your type path, TypeScript will readily accept the optional id property of Request. The use case for declare namespace is quite similar.

Answer 2

In my personal experience, the utilization of declare module and declare namespace has proven to be most valuable within the realm of Declaration Merging. Essentially, since it is possible in JavaScript to patch the prototypes of classes or append properties to third-party classes, declaration merging provides a method of exposing these dynamic modifications to the behavior of an object in the type system.

For instance, let's consider the Request object from express.js. The API offered by Express does not inherently provide a field for a request ID. However, within the context of JavaScript, it is customary to simply modify the request object accordingly.

middlware(req, res, next) {
  req.id = uuid.v4()
  next()
}

Nevertheless, TypeScript does not approve of this practice because, according to the standard express type definitions, id is not recognized as a property of request. This issue can be resolved using the combination of declare module and a declaration similar to the following:

import { Request } from "express";
import core from "express-serve-static-core";

declare module "express" {
  interface Request<
    P extends core.Params = core.ParamsDictionary,
    ResBody = any,
    ReqBody = any,
    ReqQuery = core.Query
  > {
    /**
     * An optional request id that can be attached to the request. Useful for correlating
     * and searching log messages.
     */
    id?: string;
  }
}

By including this file within your type path, TypeScript will readily accept the optional id property of Request. The use case for declare namespace is quite similar.

Determining the appropriate scenarios for using declare module and declare namespace

Answer №1

Similar questions

Jest tests are failing to render React IonDateTime component

Enhancing collaboration: Seamlessly sharing interface/interface/model files in the integration of

Guide on creating a Typescript function with a strongly typed argument

Can you explain the functionality of `property IN array` in the TypeORM query builder?

Detect errors in the `valueChanges` subscription of Firestore and attempt a retry if an error occurs

Tips for creating a sequelize transaction in TypeScript

Achieving a delayed refetch in React-Query following a POST请求

Bring in typings from a package with an alternate title

Is there a way to determine if a string is empty, even if it contains hard returns?

Modifying a property in a nested layout through a page in Next.js 13

Ways to encourage children to adopt a specific trait

Is it possible to compile using Angular sources while in Ivy's partial compilation mode?

Compiling TypeScript to JavaScript with Deno

Angular 5 Image Upload - Transfer your images with ease

Using Angular Material to dynamically hide columns in a table that is being created on the fly

Initializing various objects on the same interface type array in one line

In Angular, when a component is clicked, it is selecting entire arrays instead of just a single item at a

When working with TypeScript, it's important to note that an implicit 'any' type may occur when trying to use an expression of type 'string' to index a specific type

Accessing file uploads in Angular 2

What steps should I take to ensure that a cookie has been properly set before utilizing it?