0
# util-deprecate
1

2
The Node.js `util.deprecate()` function with browser support. Provides a cross-platform implementation for marking functions as deprecated with configurable warning behavior.
3

4
## Package Information
5

6
- **Package Name**: util-deprecate
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install util-deprecate`
10

11
## Core Imports
12

13
```javascript
14
const deprecate = require('util-deprecate');
15
```
16

17
For ES modules (using a bundler like webpack or browserify):
18

19
```javascript
20
import deprecate from 'util-deprecate';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const deprecate = require('util-deprecate');
27

28
// Mark a function as deprecated
29
const oldFunction = function() {
30
  return 'This function works but is deprecated';
31
};
32

33
// Create a deprecated version with a custom warning message
34
const deprecatedFunction = deprecate(
35
  oldFunction, 
36
  'oldFunction() is deprecated, use newFunction() instead'
37
);
38

39
// Export the deprecated function
40
exports.oldFunction = deprecatedFunction;
41

42
// When users call the function, they'll see the warning once:
43
// deprecatedFunction(); // Logs: "oldFunction() is deprecated, use newFunction() instead"
44
// deprecatedFunction(); // No warning on subsequent calls
45
```
46

47
## Architecture
48

49
util-deprecate uses a dual-implementation approach to provide cross-platform compatibility:
50

51
- **Node.js Environment**: Directly uses the native `util.deprecate()` function from Node.js core, ensuring full compatibility with Node.js deprecation system and environment variables
52
- **Browser Environment**: Provides a custom implementation that mimics Node.js behavior while safely handling browser-specific constraints like localStorage access and sandboxed environments
53
- **Automatic Selection**: The appropriate implementation is selected automatically via package.json `browser` field when using bundlers like browserify or webpack
54

55
## Capabilities
56

57
### Function Deprecation
58

59
Mark functions as deprecated with customizable warning messages and behavior control through environment configuration.
60

61
```javascript { .api }
62
/**
63
 * Mark that a method should not be used.
64
 * Returns a modified function which warns once by default.
65
 * 
66
 * @param {Function} fn - the function to deprecate
67
 * @param {String} msg - the string to print to the console when fn is invoked
68
 * @returns {Function} a new "deprecated" version of fn
69
 */
70
function deprecate(fn, msg);
71
```
72

73
**Parameters:**
74
- `fn` (Function): The function to deprecate
75
- `msg` (String): The warning message to display when the deprecated function is invoked
76

77
**Returns:**
78
- `Function`: A new "deprecated" wrapper version of the original function that:
79
  - Executes the original function with the same arguments and context
80
  - Shows a deprecation warning only on the first invocation
81
  - Respects configuration flags for warning behavior
82

83
**Warning Behavior:**
84

85
The deprecation warning behavior can be controlled through different mechanisms depending on the environment:
86

87
**Node.js Environment:**
88
- Uses Node.js built-in `util.deprecate()` function
89
- Respects standard Node.js environment variables and process configuration
90

91
**Browser Environment:**
92
- Uses localStorage configuration flags:
93
  - `localStorage.noDeprecation = 'true'`: Disables all deprecation warnings
94
  - `localStorage.throwDeprecation = 'true'`: Throws an Error instead of showing a warning
95
  - `localStorage.traceDeprecation = 'true'`: Uses `console.trace()` to show stack trace instead of `console.warn()`
96

97
**Usage Examples:**
98

99
```javascript
100
const deprecate = require('util-deprecate');
101

102
// Simple deprecation
103
const oldApi = deprecate(
104
  function(data) { return data.toUpperCase(); },
105
  'oldApi() is deprecated, use newApi() instead'
106
);
107

108
// Deprecate a class method
109
class MyClass {
110
  constructor() {
111
    this.newMethod = this.newMethod.bind(this);
112
    this.oldMethod = deprecate(
113
      this.oldMethod.bind(this),
114
      'MyClass.oldMethod() is deprecated, use MyClass.newMethod() instead'
115
    );
116
  }
117
  
118
  newMethod(data) {
119
    return data.toLowerCase();
120
  }
121
  
122
  oldMethod(data) {
123
    return this.newMethod(data);
124
  }
125
}
126

127
// Configure warning behavior in browser
128
if (typeof localStorage !== 'undefined') {
129
  // Disable all deprecation warnings
130
  localStorage.noDeprecation = 'true';
131
  
132
  // Or throw errors instead of warnings
133
  localStorage.throwDeprecation = 'true';
134
  
135
  // Or show stack traces
136
  localStorage.traceDeprecation = 'true';
137
}
138
```
139

140
## Environment-Specific Implementation
141

142
The package provides different implementations based on the runtime environment:
143

144
**Node.js (`node.js`):**
145
- Re-exports the native `util.deprecate` function from Node.js core
146
- Full compatibility with Node.js deprecation system
147
- Supports all Node.js deprecation environment variables and configuration
148

149
**Browser (`browser.js`):**
150
- Custom implementation for browser compatibility via browserify
151
- Safe localStorage access with error handling for sandboxed environments
152
- Configurable warning output: `console.warn()`, `console.trace()`, or thrown Error
153
- Once-only warning behavior maintained across function calls
154

155
The appropriate implementation is automatically selected based on the environment when using a bundler like browserify or webpack that respects the `browser` field in package.json.