Module Augmentation: การต่อเติมโมดูล: การขยายประเภทไลบรารีภายนอกอย่างไร้รอยต่อ

            
// For example, if you want to augment the 'lodash' module
import 'lodash';

declare module 'lodash' {
  interface LoDashStatic {
    // Add new methods or properties here
    myCustomUtility(input: string): string;
  }
}

            

              
                Copy
              
            
          

            
import _ from 'lodash';

const result = _.myCustomUtility('hello from the world!');
console.log(result); // Output: 'hello from the world!' (assuming your implementation returns the input)

            

              
                Copy
              
            
          

            
// src/types/date-fns.d.ts

// Import the module to signal augmentation.
// This line doesn't add any runtime code.
import 'date-fns';

declare module 'date-fns' {
  // We'll augment the main export, which is often a namespace or object.
  // For date-fns, it's common to work with functions directly, so we might
  // need to augment a specific function or the module's export object.
  // Let's assume we want to add a new format function.

  // We need to find the correct place to augment. Often, libraries export
  // a default object or a set of named exports. For date-fns, we can augment
  // the module's default export if it's used that way, or specific functions.
  // A common pattern is to augment the module itself if specific exports aren't directly accessible for augmentation.

  // Let's illustrate augmenting a hypothetical 'format' function if it were a method on a Date object.
  // More realistically, we augment the module to potentially add new functions or modify existing ones.

  // For date-fns, a more direct approach might be to declare a new function
  // in a declaration file that uses date-fns internally.
  // However, to demonstrate module augmentation properly, let's pretend date-fns
  // has a global-like object we can extend.

  // A more accurate approach for date-fns would be to add a new function signature
  // to the module's known exports if we were to modify the core library's types.
  // Since we're extending, let's show how to add a new named export.

  // This is a simplified example assuming we want to add a `formatEuropeanDate` function.
  // In reality, date-fns exports functions directly. We can add our function to the module's exports.

  // To augment the module with a new function, we can declare a new type for the module export.
  // If the library is commonly imported as `import * as dateFns from 'date-fns';`,
  // we'd augment `DateFns` namespace. If imported as `import dateFns from 'date-fns';`,
  // we'd augment the default export type.

  // For date-fns, which exports functions directly, you'd typically define your own
  // function that uses date-fns internally. However, if the library structure allowed
  // for it (e.g., it exported an object of utilities), you could augment that object.

  // Let's demonstrate augmenting a hypothetical utility object.
  // If date-fns exposed something like `dateFns.utils.formatDate`, we could do:

  // interface DateFnsUtils {
  //   formatEuropeanDate(date: Date): string;
  // }
  // interface DateFns {
  //   utils: DateFnsUtils;
  // }

  // A more practical approach for date-fns is to leverage its `format` function and add
  // a new format string or create a wrapper function.
  // Let's show how to augment the module to add a new formatting option for the existing `format` function.
  // This requires knowing the internal structure of `format` and its accepted format tokens.

  // A common technique is to augment the module with a new named export, if the library supports it.
  // Let's assume we are adding a new utility function to the module's exports.
  // We'll augment the module itself to add a new named export.

  // First, let's try to augment the module's export itself.
  // If date-fns was structured like: `export const format = ...; export const parse = ...;`
  // We can't directly add to these. Module augmentation works by merging declarations.

  // The most common and correct way to augment modules like date-fns is to
  // use the module augmentation to declare additional functions or modify
  // existing ones *if* the library's types allow for it.

  // Let's consider a simpler case: extending a library that exports an object.
  // Example: If `libraryX` exports `export default { methodA: () => {} };`
  // `declare module 'libraryX' { interface LibraryXExport { methodB(): void; } }`

  // For date-fns, let's illustrate by adding a new function to the module.
  // This is done by declaring the module and then adding a new member to its export interface.
  // However, date-fns exports functions directly, not an object to be augmented this way.

  // A better way to achieve this for date-fns is by creating a new declaration file that
  // augments the module's capabilities by adding a new function signature.
  // Let's assume we are augmenting the module to add a new top-level function.
  // This requires understanding how the module is intended to be extended.

  // If we want to add a `formatEuropeanDate` function:
  // This is best done by defining your own function and importing date-fns within it.
  // However, to force the issue of module augmentation for the sake of demonstration:

  // We'll augment the module 'date-fns' to include a new function signature.
  // This approach assumes the module exports are flexible enough.
  // A more realistic scenario is augmenting a type returned by a function.

  // Let's assume date-fns has a main object export and we can add to it.
  // (This is a hypothetical structure for demonstration)
  // declare namespace dateFnsNamespace { // If it was a namespace
  //   function format(date: Date, formatString: string): string;
  //   function formatEuropeanDate(date: Date): string;
  // }

  // For practical date-fns augmentation: you might extend the `format` function's
  // capabilities by declaring a new format token it understands.
  // This is advanced and depends on the library's design.

  // A simpler, more common use case: extending a library's object properties.
  // Let's pivot to a more common example that fits module augmentation directly.
  // Suppose we use a hypothetical `apiClient` library.
}

            

              
                Copy
              
            
          

            
// This is how the library might be structured internally
export interface AppConfig {
  apiUrl: string;
  timeout: number;
}

