@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.
@@ -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 };