@useverse/profanity-guard 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +23 -0
- package/README.md +1302 -0
- package/dist/index.d.mts +1548 -0
- package/dist/index.d.ts +1548 -0
- package/dist/index.js +12111 -0
- package/dist/index.mjs +12075 -0
- package/package.json +62 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,1548 @@
|
|
|
1
|
+
import * as react from 'react';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Type Definitions for ProfanityGuard
|
|
5
|
+
*
|
|
6
|
+
* @module types
|
|
7
|
+
* @description Comprehensive TypeScript type definitions for the ProfanityGuard content moderation library
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Moderation level enumeration
|
|
11
|
+
*
|
|
12
|
+
* @enum {string}
|
|
13
|
+
* @description Defines how strictly content should be moderated
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```typescript
|
|
17
|
+
* import { ModerationLevel, ProfanityGuard } from 'profanity-guard';
|
|
18
|
+
*
|
|
19
|
+
* const strictModerator = new ProfanityGuard(ModerationLevel.STRICT);
|
|
20
|
+
* const relaxedModerator = new ProfanityGuard(ModerationLevel.RELAXED);
|
|
21
|
+
* ```
|
|
22
|
+
*/
|
|
23
|
+
declare enum ModerationLevel {
|
|
24
|
+
/**
|
|
25
|
+
* No moderation - all content passes through unchanged
|
|
26
|
+
*
|
|
27
|
+
* @remarks Use this when you want to disable moderation temporarily
|
|
28
|
+
* without removing the moderator instance
|
|
29
|
+
*/
|
|
30
|
+
OFF = "off",
|
|
31
|
+
/**
|
|
32
|
+
* Relaxed moderation - only blocks SEVERE and WTF severity words
|
|
33
|
+
*
|
|
34
|
+
* @remarks Suitable for adult audiences or casual environments where
|
|
35
|
+
* mild profanity is acceptable
|
|
36
|
+
*/
|
|
37
|
+
RELAXED = "relaxed",
|
|
38
|
+
/**
|
|
39
|
+
* Moderate moderation - blocks MODERATE, SEVERE, and WTF severity words
|
|
40
|
+
*
|
|
41
|
+
* @remarks The default level. Suitable for most general-purpose applications
|
|
42
|
+
* and public-facing content
|
|
43
|
+
*/
|
|
44
|
+
MODERATE = "moderate",
|
|
45
|
+
/**
|
|
46
|
+
* Strict moderation - blocks all profanity (MILD, MODERATE, SEVERE, WTF)
|
|
47
|
+
*
|
|
48
|
+
* @remarks Suitable for family-friendly environments, educational platforms,
|
|
49
|
+
* or professional contexts where any profanity is unacceptable
|
|
50
|
+
*/
|
|
51
|
+
STRICT = "strict"
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Word severity classification enumeration
|
|
55
|
+
*
|
|
56
|
+
* @enum {string}
|
|
57
|
+
* @description Categorizes words by their offensive level
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* ```typescript
|
|
61
|
+
* import { WordSeverity, ProfanityGuard } from 'profanity-guard';
|
|
62
|
+
*
|
|
63
|
+
* const moderator = new ProfanityGuard();
|
|
64
|
+
* moderator.addWord('example', WordSeverity.MODERATE, ['alternative']);
|
|
65
|
+
* const moderator = new ProfanityGuard();
|
|
66
|
+
* moderator.addWord('example', WordSeverity.MODERATE, ['alternative']);
|
|
67
|
+
* ```
|
|
68
|
+
*/
|
|
69
|
+
declare enum WordSeverity {
|
|
70
|
+
/**
|
|
71
|
+
* Mild severity - minor profanity
|
|
72
|
+
*
|
|
73
|
+
* @remarks Examples: damn, hell, crap
|
|
74
|
+
* Generally acceptable in casual adult conversations but may be
|
|
75
|
+
* inappropriate in professional or family settings
|
|
76
|
+
*/
|
|
77
|
+
MILD = "mild",
|
|
78
|
+
/**
|
|
79
|
+
* Moderate severity - common profanity
|
|
80
|
+
*
|
|
81
|
+
* @remarks Examples: shit, ass, bitch
|
|
82
|
+
* Inappropriate in most public and professional contexts
|
|
83
|
+
*/
|
|
84
|
+
MODERATE = "moderate",
|
|
85
|
+
/**
|
|
86
|
+
* Severe severity - strong profanity and slurs
|
|
87
|
+
*
|
|
88
|
+
* @remarks Examples: fuck, and various slurs
|
|
89
|
+
* Offensive in virtually all contexts, should be blocked
|
|
90
|
+
* in most applications
|
|
91
|
+
*/
|
|
92
|
+
SEVERE = "severe",
|
|
93
|
+
/**
|
|
94
|
+
* WTF severity - extreme profanity and hate speech
|
|
95
|
+
*
|
|
96
|
+
* @remarks The most offensive category, including extreme profanity,
|
|
97
|
+
* slurs, and hate speech. Should always be blocked except in
|
|
98
|
+
* very specific research or archival contexts
|
|
99
|
+
*/
|
|
100
|
+
WTF = "absolutely not"
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Word entry structure for the moderation library
|
|
104
|
+
*
|
|
105
|
+
* @interface WordEntry
|
|
106
|
+
* @description Defines the structure of a word in the moderation library
|
|
107
|
+
*
|
|
108
|
+
* @example
|
|
109
|
+
* ```typescript
|
|
110
|
+
* const entry: WordEntry = {
|
|
111
|
+
* word: 'damn',
|
|
112
|
+
* severity: WordSeverity.MILD,
|
|
113
|
+
* alternatives: ['darn', 'dang']
|
|
114
|
+
* };
|
|
115
|
+
*
|
|
116
|
+
* moderator.addWord(entry.word, entry.severity, entry.alternatives);
|
|
117
|
+
* ```
|
|
118
|
+
*/
|
|
119
|
+
interface WordEntry {
|
|
120
|
+
/**
|
|
121
|
+
* The base word to moderate (stored in lowercase)
|
|
122
|
+
*
|
|
123
|
+
* @type {string}
|
|
124
|
+
* @remarks The actual word will be matched case-insensitively and with
|
|
125
|
+
* common obfuscation patterns (e.g., @ for a, 3 for e)
|
|
126
|
+
*/
|
|
127
|
+
word: string;
|
|
128
|
+
/**
|
|
129
|
+
* Severity classification of the word
|
|
130
|
+
*
|
|
131
|
+
* @type {WordSeverity}
|
|
132
|
+
* @remarks Determines at which moderation levels this word will be blocked
|
|
133
|
+
*/
|
|
134
|
+
severity: WordSeverity;
|
|
135
|
+
/**
|
|
136
|
+
* Optional array of alternative replacement words
|
|
137
|
+
*
|
|
138
|
+
* @type {string[] | undefined}
|
|
139
|
+
* @remarks Used when calling {@link ProfanityGuard.moderateSentence} with
|
|
140
|
+
* `preserveStructure: true`. The first alternative will be used as replacement.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```typescript
|
|
144
|
+
* // Without alternatives: "That's damn good" → "That's **** good"
|
|
145
|
+
* // With alternatives ['darn']: "That's damn good" → "That's darn good"
|
|
146
|
+
* ```
|
|
147
|
+
*/
|
|
148
|
+
alternatives?: string[];
|
|
149
|
+
/**
|
|
150
|
+
* Optional array of common obfuscated variations of the word
|
|
151
|
+
*
|
|
152
|
+
* @type {string[] | undefined}
|
|
153
|
+
* @remarks Used automatically by pattern matching to detect obfuscated variations
|
|
154
|
+
*/
|
|
155
|
+
variants?: string[];
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Match information for a detected profanity instance
|
|
159
|
+
*
|
|
160
|
+
* @interface Match
|
|
161
|
+
* @description Details about a single detected profane word in content
|
|
162
|
+
*/
|
|
163
|
+
interface Match {
|
|
164
|
+
/**
|
|
165
|
+
* The actual matched word as it appeared in the content
|
|
166
|
+
*
|
|
167
|
+
* @type {string}
|
|
168
|
+
* @remarks May be in any case or obfuscation (e.g., "D@mn", "DAMN", "d4mn")
|
|
169
|
+
*/
|
|
170
|
+
word: string;
|
|
171
|
+
/**
|
|
172
|
+
* Severity level of the matched word
|
|
173
|
+
*
|
|
174
|
+
* @type {WordSeverity}
|
|
175
|
+
*/
|
|
176
|
+
severity: WordSeverity;
|
|
177
|
+
/**
|
|
178
|
+
* Zero-based position where the word was found in the original content
|
|
179
|
+
*
|
|
180
|
+
* @type {number}
|
|
181
|
+
* @remarks Can be used to highlight or manipulate specific instances
|
|
182
|
+
*
|
|
183
|
+
* @example
|
|
184
|
+
* ```typescript
|
|
185
|
+
* const content = "Hello damn world";
|
|
186
|
+
* const result = moderator.moderate(content);
|
|
187
|
+
* // result.matches[0].position === 6
|
|
188
|
+
* ```
|
|
189
|
+
*/
|
|
190
|
+
position: number;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Comprehensive moderation result
|
|
194
|
+
*
|
|
195
|
+
* @interface ModerationResult
|
|
196
|
+
* @description Contains all information about a moderation operation
|
|
197
|
+
*
|
|
198
|
+
* @example
|
|
199
|
+
* ```typescript
|
|
200
|
+
* const result: ModerationResult = moderator.moderate("This damn text has shit");
|
|
201
|
+
*
|
|
202
|
+
* if (!result.isClean) {
|
|
203
|
+
* console.log(`Found ${result.foundWords.length} profane words`);
|
|
204
|
+
* console.log(`Highest severity: ${result.severity}`);
|
|
205
|
+
* console.log(`Sanitized: ${result.sanitized}`);
|
|
206
|
+
*
|
|
207
|
+
* result.matches.forEach(match => {
|
|
208
|
+
* console.log(`"${match.word}" at position ${match.position}`);
|
|
209
|
+
* });
|
|
210
|
+
* }
|
|
211
|
+
* ```
|
|
212
|
+
*/
|
|
213
|
+
interface ModerationResult {
|
|
214
|
+
/**
|
|
215
|
+
* Whether the content is free of profanity
|
|
216
|
+
*
|
|
217
|
+
* @type {boolean}
|
|
218
|
+
* @remarks `true` if no profanity detected, `false` otherwise
|
|
219
|
+
*/
|
|
220
|
+
isClean: boolean;
|
|
221
|
+
/**
|
|
222
|
+
* Array of unique profane words found in the content
|
|
223
|
+
*
|
|
224
|
+
* @type {string[]}
|
|
225
|
+
* @remarks Contains each unique matched word (duplicates removed).
|
|
226
|
+
* Words appear as they were matched in the content (preserving case/obfuscation).
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```typescript
|
|
230
|
+
* // Content: "Damn this damn situation"
|
|
231
|
+
* // foundWords: ['Damn', 'damn'] or ['Damn'] depending on implementation
|
|
232
|
+
* ```
|
|
233
|
+
*/
|
|
234
|
+
foundWords: string[];
|
|
235
|
+
/**
|
|
236
|
+
* Highest severity level found in the content
|
|
237
|
+
*
|
|
238
|
+
* @type {WordSeverity | null}
|
|
239
|
+
* @remarks `null` if no profanity detected, otherwise the most severe
|
|
240
|
+
* category found
|
|
241
|
+
*
|
|
242
|
+
* @example
|
|
243
|
+
* ```typescript
|
|
244
|
+
* // Content: "damn this shit"
|
|
245
|
+
* // severity: WordSeverity.MODERATE (shit is more severe than damn)
|
|
246
|
+
* ```
|
|
247
|
+
*/
|
|
248
|
+
severity: WordSeverity | null;
|
|
249
|
+
/**
|
|
250
|
+
* Sanitized version of the content with profanity censored or replaced
|
|
251
|
+
*
|
|
252
|
+
* @type {string}
|
|
253
|
+
* @remarks Profane words are replaced with:
|
|
254
|
+
* - Censor characters (default: asterisks) in standard moderation
|
|
255
|
+
* - Alternative words when using {@link ProfanityGuard.moderateSentence} with `preserveStructure: true`
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* ```typescript
|
|
259
|
+
* // Standard: "damn" → "****"
|
|
260
|
+
* // With alternatives: "damn" → "darn"
|
|
261
|
+
* ```
|
|
262
|
+
*/
|
|
263
|
+
sanitized: string;
|
|
264
|
+
/**
|
|
265
|
+
* Detailed information about each match found
|
|
266
|
+
*
|
|
267
|
+
* @type {Match[]}
|
|
268
|
+
* @remarks Array of match objects sorted by position.
|
|
269
|
+
* Useful for detailed analysis, logging, or custom replacement logic.
|
|
270
|
+
*
|
|
271
|
+
* @example
|
|
272
|
+
* ```typescript
|
|
273
|
+
* result.matches.forEach(match => {
|
|
274
|
+
* console.log(`Found "${match.word}" (${match.severity}) at position ${match.position}`);
|
|
275
|
+
* });
|
|
276
|
+
* ```
|
|
277
|
+
*/
|
|
278
|
+
matches: Match[];
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* Library statistics structure
|
|
282
|
+
*
|
|
283
|
+
* @interface LibraryStats
|
|
284
|
+
* @description Statistics about the current word library
|
|
285
|
+
*
|
|
286
|
+
* @example
|
|
287
|
+
* ```typescript
|
|
288
|
+
* const stats = moderator.getStats();
|
|
289
|
+
* console.log(`Total words: ${stats.total}`);
|
|
290
|
+
* console.log(`Distribution: ${stats.mild} mild, ${stats.moderate} moderate, ${stats.severe} severe`);
|
|
291
|
+
* ```
|
|
292
|
+
*/
|
|
293
|
+
interface LibraryStats {
|
|
294
|
+
/**
|
|
295
|
+
* Total number of words in the library
|
|
296
|
+
*
|
|
297
|
+
* @type {number}
|
|
298
|
+
*/
|
|
299
|
+
total: number;
|
|
300
|
+
/**
|
|
301
|
+
* Number of MILD severity words
|
|
302
|
+
*
|
|
303
|
+
* @type {number}
|
|
304
|
+
*/
|
|
305
|
+
mild: number;
|
|
306
|
+
/**
|
|
307
|
+
* Number of MODERATE severity words
|
|
308
|
+
*
|
|
309
|
+
* @type {number}
|
|
310
|
+
*/
|
|
311
|
+
moderate: number;
|
|
312
|
+
/**
|
|
313
|
+
* Number of SEVERE severity words
|
|
314
|
+
*
|
|
315
|
+
* @type {number}
|
|
316
|
+
*/
|
|
317
|
+
severe: number;
|
|
318
|
+
/**
|
|
319
|
+
* Number of WTF severity words
|
|
320
|
+
*
|
|
321
|
+
* @type {number}
|
|
322
|
+
*/
|
|
323
|
+
wtf?: number;
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Configuration options for ProfanityGuard constructor
|
|
327
|
+
*
|
|
328
|
+
* @interface ProfanityGuardConfig
|
|
329
|
+
* @description Optional configuration object for creating ProfanityGuard instances
|
|
330
|
+
*
|
|
331
|
+
* @example
|
|
332
|
+
* ```typescript
|
|
333
|
+
* const config: ProfanityGuardConfig = {
|
|
334
|
+
* moderationLevel: ModerationLevel.STRICT,
|
|
335
|
+
* censorChar: '#',
|
|
336
|
+
* autoImportLibrary: true
|
|
337
|
+
* };
|
|
338
|
+
*
|
|
339
|
+
* const moderator = new ProfanityGuard(config);
|
|
340
|
+
* ```
|
|
341
|
+
*/
|
|
342
|
+
interface ProfanityGuardConfig {
|
|
343
|
+
/**
|
|
344
|
+
* Initial moderation level
|
|
345
|
+
*
|
|
346
|
+
* @type {ModerationLevel}
|
|
347
|
+
* @default ModerationLevel.MODERATE
|
|
348
|
+
*/
|
|
349
|
+
moderationLevel?: ModerationLevel;
|
|
350
|
+
/**
|
|
351
|
+
* Character used for censoring
|
|
352
|
+
*
|
|
353
|
+
* @type {string}
|
|
354
|
+
* @default '*'
|
|
355
|
+
*/
|
|
356
|
+
censorChar?: string;
|
|
357
|
+
/**
|
|
358
|
+
* Whether to automatically import the default library
|
|
359
|
+
*
|
|
360
|
+
* @type {boolean}
|
|
361
|
+
* @default true
|
|
362
|
+
*/
|
|
363
|
+
autoImportLibrary?: boolean;
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
/**
|
|
367
|
+
* Profanity Guard - A flexible, production-ready content moderation library
|
|
368
|
+
*
|
|
369
|
+
* @module ProfanityGuard
|
|
370
|
+
* @version 1.0.0
|
|
371
|
+
* @license MIT
|
|
372
|
+
*
|
|
373
|
+
* @description
|
|
374
|
+
* A comprehensive TypeScript library for content moderation and profanity filtering.
|
|
375
|
+
* Features multiple severity levels, customizable word libraries, obfuscation detection,
|
|
376
|
+
* and flexible sanitization options.
|
|
377
|
+
*
|
|
378
|
+
* @example
|
|
379
|
+
* ```typescript
|
|
380
|
+
* import { ProfanityGuard, ModerationLevel } from 'profanity-guard';
|
|
381
|
+
*
|
|
382
|
+
* const moderator = new ProfanityGuard(ModerationLevel.MODERATE);
|
|
383
|
+
* const result = moderator.moderate("This is some damn text");
|
|
384
|
+
*
|
|
385
|
+
* console.log(result.isClean); // false
|
|
386
|
+
* console.log(result.sanitized); // "This is some **** text"
|
|
387
|
+
* ```
|
|
388
|
+
*/
|
|
389
|
+
|
|
390
|
+
/**
|
|
391
|
+
* Main content moderation class
|
|
392
|
+
*
|
|
393
|
+
* @class ProfanityGuard
|
|
394
|
+
* @classdesc Provides comprehensive content moderation with configurable severity levels,
|
|
395
|
+
* custom word libraries, and advanced pattern matching including obfuscation detection.
|
|
396
|
+
*
|
|
397
|
+
* @example
|
|
398
|
+
* ```typescript
|
|
399
|
+
* // Basic usage
|
|
400
|
+
* const moderator = new ProfanityGuard();
|
|
401
|
+
* const clean = moderator.isClean("Hello world"); // true
|
|
402
|
+
*
|
|
403
|
+
* // With custom settings
|
|
404
|
+
* const strictModerator = new ProfanityGuard(ModerationLevel.STRICT, '#');
|
|
405
|
+
* const result = strictModerator.moderate("damn it");
|
|
406
|
+
* console.log(result.sanitized); // "#### it"
|
|
407
|
+
* ```
|
|
408
|
+
*/
|
|
409
|
+
declare class ProfanityGuard {
|
|
410
|
+
/** @private Current moderation level determining which words to filter */
|
|
411
|
+
private moderationLevel;
|
|
412
|
+
/** @private Internal word library storing all moderation entries */
|
|
413
|
+
private wordLibrary;
|
|
414
|
+
/** @private Character used to censor detected profanity */
|
|
415
|
+
private censorChar;
|
|
416
|
+
/**
|
|
417
|
+
* Creates a new ProfanityGuard instance
|
|
418
|
+
*
|
|
419
|
+
* @constructor
|
|
420
|
+
* @param {ModerationLevel} [moderationLevel=ModerationLevel.MODERATE] - Initial moderation level
|
|
421
|
+
* @param {string} [censorChar='*'] - Character used for censoring bad words
|
|
422
|
+
*
|
|
423
|
+
* @example
|
|
424
|
+
* ```typescript
|
|
425
|
+
* // Default settings (moderate level, '*' censor)
|
|
426
|
+
* const moderator = new ProfanityGuard();
|
|
427
|
+
*
|
|
428
|
+
* // Custom settings
|
|
429
|
+
* const strictModerator = new ProfanityGuard(ModerationLevel.STRICT, '#');
|
|
430
|
+
*
|
|
431
|
+
* // Relaxed moderation
|
|
432
|
+
* const relaxedModerator = new ProfanityGuard(ModerationLevel.RELAXED);
|
|
433
|
+
* ```
|
|
434
|
+
*/
|
|
435
|
+
constructor(moderationLevel?: ModerationLevel, censorChar?: string);
|
|
436
|
+
/**
|
|
437
|
+
* Initializes the word library with a basic default set of words
|
|
438
|
+
*
|
|
439
|
+
* @private
|
|
440
|
+
* @returns {void}
|
|
441
|
+
*
|
|
442
|
+
* @remarks
|
|
443
|
+
* This method is called automatically during construction.
|
|
444
|
+
* The default library includes common profanity categorized by severity.
|
|
445
|
+
* Users should expand this library based on their specific needs using
|
|
446
|
+
* {@link addWord}, {@link addWords}, or {@link importLibrary}.
|
|
447
|
+
*/
|
|
448
|
+
private initializeDefaultLibrary;
|
|
449
|
+
/**
|
|
450
|
+
* Adds a single word to the moderation library
|
|
451
|
+
*
|
|
452
|
+
* @param {string} word - The word to add (case-insensitive)
|
|
453
|
+
* @param {WordSeverity} severity - The severity level of the word
|
|
454
|
+
* @param {string[]} [alternatives] - Optional array of alternative words for replacement
|
|
455
|
+
* @returns {void}
|
|
456
|
+
*
|
|
457
|
+
* @example
|
|
458
|
+
* ```typescript
|
|
459
|
+
* moderator.addWord('badword', WordSeverity.MODERATE, ['alternative', 'replacement']);
|
|
460
|
+
* moderator.addWord('slur', WordSeverity.SEVERE);
|
|
461
|
+
* ```
|
|
462
|
+
*
|
|
463
|
+
* @remarks
|
|
464
|
+
* - Words are stored in lowercase for case-insensitive matching
|
|
465
|
+
* - Alternatives are used when {@link moderateSentence} is called with `preserveStructure: true`
|
|
466
|
+
* - Duplicate words will overwrite the existing entry
|
|
467
|
+
*/
|
|
468
|
+
addWord(word: string, severity: WordSeverity, alternatives?: string[], variants?: string[]): void;
|
|
469
|
+
/**
|
|
470
|
+
* Adds multiple words to the library at once
|
|
471
|
+
*
|
|
472
|
+
* @param {WordEntry[]} entries - Array of word entries to add
|
|
473
|
+
* @returns {void}
|
|
474
|
+
*
|
|
475
|
+
* @example
|
|
476
|
+
* ```typescript
|
|
477
|
+
* moderator.addWords([
|
|
478
|
+
* { word: 'badword1', severity: WordSeverity.MILD, alternatives: ['good1'] },
|
|
479
|
+
* { word: 'badword2', severity: WordSeverity.MODERATE }
|
|
480
|
+
* ]);
|
|
481
|
+
* ```
|
|
482
|
+
*
|
|
483
|
+
* @see {@link WordEntry} for the structure of each entry
|
|
484
|
+
*/
|
|
485
|
+
addWords(entries: WordEntry[]): void;
|
|
486
|
+
/**
|
|
487
|
+
* Removes a word from the moderation library
|
|
488
|
+
*
|
|
489
|
+
* @param {string} word - The word to remove (case-insensitive)
|
|
490
|
+
* @returns {boolean} `true` if the word was removed, `false` if it wasn't in the library
|
|
491
|
+
*
|
|
492
|
+
* @example
|
|
493
|
+
* ```typescript
|
|
494
|
+
* const removed = moderator.removeWord('damn');
|
|
495
|
+
* if (removed) {
|
|
496
|
+
* console.log('Word removed successfully');
|
|
497
|
+
* }
|
|
498
|
+
* ```
|
|
499
|
+
*/
|
|
500
|
+
removeWord(word: string): boolean;
|
|
501
|
+
/**
|
|
502
|
+
* Imports a word library from a JSON-compatible array
|
|
503
|
+
*
|
|
504
|
+
* @param {WordEntry[]} jsonData - Array of word entries to import
|
|
505
|
+
* @returns {void}
|
|
506
|
+
*
|
|
507
|
+
* @example
|
|
508
|
+
* ```typescript
|
|
509
|
+
* import customLibrary from './custom-words.json';
|
|
510
|
+
* moderator.importLibrary(customLibrary);
|
|
511
|
+
*
|
|
512
|
+
* // Or use the built-in library
|
|
513
|
+
* import { all_bad_words } from 'profanity-guard/core/library';
|
|
514
|
+
* moderator.importLibrary(all_bad_words);
|
|
515
|
+
* ```
|
|
516
|
+
*
|
|
517
|
+
* @remarks
|
|
518
|
+
* This method adds to the existing library rather than replacing it.
|
|
519
|
+
* Use {@link clearLibrary} first if you want to replace the entire library.
|
|
520
|
+
*/
|
|
521
|
+
importLibrary(jsonData: WordEntry[]): void;
|
|
522
|
+
/**
|
|
523
|
+
* Exports the current word library as a JSON-compatible array
|
|
524
|
+
*
|
|
525
|
+
* @returns {WordEntry[]} Array of all word entries in the library
|
|
526
|
+
*
|
|
527
|
+
* @example
|
|
528
|
+
* ```typescript
|
|
529
|
+
* const library = moderator.exportLibrary();
|
|
530
|
+
* console.log(`Total words: ${library.length}`);
|
|
531
|
+
*
|
|
532
|
+
* // Save to file
|
|
533
|
+
* fs.writeFileSync('my-library.json', JSON.stringify(library, null, 2));
|
|
534
|
+
* ```
|
|
535
|
+
*/
|
|
536
|
+
exportLibrary(): WordEntry[];
|
|
537
|
+
/**
|
|
538
|
+
* Clears all words from the library
|
|
539
|
+
*
|
|
540
|
+
* @returns {void}
|
|
541
|
+
*
|
|
542
|
+
* @example
|
|
543
|
+
* ```typescript
|
|
544
|
+
* moderator.clearLibrary();
|
|
545
|
+
* console.log(moderator.getStats().total); // 0
|
|
546
|
+
* ```
|
|
547
|
+
*
|
|
548
|
+
* @warning
|
|
549
|
+
* This will remove all words including the default library.
|
|
550
|
+
* Consider backing up with {@link exportLibrary} first.
|
|
551
|
+
*/
|
|
552
|
+
clearLibrary(): void;
|
|
553
|
+
/**
|
|
554
|
+
* Changes the current moderation level
|
|
555
|
+
*
|
|
556
|
+
* @param {ModerationLevel} level - The new moderation level
|
|
557
|
+
* @returns {void}
|
|
558
|
+
*
|
|
559
|
+
* @example
|
|
560
|
+
* ```typescript
|
|
561
|
+
* moderator.setModerationLevel(ModerationLevel.STRICT);
|
|
562
|
+
* moderator.setModerationLevel(ModerationLevel.OFF); // Disables all moderation
|
|
563
|
+
* ```
|
|
564
|
+
*
|
|
565
|
+
* @see {@link ModerationLevel} for available levels and their behavior
|
|
566
|
+
*/
|
|
567
|
+
setModerationLevel(level: ModerationLevel): void;
|
|
568
|
+
/**
|
|
569
|
+
* Gets the current moderation level
|
|
570
|
+
*
|
|
571
|
+
* @returns {ModerationLevel} The current moderation level
|
|
572
|
+
*
|
|
573
|
+
* @example
|
|
574
|
+
* ```typescript
|
|
575
|
+
* if (moderator.getModerationLevel() === ModerationLevel.STRICT) {
|
|
576
|
+
* console.log('Running in strict mode');
|
|
577
|
+
* }
|
|
578
|
+
* ```
|
|
579
|
+
*/
|
|
580
|
+
getModerationLevel(): ModerationLevel;
|
|
581
|
+
/**
|
|
582
|
+
* Determines if a word severity should be blocked based on current moderation level
|
|
583
|
+
*
|
|
584
|
+
* @private
|
|
585
|
+
* @param {WordSeverity} severity - The severity level to check
|
|
586
|
+
* @returns {boolean} `true` if the word should be blocked, `false` otherwise
|
|
587
|
+
*
|
|
588
|
+
* @remarks
|
|
589
|
+
* Moderation level hierarchy:
|
|
590
|
+
* - OFF: Blocks nothing
|
|
591
|
+
* - RELAXED: Blocks only SEVERE and WTF
|
|
592
|
+
* - MODERATE: Blocks MODERATE, SEVERE, and WTF
|
|
593
|
+
* - STRICT: Blocks MILD, MODERATE, SEVERE, and WTF
|
|
594
|
+
*/
|
|
595
|
+
private shouldBlock;
|
|
596
|
+
/**
|
|
597
|
+
* Creates a regex pattern for matching a word with obfuscation detection
|
|
598
|
+
*
|
|
599
|
+
* @private
|
|
600
|
+
* @param {string} word - The word to create a pattern for
|
|
601
|
+
* @returns {RegExp} Regular expression that matches the word and common obfuscations
|
|
602
|
+
*
|
|
603
|
+
* @remarks
|
|
604
|
+
* The pattern handles:
|
|
605
|
+
* - Letter substitutions (e.g., @ for a, 3 for e, $ for s)
|
|
606
|
+
* - Case insensitivity
|
|
607
|
+
* - Special characters and spaces inserted between letters
|
|
608
|
+
* - Word boundaries to avoid false positives
|
|
609
|
+
*
|
|
610
|
+
* @example
|
|
611
|
+
* Pattern for "bad" will match: bad, b@d, B4D, b-a-d, b_a_d, etc.
|
|
612
|
+
*/
|
|
613
|
+
private createWordPattern;
|
|
614
|
+
/**
|
|
615
|
+
* Get all words to check (main word + all variants)
|
|
616
|
+
*/
|
|
617
|
+
private getAllWordsToCheck;
|
|
618
|
+
/**
|
|
619
|
+
* Performs comprehensive content moderation and returns detailed results
|
|
620
|
+
*
|
|
621
|
+
* @param {string} content - The text content to moderate
|
|
622
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
623
|
+
*
|
|
624
|
+
* @example
|
|
625
|
+
* ```typescript
|
|
626
|
+
* const result = moderator.moderate("This damn text has shit in it");
|
|
627
|
+
*
|
|
628
|
+
* console.log(result.isClean); // false
|
|
629
|
+
* console.log(result.foundWords); // ['damn', 'shit']
|
|
630
|
+
* console.log(result.severity); // 'moderate'
|
|
631
|
+
* console.log(result.sanitized); // "This **** text has **** in it"
|
|
632
|
+
* console.log(result.matches.length); // 2
|
|
633
|
+
* ```
|
|
634
|
+
*
|
|
635
|
+
* @remarks
|
|
636
|
+
* - Detects obfuscated variations (e.g., "sh!t", "d@mn")
|
|
637
|
+
* - Handles overlapping matches correctly
|
|
638
|
+
* - Returns the highest severity level found
|
|
639
|
+
* - Preserves original text positions in match data
|
|
640
|
+
*
|
|
641
|
+
* @see {@link ModerationResult} for the complete result structure
|
|
642
|
+
*/
|
|
643
|
+
moderate(content: string): ModerationResult;
|
|
644
|
+
/**
|
|
645
|
+
* Performs a quick check if content is clean (contains no profanity)
|
|
646
|
+
*
|
|
647
|
+
* @param {string} content - The text content to check
|
|
648
|
+
* @returns {boolean} `true` if clean, `false` if profanity detected
|
|
649
|
+
*
|
|
650
|
+
* @example
|
|
651
|
+
* ```typescript
|
|
652
|
+
* if (moderator.isClean("Hello world")) {
|
|
653
|
+
* console.log("Content is safe!");
|
|
654
|
+
* }
|
|
655
|
+
*
|
|
656
|
+
* if (!moderator.isClean("This is shit")) {
|
|
657
|
+
* console.log("Profanity detected!");
|
|
658
|
+
* }
|
|
659
|
+
* ```
|
|
660
|
+
*
|
|
661
|
+
* @remarks
|
|
662
|
+
* This is a convenience method that calls {@link moderate} and returns only the `isClean` property.
|
|
663
|
+
* Use {@link moderate} directly if you need additional details about detected words.
|
|
664
|
+
*/
|
|
665
|
+
isClean(content: string): boolean;
|
|
666
|
+
/**
|
|
667
|
+
* Returns a sanitized (censored) version of the content
|
|
668
|
+
*
|
|
669
|
+
* @param {string} content - The text content to sanitize
|
|
670
|
+
* @returns {string} The sanitized text with profanity censored
|
|
671
|
+
*
|
|
672
|
+
* @example
|
|
673
|
+
* ```typescript
|
|
674
|
+
* const clean = moderator.sanitize("This damn text is shit");
|
|
675
|
+
* console.log(clean); // "This **** text is ****"
|
|
676
|
+
*
|
|
677
|
+
* // With custom censor character
|
|
678
|
+
* const moderator2 = new ProfanityGuard(ModerationLevel.MODERATE, '#');
|
|
679
|
+
* console.log(moderator2.sanitize("damn")); // "####"
|
|
680
|
+
* ```
|
|
681
|
+
*
|
|
682
|
+
* @remarks
|
|
683
|
+
* This is a convenience method that calls {@link moderate} and returns only the `sanitized` property.
|
|
684
|
+
*/
|
|
685
|
+
sanitize(content: string): string;
|
|
686
|
+
/**
|
|
687
|
+
* Gets the numeric rank of a severity level for comparison
|
|
688
|
+
*
|
|
689
|
+
* @private
|
|
690
|
+
* @param {WordSeverity} severity - The severity level to rank
|
|
691
|
+
* @returns {number} Numeric rank (1=MILD, 2=MODERATE, 3=SEVERE)
|
|
692
|
+
*/
|
|
693
|
+
private getSeverityRank;
|
|
694
|
+
/**
|
|
695
|
+
* Gets statistics about the current word library
|
|
696
|
+
*
|
|
697
|
+
* @returns {Object} Statistics object containing word counts by severity
|
|
698
|
+
* @returns {number} .total - Total number of words in the library
|
|
699
|
+
* @returns {number} .mild - Number of MILD severity words
|
|
700
|
+
* @returns {number} .moderate - Number of MODERATE severity words
|
|
701
|
+
* @returns {number} .severe - Number of SEVERE severity words
|
|
702
|
+
* @returns {number} .wtf - Number of WTF severity words
|
|
703
|
+
* @returns {number} .totalVariants - Total number of variants across all words
|
|
704
|
+
*
|
|
705
|
+
* @example
|
|
706
|
+
* ```typescript
|
|
707
|
+
* const stats = moderator.getStats();
|
|
708
|
+
* console.log(`Total words: ${stats.total}`);
|
|
709
|
+
* console.log(`Mild: ${stats.mild}, Moderate: ${stats.moderate}, Severe: ${stats.severe}`);
|
|
710
|
+
* ```
|
|
711
|
+
*/
|
|
712
|
+
getStats(): {
|
|
713
|
+
total: number;
|
|
714
|
+
mild: number;
|
|
715
|
+
moderate: number;
|
|
716
|
+
severe: number;
|
|
717
|
+
wtf: number;
|
|
718
|
+
totalVariants: number;
|
|
719
|
+
};
|
|
720
|
+
/**
|
|
721
|
+
* Validates that critical words are in the library
|
|
722
|
+
*
|
|
723
|
+
* @param {string[]} [criticalWords] - Array of words that must be present
|
|
724
|
+
* @returns {Object} Validation result
|
|
725
|
+
* @returns {boolean} .allPresent - True if all critical words are in library
|
|
726
|
+
* @returns {string[]} .missing - Array of missing words
|
|
727
|
+
* @returns {string[]} .present - Array of present words
|
|
728
|
+
*
|
|
729
|
+
* @example
|
|
730
|
+
* ```typescript
|
|
731
|
+
* const validation = moderator.validateLibrary(['fuck', 'shit', 'nigga']);
|
|
732
|
+
* if (!validation.allPresent) {
|
|
733
|
+
* console.error('Missing words:', validation.missing);
|
|
734
|
+
* }
|
|
735
|
+
* ```
|
|
736
|
+
*/
|
|
737
|
+
validateLibrary(criticalWords?: string[]): {
|
|
738
|
+
allPresent: boolean;
|
|
739
|
+
missing: string[];
|
|
740
|
+
present: string[];
|
|
741
|
+
};
|
|
742
|
+
/**
|
|
743
|
+
* Debug a specific word - see if it's detected and how
|
|
744
|
+
*
|
|
745
|
+
* @param {string} word - The word to debug
|
|
746
|
+
* @param {string} [testText] - Optional text to test the word against
|
|
747
|
+
* @returns {Object} Debug information
|
|
748
|
+
* @returns {boolean} .inLibrary - True if word is in the library
|
|
749
|
+
* @returns {WordEntry} [.entry] - The word entry if found
|
|
750
|
+
* @returns {string} [.pattern] - The regex pattern used for matching
|
|
751
|
+
* @returns {boolean} .wouldBlock - True if word would be blocked at current level
|
|
752
|
+
* @returns {ModerationResult} [.testResult] - Result of testing against testText
|
|
753
|
+
*
|
|
754
|
+
* @example
|
|
755
|
+
* ```typescript
|
|
756
|
+
* const debug = moderator.debugWord('pussy', 'this pussy is bad');
|
|
757
|
+
* console.log('In library:', debug.inLibrary);
|
|
758
|
+
* console.log('Would block:', debug.wouldBlock);
|
|
759
|
+
* console.log('Test result:', debug.testResult);
|
|
760
|
+
* ```
|
|
761
|
+
*/
|
|
762
|
+
debugWord(word: string, testText?: string): {
|
|
763
|
+
inLibrary: boolean;
|
|
764
|
+
entry?: WordEntry;
|
|
765
|
+
pattern?: string;
|
|
766
|
+
wouldBlock: boolean;
|
|
767
|
+
testResult?: ModerationResult;
|
|
768
|
+
};
|
|
769
|
+
/**
|
|
770
|
+
* Run comprehensive tests to ensure nothing slips through
|
|
771
|
+
*
|
|
772
|
+
* @returns {Object} Test results
|
|
773
|
+
* @returns {number} .passed - Number of tests that passed
|
|
774
|
+
* @returns {number} .failed - Number of tests that failed
|
|
775
|
+
* @returns {Array} .results - Detailed results for each test
|
|
776
|
+
*
|
|
777
|
+
* @example
|
|
778
|
+
* ```typescript
|
|
779
|
+
* const testResults = moderator.runTests();
|
|
780
|
+
* console.log(`${testResults.passed} passed, ${testResults.failed} failed`);
|
|
781
|
+
* testResults.results.forEach(r => {
|
|
782
|
+
* console.log(`${r.passed ? '✅' : '❌'} ${r.test}: ${r.details}`);
|
|
783
|
+
* });
|
|
784
|
+
* ```
|
|
785
|
+
*/
|
|
786
|
+
runTests(): {
|
|
787
|
+
passed: number;
|
|
788
|
+
failed: number;
|
|
789
|
+
results: Array<{
|
|
790
|
+
test: string;
|
|
791
|
+
passed: boolean;
|
|
792
|
+
details: string;
|
|
793
|
+
}>;
|
|
794
|
+
};
|
|
795
|
+
/**
|
|
796
|
+
* Moderates a sentence with optional structure preservation using alternatives
|
|
797
|
+
*
|
|
798
|
+
* @param {string} sentence - The sentence to moderate
|
|
799
|
+
* @param {boolean} [preserveStructure=false] - If true, replaces bad words with alternatives instead of censoring
|
|
800
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
801
|
+
*
|
|
802
|
+
* @example
|
|
803
|
+
* ```typescript
|
|
804
|
+
* // Standard censoring
|
|
805
|
+
* const result1 = moderator.moderateSentence("This is damn good");
|
|
806
|
+
* console.log(result1.sanitized); // "This is **** good"
|
|
807
|
+
*
|
|
808
|
+
* // With structure preservation (uses alternatives)
|
|
809
|
+
* const result2 = moderator.moderateSentence("This is damn good", true);
|
|
810
|
+
* console.log(result2.sanitized); // "This is darn good"
|
|
811
|
+
* ```
|
|
812
|
+
*
|
|
813
|
+
* @remarks
|
|
814
|
+
* When `preserveStructure` is true, the method replaces profanity with the first alternative
|
|
815
|
+
* from the word's alternatives array. If no alternative exists, it falls back to censoring.
|
|
816
|
+
*
|
|
817
|
+
* This is useful for maintaining readability while removing profanity, such as in
|
|
818
|
+
* comment systems or user-generated content displays.
|
|
819
|
+
*/
|
|
820
|
+
moderateSentence(sentence: string, preserveStructure?: boolean): ModerationResult;
|
|
821
|
+
/**
|
|
822
|
+
* Highlights profane words in content by wrapping them in custom tags
|
|
823
|
+
*
|
|
824
|
+
* @param {string} content - The text content to highlight
|
|
825
|
+
* @param {string} [openTag='<mark>'] - Opening tag to wrap profane words
|
|
826
|
+
* @param {string} [closeTag='</mark>'] - Closing tag to wrap profane words
|
|
827
|
+
* @returns {string} Content with profane words wrapped in tags
|
|
828
|
+
*
|
|
829
|
+
* @example
|
|
830
|
+
* ```typescript
|
|
831
|
+
* const highlighted = moderator.highlight("This damn text is shit");
|
|
832
|
+
* // Output: "This <mark>damn</mark> text is <mark>shit</mark>"
|
|
833
|
+
*
|
|
834
|
+
* const custom = moderator.highlight("damn it", '<span class="profanity">', '</span>');
|
|
835
|
+
* // Output: "damn it" becomes '<span class="profanity">damn</span> it'
|
|
836
|
+
* ```
|
|
837
|
+
*
|
|
838
|
+
* @remarks
|
|
839
|
+
* Useful for displaying flagged content to moderators or for educational purposes.
|
|
840
|
+
* The tags are not HTML-escaped, so ensure safe usage.
|
|
841
|
+
*/
|
|
842
|
+
highlight(content: string, openTag?: string, closeTag?: string): string;
|
|
843
|
+
/**
|
|
844
|
+
* Counts profane words by severity level
|
|
845
|
+
*
|
|
846
|
+
* @param {string} content - The text content to analyze
|
|
847
|
+
* @returns {Object} Count of words by severity level
|
|
848
|
+
*
|
|
849
|
+
* @example
|
|
850
|
+
* ```typescript
|
|
851
|
+
* const counts = moderator.countBySeverity("This damn shit is fucking bad");
|
|
852
|
+
* // Output: { mild: 1, moderate: 1, severe: 1, wtf: 0, total: 3 }
|
|
853
|
+
* ```
|
|
854
|
+
*/
|
|
855
|
+
countBySeverity(content: string): {
|
|
856
|
+
mild: number;
|
|
857
|
+
moderate: number;
|
|
858
|
+
severe: number;
|
|
859
|
+
wtf: number;
|
|
860
|
+
total: number;
|
|
861
|
+
};
|
|
862
|
+
/**
|
|
863
|
+
* Calculates a profanity score for the content
|
|
864
|
+
*
|
|
865
|
+
* @param {string} content - The text content to score
|
|
866
|
+
* @returns {number} Score from 0-100 (0 = clean, 100 = extremely profane)
|
|
867
|
+
*
|
|
868
|
+
* @example
|
|
869
|
+
* ```typescript
|
|
870
|
+
* const score = moderator.getProfanityScore("Hello world");
|
|
871
|
+
* console.log(score); // 0
|
|
872
|
+
*
|
|
873
|
+
* const badScore = moderator.getProfanityScore("This fucking damn shit");
|
|
874
|
+
* console.log(badScore); // ~75 (depends on word count and severity)
|
|
875
|
+
* ```
|
|
876
|
+
*
|
|
877
|
+
* @remarks
|
|
878
|
+
* Score calculation:
|
|
879
|
+
* - MILD words: 10 points each
|
|
880
|
+
* - MODERATE words: 25 points each
|
|
881
|
+
* - SEVERE words: 50 points each
|
|
882
|
+
* - WTF words: 100 points each
|
|
883
|
+
* - Normalized by word count and capped at 100
|
|
884
|
+
*/
|
|
885
|
+
getProfanityScore(content: string): number;
|
|
886
|
+
/**
|
|
887
|
+
* Checks if content exceeds a profanity threshold
|
|
888
|
+
*
|
|
889
|
+
* @param {string} content - The text content to check
|
|
890
|
+
* @param {number} threshold - Maximum allowed profanity score (0-100)
|
|
891
|
+
* @returns {boolean} True if content is within threshold, false otherwise
|
|
892
|
+
*
|
|
893
|
+
* @example
|
|
894
|
+
* ```typescript
|
|
895
|
+
* const isAcceptable = moderator.isWithinThreshold("Hello world", 10);
|
|
896
|
+
* console.log(isAcceptable); // true
|
|
897
|
+
*
|
|
898
|
+
* const isTooProfiled = moderator.isWithinThreshold("This shit is bad", 15);
|
|
899
|
+
* console.log(isTooProfiled); // false (score too high)
|
|
900
|
+
* ```
|
|
901
|
+
*/
|
|
902
|
+
isWithinThreshold(content: string, threshold: number): boolean;
|
|
903
|
+
/**
|
|
904
|
+
* Extracts only clean sentences from content
|
|
905
|
+
*
|
|
906
|
+
* @param {string} content - The text content to filter
|
|
907
|
+
* @param {string} [delimiter='.'] - Sentence delimiter
|
|
908
|
+
* @returns {string[]} Array of clean sentences
|
|
909
|
+
*
|
|
910
|
+
* @example
|
|
911
|
+
* ```typescript
|
|
912
|
+
* const text = "Hello world. This is damn bad. Nice day today.";
|
|
913
|
+
* const clean = moderator.getCleanSentences(text);
|
|
914
|
+
* // Output: ["Hello world", "Nice day today"]
|
|
915
|
+
* ```
|
|
916
|
+
*/
|
|
917
|
+
getCleanSentences(content: string, delimiter?: string): string[];
|
|
918
|
+
/**
|
|
919
|
+
* Moderates an array of strings and returns results for each
|
|
920
|
+
*
|
|
921
|
+
* @param {string[]} contents - Array of text content to moderate
|
|
922
|
+
* @returns {ModerationResult[]} Array of moderation results
|
|
923
|
+
*
|
|
924
|
+
* @example
|
|
925
|
+
* ```typescript
|
|
926
|
+
* const results = moderator.moderateBatch([
|
|
927
|
+
* "Hello world",
|
|
928
|
+
* "This is damn bad",
|
|
929
|
+
* "Nice day"
|
|
930
|
+
* ]);
|
|
931
|
+
* console.log(results[1].isClean); // false
|
|
932
|
+
* ```
|
|
933
|
+
*/
|
|
934
|
+
moderateBatch(contents: string[]): ModerationResult[];
|
|
935
|
+
/**
|
|
936
|
+
* Gets a detailed report of all profanity found in content
|
|
937
|
+
*
|
|
938
|
+
* @param {string} content - The text content to analyze
|
|
939
|
+
* @returns {Object} Detailed profanity report
|
|
940
|
+
*
|
|
941
|
+
* @example
|
|
942
|
+
* ```typescript
|
|
943
|
+
* const report = moderator.getDetailedReport("This damn shit is bad");
|
|
944
|
+
* console.log(report);
|
|
945
|
+
* // {
|
|
946
|
+
* // isClean: false,
|
|
947
|
+
* // totalWords: 5,
|
|
948
|
+
* // profaneWords: 2,
|
|
949
|
+
* // profanityPercentage: 40,
|
|
950
|
+
* // score: 35,
|
|
951
|
+
* // highestSeverity: 'moderate',
|
|
952
|
+
* // severityCounts: { mild: 1, moderate: 1, severe: 0, wtf: 0 },
|
|
953
|
+
* // flaggedWords: ['damn', 'shit'],
|
|
954
|
+
* // details: [...]
|
|
955
|
+
* // }
|
|
956
|
+
* ```
|
|
957
|
+
*/
|
|
958
|
+
getDetailedReport(content: string): {
|
|
959
|
+
isClean: boolean;
|
|
960
|
+
totalWords: number;
|
|
961
|
+
profaneWords: number;
|
|
962
|
+
profanityPercentage: number;
|
|
963
|
+
score: number;
|
|
964
|
+
highestSeverity: WordSeverity | null;
|
|
965
|
+
severityCounts: {
|
|
966
|
+
mild: number;
|
|
967
|
+
moderate: number;
|
|
968
|
+
severe: number;
|
|
969
|
+
wtf: number;
|
|
970
|
+
};
|
|
971
|
+
flaggedWords: string[];
|
|
972
|
+
details: Array<{
|
|
973
|
+
word: string;
|
|
974
|
+
severity: WordSeverity;
|
|
975
|
+
position: number;
|
|
976
|
+
context: string;
|
|
977
|
+
}>;
|
|
978
|
+
};
|
|
979
|
+
/**
|
|
980
|
+
* Validates content and returns validation result
|
|
981
|
+
*
|
|
982
|
+
* @param {string} content - The text content to validate
|
|
983
|
+
* @param {Object} options - Validation options
|
|
984
|
+
* @param {number} [options.maxProfanityScore] - Maximum allowed profanity score
|
|
985
|
+
* @param {WordSeverity} [options.maxSeverity] - Maximum allowed severity level
|
|
986
|
+
* @param {number} [options.maxProfaneWords] - Maximum number of profane words allowed
|
|
987
|
+
* @returns {Object} Validation result with pass/fail and reasons
|
|
988
|
+
*
|
|
989
|
+
* @example
|
|
990
|
+
* ```typescript
|
|
991
|
+
* const validation = moderator.validate("This is damn good", {
|
|
992
|
+
* maxProfanityScore: 20,
|
|
993
|
+
* maxSeverity: WordSeverity.MILD,
|
|
994
|
+
* maxProfaneWords: 1
|
|
995
|
+
* });
|
|
996
|
+
* console.log(validation);
|
|
997
|
+
* // {
|
|
998
|
+
* // isValid: true,
|
|
999
|
+
* // reasons: [],
|
|
1000
|
+
* // score: 10,
|
|
1001
|
+
* // profaneWordCount: 1
|
|
1002
|
+
* // }
|
|
1003
|
+
* ```
|
|
1004
|
+
*/
|
|
1005
|
+
validate(content: string, options?: {
|
|
1006
|
+
maxProfanityScore?: number;
|
|
1007
|
+
maxSeverity?: WordSeverity;
|
|
1008
|
+
maxProfaneWords?: number;
|
|
1009
|
+
}): {
|
|
1010
|
+
isValid: boolean;
|
|
1011
|
+
reasons: string[];
|
|
1012
|
+
score: number;
|
|
1013
|
+
profaneWordCount: number;
|
|
1014
|
+
};
|
|
1015
|
+
/**
|
|
1016
|
+
* Replaces profane words with random alternatives from their alternatives list
|
|
1017
|
+
*
|
|
1018
|
+
* @param {string} content - The text content to process
|
|
1019
|
+
* @returns {string} Content with profanity replaced by random alternatives
|
|
1020
|
+
*
|
|
1021
|
+
* @example
|
|
1022
|
+
* ```typescript
|
|
1023
|
+
* const replaced = moderator.replaceWithAlternatives("This damn thing is shit");
|
|
1024
|
+
* // Output might be: "This darn thing is shoot" or "This dang thing is crap"
|
|
1025
|
+
* ```
|
|
1026
|
+
*/
|
|
1027
|
+
replaceWithAlternatives(content: string): string;
|
|
1028
|
+
/**
|
|
1029
|
+
* Gets words by severity level
|
|
1030
|
+
*
|
|
1031
|
+
* @param {WordSeverity} severity - The severity level to filter by
|
|
1032
|
+
* @returns {WordEntry[]} Array of words with the specified severity
|
|
1033
|
+
*
|
|
1034
|
+
* @example
|
|
1035
|
+
* ```typescript
|
|
1036
|
+
* const mildWords = moderator.getWordsBySeverity(WordSeverity.MILD);
|
|
1037
|
+
* console.log(mildWords); // All MILD severity words in the library
|
|
1038
|
+
* ```
|
|
1039
|
+
*/
|
|
1040
|
+
getWordsBySeverity(severity: WordSeverity): WordEntry[];
|
|
1041
|
+
/**
|
|
1042
|
+
* Checks if a specific word is in the library
|
|
1043
|
+
*
|
|
1044
|
+
* @param {string} word - The word to check
|
|
1045
|
+
* @returns {boolean} True if the word is in the library, false otherwise
|
|
1046
|
+
*
|
|
1047
|
+
* @example
|
|
1048
|
+
* ```typescript
|
|
1049
|
+
* const hasWord = moderator.hasWord('damn');
|
|
1050
|
+
* console.log(hasWord); // true
|
|
1051
|
+
* ```
|
|
1052
|
+
*/
|
|
1053
|
+
hasWord(word: string): boolean;
|
|
1054
|
+
/**
|
|
1055
|
+
* Gets information about a specific word
|
|
1056
|
+
*
|
|
1057
|
+
* @param {string} word - The word to look up
|
|
1058
|
+
* @returns {WordEntry | null} Word entry if found, null otherwise
|
|
1059
|
+
*
|
|
1060
|
+
* @example
|
|
1061
|
+
* ```typescript
|
|
1062
|
+
* const info = moderator.getWordInfo('damn');
|
|
1063
|
+
* console.log(info);
|
|
1064
|
+
* // { word: 'damn', severity: 'mild', alternatives: ['darn', 'dang'] }
|
|
1065
|
+
* ```
|
|
1066
|
+
*/
|
|
1067
|
+
getWordInfo(word: string): WordEntry | null;
|
|
1068
|
+
/**
|
|
1069
|
+
* Filters an array of strings to only include clean content
|
|
1070
|
+
*
|
|
1071
|
+
* @param {string[]} contents - Array of text content to filter
|
|
1072
|
+
* @returns {string[]} Array containing only clean content
|
|
1073
|
+
*
|
|
1074
|
+
* @example
|
|
1075
|
+
* ```typescript
|
|
1076
|
+
* const filtered = moderator.filterClean([
|
|
1077
|
+
* "Hello world",
|
|
1078
|
+
* "This is damn bad",
|
|
1079
|
+
* "Nice day"
|
|
1080
|
+
* ]);
|
|
1081
|
+
* console.log(filtered); // ["Hello world", "Nice day"]
|
|
1082
|
+
* ```
|
|
1083
|
+
*/
|
|
1084
|
+
filterClean(contents: string[]): string[];
|
|
1085
|
+
/**
|
|
1086
|
+
* Filters an array of strings to only include profane content
|
|
1087
|
+
*
|
|
1088
|
+
* @param {string[]} contents - Array of text content to filter
|
|
1089
|
+
* @returns {string[]} Array containing only profane content
|
|
1090
|
+
*
|
|
1091
|
+
* @example
|
|
1092
|
+
* ```typescript
|
|
1093
|
+
* const profane = moderator.filterProfane([
|
|
1094
|
+
* "Hello world",
|
|
1095
|
+
* "This is damn bad",
|
|
1096
|
+
* "Nice day"
|
|
1097
|
+
* ]);
|
|
1098
|
+
* console.log(profane); // ["This is damn bad"]
|
|
1099
|
+
* ```
|
|
1100
|
+
*/
|
|
1101
|
+
filterProfane(contents: string[]): string[];
|
|
1102
|
+
/**
|
|
1103
|
+
* Suggests alternatives for a given word if it's in the library
|
|
1104
|
+
*
|
|
1105
|
+
* @param {string} word - The word to get suggestions for
|
|
1106
|
+
* @returns {string[]} Array of alternative words, empty if word not found or no alternatives
|
|
1107
|
+
*
|
|
1108
|
+
* @example
|
|
1109
|
+
* ```typescript
|
|
1110
|
+
* const suggestions = moderator.getSuggestions('damn');
|
|
1111
|
+
* console.log(suggestions); // ['darn', 'dang']
|
|
1112
|
+
* ```
|
|
1113
|
+
*/
|
|
1114
|
+
getSuggestions(word: string): string[];
|
|
1115
|
+
test(): void;
|
|
1116
|
+
}
|
|
1117
|
+
/**
|
|
1118
|
+
* Quick utility function for one-off moderation without creating an instance
|
|
1119
|
+
*
|
|
1120
|
+
* @param {string} content - The text content to moderate
|
|
1121
|
+
* @param {ModerationLevel} [level=ModerationLevel.MODERATE] - Moderation level to use
|
|
1122
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
1123
|
+
*
|
|
1124
|
+
* @example
|
|
1125
|
+
* ```typescript
|
|
1126
|
+
* import { quickModerate, ModerationLevel } from 'profanity-guard';
|
|
1127
|
+
*
|
|
1128
|
+
* const result = quickModerate("Some damn text", ModerationLevel.STRICT);
|
|
1129
|
+
* console.log(result.sanitized);
|
|
1130
|
+
* ```
|
|
1131
|
+
*
|
|
1132
|
+
* @remarks
|
|
1133
|
+
* This function creates a new ProfanityGuard instance with the full word library for each call.
|
|
1134
|
+
* For better performance when moderating multiple pieces of content, create a ProfanityGuard
|
|
1135
|
+
* instance once and reuse it.
|
|
1136
|
+
*/
|
|
1137
|
+
declare function quickModerate(content: string, level?: ModerationLevel): ModerationResult;
|
|
1138
|
+
/**
|
|
1139
|
+
* Quick utility to check if content is clean
|
|
1140
|
+
*
|
|
1141
|
+
* @param {string} content - The text content to check
|
|
1142
|
+
* @param {ModerationLevel} [level=ModerationLevel.MODERATE] - Moderation level to use
|
|
1143
|
+
* @returns {boolean} True if clean, false otherwise
|
|
1144
|
+
*
|
|
1145
|
+
* @example
|
|
1146
|
+
* ```typescript
|
|
1147
|
+
* import { quickCheck } from 'profanity-guard';
|
|
1148
|
+
*
|
|
1149
|
+
* if (quickCheck("Hello world")) {
|
|
1150
|
+
* console.log("Content is clean!");
|
|
1151
|
+
* }
|
|
1152
|
+
* ```
|
|
1153
|
+
*/
|
|
1154
|
+
declare function quickCheck(content: string, level?: ModerationLevel): boolean;
|
|
1155
|
+
/**
|
|
1156
|
+
* Quick utility to sanitize content
|
|
1157
|
+
*
|
|
1158
|
+
* @param {string} content - The text content to sanitize
|
|
1159
|
+
* @param {ModerationLevel} [level=ModerationLevel.MODERATE] - Moderation level to use
|
|
1160
|
+
* @param {string} [censorChar='*'] - Character to use for censoring
|
|
1161
|
+
* @returns {string} Sanitized content
|
|
1162
|
+
*
|
|
1163
|
+
* @example
|
|
1164
|
+
* ```typescript
|
|
1165
|
+
* import { quickSanitize } from 'profanity-guard';
|
|
1166
|
+
*
|
|
1167
|
+
* const clean = quickSanitize("This damn text");
|
|
1168
|
+
* console.log(clean); // "This **** text"
|
|
1169
|
+
* ```
|
|
1170
|
+
*/
|
|
1171
|
+
declare function quickSanitize(content: string, level?: ModerationLevel, censorChar?: string): string;
|
|
1172
|
+
/**
|
|
1173
|
+
* Quick utility to get profanity score
|
|
1174
|
+
*
|
|
1175
|
+
* @param {string} content - The text content to score
|
|
1176
|
+
* @param {ModerationLevel} [level=ModerationLevel.MODERATE] - Moderation level to use
|
|
1177
|
+
* @returns {number} Profanity score (0-100)
|
|
1178
|
+
*
|
|
1179
|
+
* @example
|
|
1180
|
+
* ```typescript
|
|
1181
|
+
* import { quickScore } from 'profanity-guard';
|
|
1182
|
+
*
|
|
1183
|
+
* const score = quickScore("This damn shit is bad");
|
|
1184
|
+
* console.log(score); // e.g., 45
|
|
1185
|
+
* ```
|
|
1186
|
+
*/
|
|
1187
|
+
declare function quickScore(content: string, level?: ModerationLevel): number;
|
|
1188
|
+
/**
|
|
1189
|
+
* Quick utility to validate content against criteria
|
|
1190
|
+
*
|
|
1191
|
+
* @param {string} content - The text content to validate
|
|
1192
|
+
* @param {Object} options - Validation options
|
|
1193
|
+
* @returns {boolean} True if valid, false otherwise
|
|
1194
|
+
*
|
|
1195
|
+
* @example
|
|
1196
|
+
* ```typescript
|
|
1197
|
+
* import { quickValidate } from 'profanity-guard';
|
|
1198
|
+
*
|
|
1199
|
+
* const isValid = quickValidate("Hello world", { maxProfanityScore: 10 });
|
|
1200
|
+
* console.log(isValid); // true
|
|
1201
|
+
* ```
|
|
1202
|
+
*/
|
|
1203
|
+
declare function quickValidate(content: string, options?: {
|
|
1204
|
+
maxProfanityScore?: number;
|
|
1205
|
+
maxSeverity?: WordSeverity;
|
|
1206
|
+
maxProfaneWords?: number;
|
|
1207
|
+
level?: ModerationLevel;
|
|
1208
|
+
}): boolean;
|
|
1209
|
+
/**
|
|
1210
|
+
* Quick moderation for RELAXED level (only severe/wtf words)
|
|
1211
|
+
* Lazy-loads only severe and wtf word lists for minimal bundle impact
|
|
1212
|
+
*
|
|
1213
|
+
* @param {string} content - The text content to moderate
|
|
1214
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
1215
|
+
*/
|
|
1216
|
+
declare function quickModerateRelaxed(content: string): ModerationResult;
|
|
1217
|
+
/**
|
|
1218
|
+
* Quick moderation for MODERATE level (moderate/severe/wtf words)
|
|
1219
|
+
* Lazy-loads moderate, severe, and wtf word lists
|
|
1220
|
+
*
|
|
1221
|
+
* @param {string} content - The text content to moderate
|
|
1222
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
1223
|
+
*/
|
|
1224
|
+
declare function quickModerateModerate(content: string): ModerationResult;
|
|
1225
|
+
/**
|
|
1226
|
+
* Quick moderation for STRICT level (all words)
|
|
1227
|
+
* Lazy-loads all word lists
|
|
1228
|
+
*
|
|
1229
|
+
* @param {string} content - The text content to moderate
|
|
1230
|
+
* @returns {ModerationResult} Detailed moderation results
|
|
1231
|
+
*/
|
|
1232
|
+
declare function quickModerateStrict(content: string): ModerationResult;
|
|
1233
|
+
/**
|
|
1234
|
+
* Quick check for RELAXED level
|
|
1235
|
+
* @param {string} content - The text content to check
|
|
1236
|
+
* @returns {boolean} True if clean, false otherwise
|
|
1237
|
+
*/
|
|
1238
|
+
declare function quickCheckRelaxed(content: string): boolean;
|
|
1239
|
+
/**
|
|
1240
|
+
* Quick check for MODERATE level
|
|
1241
|
+
* @param {string} content - The text content to check
|
|
1242
|
+
* @returns {boolean} True if clean, false otherwise
|
|
1243
|
+
*/
|
|
1244
|
+
declare function quickCheckModerate(content: string): boolean;
|
|
1245
|
+
/**
|
|
1246
|
+
* Quick check for STRICT level
|
|
1247
|
+
* @param {string} content - The text content to check
|
|
1248
|
+
* @returns {boolean} True if clean, false otherwise
|
|
1249
|
+
*/
|
|
1250
|
+
declare function quickCheckStrict(content: string): boolean;
|
|
1251
|
+
/**
|
|
1252
|
+
* Quick sanitize for RELAXED level
|
|
1253
|
+
* @param {string} content - The text content to sanitize
|
|
1254
|
+
* @param {string} [censorChar='*'] - Character to use for censoring
|
|
1255
|
+
* @returns {string} Sanitized content
|
|
1256
|
+
*/
|
|
1257
|
+
declare function quickSanitizeRelaxed(content: string, censorChar?: string): string;
|
|
1258
|
+
/**
|
|
1259
|
+
* Quick sanitize for MODERATE level
|
|
1260
|
+
* @param {string} content - The text content to sanitize
|
|
1261
|
+
* @param {string} [censorChar='*'] - Character to use for censoring
|
|
1262
|
+
* @returns {string} Sanitized content
|
|
1263
|
+
*/
|
|
1264
|
+
declare function quickSanitizeModerate(content: string, censorChar?: string): string;
|
|
1265
|
+
/**
|
|
1266
|
+
* Quick sanitize for STRICT level
|
|
1267
|
+
* @param {string} content - The text content to sanitize
|
|
1268
|
+
* @param {string} [censorChar='*'] - Character to use for censoring
|
|
1269
|
+
* @returns {string} Sanitized content
|
|
1270
|
+
*/
|
|
1271
|
+
declare function quickSanitizeStrict(content: string, censorChar?: string): string;
|
|
1272
|
+
|
|
1273
|
+
/**
|
|
1274
|
+
* Word Library Module
|
|
1275
|
+
*
|
|
1276
|
+
* @module core/library
|
|
1277
|
+
* @description Comprehensive word library for content moderation with severity classifications
|
|
1278
|
+
*
|
|
1279
|
+
* @remarks
|
|
1280
|
+
* This library uses lazy loading to minimize bundle size. Word lists are only loaded when needed.
|
|
1281
|
+
* The library is expandable and should be customized based on your specific needs using:
|
|
1282
|
+
* - {@link ProfanityGuard.addWord}
|
|
1283
|
+
* - {@link ProfanityGuard.addWords}
|
|
1284
|
+
* - {@link ProfanityGuard.importLibrary}
|
|
1285
|
+
*/
|
|
1286
|
+
|
|
1287
|
+
/**
|
|
1288
|
+
* Legacy exports for backward compatibility
|
|
1289
|
+
* @deprecated Use lazy loading functions instead for better bundle size
|
|
1290
|
+
*/
|
|
1291
|
+
declare const mild_bad_words: WordEntry[];
|
|
1292
|
+
declare const moderate_bad_words: WordEntry[];
|
|
1293
|
+
declare const severe_bad_words: WordEntry[];
|
|
1294
|
+
declare const wtf_bad_words: WordEntry[];
|
|
1295
|
+
declare const all_bad_words: WordEntry[];
|
|
1296
|
+
|
|
1297
|
+
/**
|
|
1298
|
+
* Configuration options for useProfanityGuard hook
|
|
1299
|
+
*/
|
|
1300
|
+
interface UseProfanityGuardOptions {
|
|
1301
|
+
/** Moderation level to use */
|
|
1302
|
+
level?: ModerationLevel;
|
|
1303
|
+
/** Character to use for censoring */
|
|
1304
|
+
censorChar?: string;
|
|
1305
|
+
/** Custom word library to import */
|
|
1306
|
+
customLibrary?: WordEntry[];
|
|
1307
|
+
/** Whether to clear default library before importing custom library */
|
|
1308
|
+
clearDefault?: boolean;
|
|
1309
|
+
}
|
|
1310
|
+
/**
|
|
1311
|
+
* Main hook for content moderation
|
|
1312
|
+
*
|
|
1313
|
+
* @param options - Configuration options
|
|
1314
|
+
* @returns Moderation utilities and state
|
|
1315
|
+
*
|
|
1316
|
+
* @example
|
|
1317
|
+
* ```tsx
|
|
1318
|
+
* function CommentForm() {
|
|
1319
|
+
* const { moderate, isClean, sanitize } = useProfanityGuard({
|
|
1320
|
+
* level: ModerationLevel.MODERATE
|
|
1321
|
+
* });
|
|
1322
|
+
*
|
|
1323
|
+
* const [comment, setComment] = useState('');
|
|
1324
|
+
* const result = moderate(comment);
|
|
1325
|
+
*
|
|
1326
|
+
* return (
|
|
1327
|
+
* <div>
|
|
1328
|
+
* <textarea value={comment} onChange={e => setComment(e.target.value)} />
|
|
1329
|
+
* {!result.isClean && <p>Please remove profanity</p>}
|
|
1330
|
+
* </div>
|
|
1331
|
+
* );
|
|
1332
|
+
* }
|
|
1333
|
+
* ```
|
|
1334
|
+
*/
|
|
1335
|
+
declare function useProfanityGuard(options?: UseProfanityGuardOptions): {
|
|
1336
|
+
moderate: (content: string) => ModerationResult;
|
|
1337
|
+
isClean: (content: string) => boolean;
|
|
1338
|
+
sanitize: (content: string) => string;
|
|
1339
|
+
moderateSentence: (content: string, preserveStructure?: boolean) => ModerationResult;
|
|
1340
|
+
setModerationLevel: (newLevel: ModerationLevel) => void;
|
|
1341
|
+
addWord: (word: string, severity: WordSeverity, alternatives?: string[]) => void;
|
|
1342
|
+
removeWord: (word: string) => boolean;
|
|
1343
|
+
moderator: ProfanityGuard;
|
|
1344
|
+
};
|
|
1345
|
+
/**
|
|
1346
|
+
* Hook for real-time content moderation with state management
|
|
1347
|
+
*
|
|
1348
|
+
* @param initialContent - Initial content value
|
|
1349
|
+
* @param options - Configuration options
|
|
1350
|
+
* @returns Content state and moderation utilities
|
|
1351
|
+
*
|
|
1352
|
+
* @example
|
|
1353
|
+
* ```tsx
|
|
1354
|
+
* function ChatInput() {
|
|
1355
|
+
* const {
|
|
1356
|
+
* content,
|
|
1357
|
+
* setContent,
|
|
1358
|
+
* result,
|
|
1359
|
+
* sanitizedContent,
|
|
1360
|
+
* isClean
|
|
1361
|
+
* } = useModeratedInput('', { level: ModerationLevel.STRICT });
|
|
1362
|
+
*
|
|
1363
|
+
* return (
|
|
1364
|
+
* <div>
|
|
1365
|
+
* <input
|
|
1366
|
+
* value={content}
|
|
1367
|
+
* onChange={e => setContent(e.target.value)}
|
|
1368
|
+
* />
|
|
1369
|
+
* {!isClean && <p className="error">Contains profanity</p>}
|
|
1370
|
+
* <p>Preview: {sanitizedContent}</p>
|
|
1371
|
+
* </div>
|
|
1372
|
+
* );
|
|
1373
|
+
* }
|
|
1374
|
+
* ```
|
|
1375
|
+
*/
|
|
1376
|
+
declare function useModeratedInput(initialContent?: string, options?: UseProfanityGuardOptions): {
|
|
1377
|
+
content: string;
|
|
1378
|
+
setContent: react.Dispatch<react.SetStateAction<string>>;
|
|
1379
|
+
result: ModerationResult;
|
|
1380
|
+
sanitizedContent: string;
|
|
1381
|
+
isClean: boolean;
|
|
1382
|
+
foundWords: string[];
|
|
1383
|
+
severity: WordSeverity;
|
|
1384
|
+
};
|
|
1385
|
+
/**
|
|
1386
|
+
* Hook for batch content moderation
|
|
1387
|
+
*
|
|
1388
|
+
* @param options - Configuration options
|
|
1389
|
+
* @returns Batch moderation utilities
|
|
1390
|
+
*
|
|
1391
|
+
* @example
|
|
1392
|
+
* ```tsx
|
|
1393
|
+
* function CommentList({ comments }) {
|
|
1394
|
+
* const { moderateBatch, filterClean, filterProfane } = useBatchModeration();
|
|
1395
|
+
*
|
|
1396
|
+
* const results = moderateBatch(comments);
|
|
1397
|
+
* const cleanComments = filterClean(comments);
|
|
1398
|
+
*
|
|
1399
|
+
* return (
|
|
1400
|
+
* <div>
|
|
1401
|
+
* {cleanComments.map(comment => <div key={comment}>{comment}</div>)}
|
|
1402
|
+
* </div>
|
|
1403
|
+
* );
|
|
1404
|
+
* }
|
|
1405
|
+
* ```
|
|
1406
|
+
*/
|
|
1407
|
+
declare function useBatchModeration(options?: UseProfanityGuardOptions): {
|
|
1408
|
+
moderateBatch: (contents: string[]) => ModerationResult[];
|
|
1409
|
+
filterClean: (contents: string[]) => string[];
|
|
1410
|
+
filterProfane: (contents: string[]) => string[];
|
|
1411
|
+
};
|
|
1412
|
+
/**
|
|
1413
|
+
* Hook for form validation with profanity checking
|
|
1414
|
+
*
|
|
1415
|
+
* @param options - Configuration options
|
|
1416
|
+
* @returns Validation utilities
|
|
1417
|
+
*
|
|
1418
|
+
* @example
|
|
1419
|
+
* ```tsx
|
|
1420
|
+
* function SignupForm() {
|
|
1421
|
+
* const { validateField, errors } = useProfanityValidation();
|
|
1422
|
+
* const [username, setUsername] = useState('');
|
|
1423
|
+
*
|
|
1424
|
+
* const handleSubmit = (e) => {
|
|
1425
|
+
* e.preventDefault();
|
|
1426
|
+
* if (validateField('username', username)) {
|
|
1427
|
+
* // Submit form
|
|
1428
|
+
* }
|
|
1429
|
+
* };
|
|
1430
|
+
*
|
|
1431
|
+
* return (
|
|
1432
|
+
* <form onSubmit={handleSubmit}>
|
|
1433
|
+
* <input value={username} onChange={e => setUsername(e.target.value)} />
|
|
1434
|
+
* {errors.username && <p>{errors.username}</p>}
|
|
1435
|
+
* </form>
|
|
1436
|
+
* );
|
|
1437
|
+
* }
|
|
1438
|
+
* ```
|
|
1439
|
+
*/
|
|
1440
|
+
declare function useProfanityValidation(options?: UseProfanityGuardOptions): {
|
|
1441
|
+
validateField: (fieldName: string, value: string) => boolean;
|
|
1442
|
+
errors: Record<string, string>;
|
|
1443
|
+
clearError: (fieldName: string) => void;
|
|
1444
|
+
clearAllErrors: () => void;
|
|
1445
|
+
hasErrors: boolean;
|
|
1446
|
+
};
|
|
1447
|
+
/**
|
|
1448
|
+
* Hook for live content sanitization with debouncing
|
|
1449
|
+
*
|
|
1450
|
+
* @param delay - Debounce delay in milliseconds
|
|
1451
|
+
* @param options - Configuration options
|
|
1452
|
+
* @returns Sanitization utilities
|
|
1453
|
+
*
|
|
1454
|
+
* @example
|
|
1455
|
+
* ```tsx
|
|
1456
|
+
* function LiveEditor() {
|
|
1457
|
+
* const { content, setContent, sanitized, isProcessing } = useLiveSanitizer(300);
|
|
1458
|
+
*
|
|
1459
|
+
* return (
|
|
1460
|
+
* <div>
|
|
1461
|
+
* <textarea value={content} onChange={e => setContent(e.target.value)} />
|
|
1462
|
+
* {isProcessing && <span>Processing...</span>}
|
|
1463
|
+
* <div>Sanitized: {sanitized}</div>
|
|
1464
|
+
* </div>
|
|
1465
|
+
* );
|
|
1466
|
+
* }
|
|
1467
|
+
* ```
|
|
1468
|
+
*/
|
|
1469
|
+
declare function useLiveSanitizer(delay?: number, options?: UseProfanityGuardOptions): {
|
|
1470
|
+
content: string;
|
|
1471
|
+
setContent: react.Dispatch<react.SetStateAction<string>>;
|
|
1472
|
+
sanitized: string;
|
|
1473
|
+
isProcessing: boolean;
|
|
1474
|
+
};
|
|
1475
|
+
/**
|
|
1476
|
+
* Hook for profanity statistics and analytics
|
|
1477
|
+
*
|
|
1478
|
+
* @param options - Configuration options
|
|
1479
|
+
* @returns Statistics utilities
|
|
1480
|
+
*
|
|
1481
|
+
* @example
|
|
1482
|
+
* ```tsx
|
|
1483
|
+
* function ModerationDashboard() {
|
|
1484
|
+
* const { stats, analyzeContent, history } = useProfanityStats();
|
|
1485
|
+
*
|
|
1486
|
+
* return (
|
|
1487
|
+
* <div>
|
|
1488
|
+
* <h2>Moderation Stats</h2>
|
|
1489
|
+
* <p>Total analyzed: {history.length}</p>
|
|
1490
|
+
* <p>Flagged: {history.filter(h => !h.isClean).length}</p>
|
|
1491
|
+
* </div>
|
|
1492
|
+
* );
|
|
1493
|
+
* }
|
|
1494
|
+
* ```
|
|
1495
|
+
*/
|
|
1496
|
+
declare function useProfanityStats(options?: UseProfanityGuardOptions): {
|
|
1497
|
+
stats: {
|
|
1498
|
+
library: {
|
|
1499
|
+
total: number;
|
|
1500
|
+
mild: number;
|
|
1501
|
+
moderate: number;
|
|
1502
|
+
severe: number;
|
|
1503
|
+
wtf: number;
|
|
1504
|
+
totalVariants: number;
|
|
1505
|
+
};
|
|
1506
|
+
analyzed: {
|
|
1507
|
+
total: number;
|
|
1508
|
+
flagged: number;
|
|
1509
|
+
clean: number;
|
|
1510
|
+
flaggedPercentage: number;
|
|
1511
|
+
};
|
|
1512
|
+
};
|
|
1513
|
+
analyzeContent: (content: string) => ModerationResult;
|
|
1514
|
+
history: ModerationResult[];
|
|
1515
|
+
clearHistory: () => void;
|
|
1516
|
+
};
|
|
1517
|
+
/**
|
|
1518
|
+
* Hook for content replacement with alternatives
|
|
1519
|
+
*
|
|
1520
|
+
* @param options - Configuration options
|
|
1521
|
+
* @returns Replacement utilities
|
|
1522
|
+
*
|
|
1523
|
+
* @example
|
|
1524
|
+
* ```tsx
|
|
1525
|
+
* function SmartEditor() {
|
|
1526
|
+
* const { replaceWithAlternatives, getSuggestions } = useContentReplacement();
|
|
1527
|
+
* const [text, setText] = useState('');
|
|
1528
|
+
*
|
|
1529
|
+
* const handleReplace = () => {
|
|
1530
|
+
* setText(replaceWithAlternatives(text));
|
|
1531
|
+
* };
|
|
1532
|
+
*
|
|
1533
|
+
* return (
|
|
1534
|
+
* <div>
|
|
1535
|
+
* <textarea value={text} onChange={e => setText(e.target.value)} />
|
|
1536
|
+
* <button onClick={handleReplace}>Replace Profanity</button>
|
|
1537
|
+
* </div>
|
|
1538
|
+
* );
|
|
1539
|
+
* }
|
|
1540
|
+
* ```
|
|
1541
|
+
*/
|
|
1542
|
+
declare function useContentReplacement(options?: UseProfanityGuardOptions): {
|
|
1543
|
+
replaceWithAlternatives: (content: string) => string;
|
|
1544
|
+
getSuggestions: (word: string) => string[];
|
|
1545
|
+
getWordInfo: (word: string) => WordEntry;
|
|
1546
|
+
};
|
|
1547
|
+
|
|
1548
|
+
export { type LibraryStats, type Match, ModerationLevel, type ModerationResult, ProfanityGuard, type ProfanityGuardConfig, type UseProfanityGuardOptions, type WordEntry, WordSeverity, all_bad_words, mild_bad_words, moderate_bad_words, quickCheck, quickCheckModerate, quickCheckRelaxed, quickCheckStrict, quickModerate, quickModerateModerate, quickModerateRelaxed, quickModerateStrict, quickSanitize, quickSanitizeModerate, quickSanitizeRelaxed, quickSanitizeStrict, quickScore, quickValidate, severe_bad_words, useBatchModeration, useContentReplacement, useLiveSanitizer, useModeratedInput, useProfanityGuard, useProfanityStats, useProfanityValidation, wtf_bad_words };
|