export const config: AppConfig = { ... };

            

              
                Copy
              
            
          

            
// src/types/config.d.ts

import 'config'; // This signals augmentation for the 'config' module.

declare module 'config' {
  // We are augmenting the existing AppConfig interface from the 'config' module.
  interface AppConfig {
    // Add our new property.
    environment: 'development' | 'staging' | 'production';
    // Add another custom property.
    featureFlags: Record;
  }
}

            

              
                Copy
              
            
          

            
// src/config.ts

// We need to import the original configuration to extend it.
// If 'config' exports `config: AppConfig` directly, we would import that.
// For this example, let's assume we are overriding or extending the exported object.

// IMPORTANT: This file needs to physically exist and be compiled.
// It's not just type declarations.

// Import the original configuration (this assumes 'config' exports something).
// For simplicity, let's assume we are re-exporting and adding properties.
// In a real scenario, you might import the original config object and mutate it, 
// or provide a new object that conforms to the augmented type.

// Let's assume the original 'config' module exports an object that we can add to.
// This is often done by re-exporting and adding properties.

// This requires the original module to be structured in a way that allows extension.
// If the original module exports `export const config = { apiUrl: '...', timeout: 5000 };`,
// we can't directly add to it at runtime without modifying the original module or its import.

// A common pattern is to have an initialization function or a default export that is an object.

// Let's redefine the 'config' object in our project, ensuring it has the augmented types.
// This means our project's `config.ts` will provide the implementation.

import { AppConfig as OriginalAppConfig } from 'config';

// Define the extended configuration type, which now includes our augmentations.
// This type is derived from the augmented `AppConfig` declaration.
interface ExtendedAppConfig extends OriginalAppConfig {
  environment: 'development' | 'staging' | 'production';
  featureFlags: Record;
}

// Provide the actual implementation for the configuration.
// This object must conform to the `ExtendedAppConfig` type.
export const config: ExtendedAppConfig = {
  apiUrl: 'https://api.example.com',
  timeout: 10000,
  environment: process.env.NODE_ENV as 'development' | 'staging' | 'production' || 'development',
  featureFlags: {
    newUserDashboard: true,
    internationalPricing: false,
  },
};

// Optionally, if the original library expected a default export and we want to maintain that:
// export default config;

// If the original library exported `config` directly, you might do:
// export * from 'config'; // Import original exports
// export const config = { ...originalConfig, environment: '...', featureFlags: {...} }; // Override or extend

// The key is that this `config.ts` file provides the runtime values for `environment` and `featureFlags`.

            

              
                Copy
              
            
          

            
// src/main.ts

import { config } from './config'; // Import from your extended config file

console.log(`API URL: ${config.apiUrl}`);
console.log(`Current Environment: ${config.environment}`);
console.log(`New User Dashboard Enabled: ${config.featureFlags.newUserDashboard}`);

if (config.environment === 'production') {
  console.log('Running in production mode.');
}

            

              
                Copy
              
            
          

            
// src/types/express.d.ts

import 'express'; // Signal augmentation for the 'express' module

declare global {
  // Augmenting the global Express namespace is also common for frameworks.
  // Or, if you prefer module augmentation for express module itself:
  // declare module 'express' {
  //   interface Request {
  //     user?: { id: string; username: string; roles: string[]; };
  //   }
  // }

  // Using global augmentation is often more straightforward for framework request/response objects.
  namespace Express {
    interface Request {
      // Define the type for the custom user property.
      user?: {
        id: string;
        username: string;
        roles: string[];
        // Add any other relevant user details.
      };
    }
  }
}

            

              
                Copy
              
            
          

            
// src/middleware/auth.ts

import { Request, Response, NextFunction } from 'express';

// This middleware will attach user information to the request object.
export const authenticateUser = (req: Request, res: Response, next: NextFunction) => {
  // In a real app, you'd fetch this from a token, database, etc.
  // For demonstration, we'll hardcode it.
  const isAuthenticated = true; // Simulate authentication

  if (isAuthenticated) {
    // TypeScript now knows req.user is available and has the correct type
    req.user = {
      id: 'user-123',
      username: 'alice_wonder',
      roles: ['admin', 'editor'],
    };
    console.log(`User authenticated: ${req.user.username}`);
  } else {
    console.log('Authentication failed.');
    // Handle unauthenticated access (e.g., send 401)
    return res.status(401).send('Unauthorized');
  }

  next(); // Pass control to the next middleware or route handler
};

            

              
                Copy
              
            
          

            
// src/app.ts

import express, { Request, Response } from 'express';
import { authenticateUser } from './middleware/auth';

const app = express();
const port = 3000;

// Apply the authentication middleware to all routes or specific ones.
app.use(authenticateUser);

// A protected route that uses the augmented req.user property.
app.get('/profile', (req: Request, res: Response) => {
  // TypeScript correctly infers req.user exists and has the expected properties.
  if (req.user) {
    res.send(`Welcome, ${req.user.username}! Your roles are: ${req.user.roles.join(', ')}.`);
  } else {
    // This case should theoretically not be reached if middleware works correctly,
    // but it's good practice for exhaustive checks.
    res.status(401).send('Not authenticated.');
  }
});

app.listen(port, () => {
  console.log(`Server listening on port ${port}`);
});

            

              
                Copy