0
# Scoped Loggers
1

2
Create hierarchical scoped loggers with inheritance for organized logging across different modules and components. Scoped loggers help organize log output by adding contextual prefixes while maintaining all functionality of the parent logger.
3

4
## Capabilities
5

6
### Scope Creation
7

8
Create scoped logger instances that inherit all configuration and custom loggers from the parent.
9

10
```javascript { .api }
11
/**
12
 * Create a scoped logger instance
13
 * @param name - One or more scope names (nested scopes supported)
14
 * @returns New Signale instance with the specified scope
15
 */
16
function scope(...name: string[]): Signale;
17

18
/**
19
 * Get the current scope name
20
 */
21
readonly scopeName: string;
22
```
23

24
### Scope Removal
25

26
Remove scope from a logger instance.
27

28
```javascript { .api }
29
/**
30
 * Clear the scope name from the logger
31
 */
32
function unscope(): void;
33
```
34

35
### Single Scope Creation
36

37
Create loggers with a single scope identifier.
38

39
**Usage Examples:**
40

41
```javascript
42
const signale = require('signale');
43

44
// Create scoped logger
45
const dbLogger = signale.scope('database');
46
dbLogger.info('Connection established');
47
// Output: [database] › ℹ  info  Connection established
48

49
dbLogger.success('Query executed successfully'); 
50
// Output: [database] › ✔  success  Query executed successfully
51

52
dbLogger.error('Connection timeout');
53
// Output: [database] › ✖  error  Connection timeout
54
```
55

56
### Multiple Scope Levels
57

58
Create nested scopes for hierarchical organization.
59

60
**Usage Examples:**
61

62
```javascript
63
const signale = require('signale');
64

65
// Create multi-level scoped logger
66
const apiLogger = signale.scope('api', 'v2', 'users');
67
apiLogger.info('Processing user request');
68
// Output: [api] [v2] [users] › ℹ  info  Processing user request
69

70
apiLogger.warn('Rate limit approaching');
71
// Output: [api] [v2] [users] › ⚠  warning  Rate limit approaching
72

73
// Create from existing scope
74
const authLogger = apiLogger.scope('auth');
75
authLogger.success('User authenticated');  
76
// Output: [api] [v2] [users] [auth] › ✔  success  User authenticated
77
```
78

79
### Scope Inheritance
80

81
Scoped loggers inherit all properties and custom types from their parent logger.
82

83
**Usage Examples:**
84

85
```javascript
86
const { Signale } = require('signale');
87

88
// Create parent logger with custom types
89
const parent = new Signale({
90
  types: {
91
    deploy: {
92
      badge: '🚀',
93
      color: 'magenta',
94
      label: 'deploy'
95
    }
96
  }
97
});
98

99
// Create scoped logger - inherits custom types
100
const prodLogger = parent.scope('production');
101

102
// Use inherited custom logger
103
prodLogger.deploy('Starting production deployment');
104
// Output: [production] › 🚀  deploy  Starting production deployment
105

106
// Use inherited default loggers
107
prodLogger.success('Deployment completed');
108
// Output: [production] › ✔  success  Deployment completed
109
```
110

111
### Configuration Inheritance
112

113
Scoped loggers inherit configuration, secrets, streams, and all other settings.
114

115
**Usage Examples:**
116

117
```javascript
118
const { Signale } = require('signale');
119

120
// Parent with configuration
121
const parent = new Signale({
122
  secrets: ['password123', 'secret-key'],
123
  logLevel: 'warn',
124
  stream: process.stderr
125
});
126

127
parent.addSecrets(['additional-secret']);
128

129
// Create scoped logger - inherits all settings
130
const moduleLogger = parent.scope('auth-module');
131

132
// Secrets filtering inherited
133
moduleLogger.warn('Login failed for password123');
134
// Output: [auth-module] › ⚠  warning  Login failed for [secure]
135

136
// Log level inherited
137
moduleLogger.info('This will not appear'); // Filtered due to warn level
138
moduleLogger.error('Authentication error');  // Appears
139
```
140

141
### Scope Management
142

143
Manage scope names and create scope chains.
144

145
**Usage Examples:**
146

147
```javascript
148
const signale = require('signale');
149

150
// Create initial scope
151
const appLogger = signale.scope('myapp');
152
console.log(appLogger.scopeName); // "myapp"
153

154
// Create nested scope
155
const moduleLogger = appLogger.scope('users', 'controller');
156
console.log(moduleLogger.scopeName); // ["myapp", "users", "controller"]
157

158
// Remove scope
159
moduleLogger.unscope();
160
moduleLogger.info('No scope now');
161
// Output: ℹ  info  No scope now
162

163
// Scope with array parameter
164
const serviceLogger = signale.scope('service-layer');  
165
serviceLogger.info('Service started');
166
// Output: [service-layer] › ℹ  info  Service started
167
```
168

169
### Functional Scope Patterns
170

171
Common patterns for organizing scoped loggers in applications.
172

173
**Usage Examples:**
174

175
```javascript
176
const signale = require('signale');
177

178
// Module-based scoping
179
function createModuleLogger(moduleName) {
180
  return signale.scope('app', moduleName);
181
}
182

183
const userLogger = createModuleLogger('users');
184
const orderLogger = createModuleLogger('orders');
185

186
userLogger.info('User service initialized');
187
// Output: [app] [users] › ℹ  info  User service initialized
188

189
orderLogger.info('Order processing started');  
190
// Output: [app] [orders] › ℹ  info  Order processing started
191

192
// Request-based scoping
193
function handleRequest(requestId) {
194
  const reqLogger = signale.scope('request', requestId);
195
  
196
  reqLogger.info('Processing request');
197
  reqLogger.success('Request completed');
198
  // Output: [request] [req-123] › ℹ  info  Processing request
199
  //         [request] [req-123] › ✔  success  Request completed
200
}
201

202
handleRequest('req-123');
203
```
204

205
### Scope Display Configuration
206

207
Control scope display through global configuration options.
208

209
**Usage Examples:**
210

211
```javascript
212
const { Signale } = require('signale');
213

214
// Disable scope display
215
const logger = new Signale({
216
  config: {
217
    displayScope: false
218
  }
219
});
220

221
const scoped = logger.scope('hidden');
222
scoped.info('Scope is hidden');
223
// Output: ℹ  info  Scope is hidden (no [hidden] prefix)
224

225
// Enable scope display (default)
226
const visible = new Signale({
227
  config: {
228
    displayScope: true
229
  }
230
});
231

232
const scopedVisible = visible.scope('visible');
233
scopedVisible.info('Scope is shown');
234
// Output: [visible] › ℹ  info  Scope is shown
235
```
236

237
### Error Handling in Scopes
238

239
Scope creation error handling and validation.
240

241
**Usage Examples:**
242

243
```javascript
244
const signale = require('signale');
245

246
// Error: No scope name provided
247
try {
248
  const invalid = signale.scope();
249
} catch (error) {
250
  console.error(error.message); // "No scope name was defined."
251
}
252

253
// Valid: Empty string handling
254
const emptyScoped = signale.scope('', 'valid');
255
emptyScoped.info('Empty strings filtered out');
256
// Output: [valid] › ℹ  info  Empty strings filtered out
257

258
// Array scope names are flattened
259
const complexScope = signale.scope('level1', 'level2');
260
console.log(complexScope.scopeName); // ["level1", "level2"]
261
```