Skip to content

Commit e7c3098

Browse files
DerrickRichardDerrickRichard
authored
Update README.md to match v2.0.0 update.
1 parent fb09ebe commit e7c3098

1 file changed

Lines changed: 80 additions & 97 deletions

File tree

‎README.md‎

Lines changed: 80 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,166 +1,149 @@
1-
CensorCore
1+
CensorCore
22
==========
3-
<p><strong><span style="color:red">⚠️ WARNING: The <code>wordlist.json</code> file contains explicit language, slurs, and other harmful content. View it at your own risk.</span></strong></p>
4-
<hr>
5-
CensorCore is a lightweight JavaScript library for detecting explicit or inappropriate text using a centralized JSON wordlist. It is designed for straightforward integration: include a single script tag and call one function within your message handling logic. CensorCore is suitable for chat applications, comment systems, forms, or any environment where user generated text requires screening.
63

7-
Features
8-
--------
9-
10-
- Zero configuration setup
11-
12-
- Shared JSON wordlist loaded from CDN
4+
⚠️ WARNING: The `wordlist.json` file contains explicit language, slurs, and other harmful content. View it at your own risk.
135

14-
- Efficient whole word matching
6+
CensorCore is a lightweight JavaScript library for detecting explicit, harmful, or inappropriate text using a centralized JSON wordlist. It is designed for straightforward integration: include a single script tag and call one function within your message‑handling logic.
157

16-
- Minimal and predictable API
8+
Version 2.0 introduces a more advanced moderation engine with phrase detection, severity levels, async loading events, and a detailed `analyze()` API, while remaining fully backward‑compatible with the original `isBlocked()` function. CensorCore is suitable for chat applications, comment systems, forms, or any environment where user‑generated text requires screening.
179

18-
- No DOM modification or event interception
10+
Features
1911

20-
- Full control retained by the integrating developer
12+
- Zero‑configuration setup - Shared JSON wordlist loaded from CDN - Phrase detection (supports multi‑word entries) - Automatic severity mapping based on category - Minimal and predictable API (isBlocked + analyze) - Async lifecycle events (onReady, onError) - Optional custom rule extension - No DOM modification or event interception - Full control retained by the integrating developer
2113

2214
Installation
23-
------------
24-
25-
To install CensorCore, include the script tag in the <head> tag of your HTML file to ensure it loads before your application code runs:
26-
27-
`<script src="https://cdn.jsdelivr.net/gh/DerrickRichard/CensorCore-Library@latest/CensorCore.js"></script>`
28-
29-
The library will load after your code runs if you put it near the closing `<html>` tag, causing it to fail.
30-
31-
After the script loads, a global object named censor will be available for use in your JavaScript.
32-
33-
Make sure your internet connection allows loading scripts from the CDN[ ](https://cdn.jsdelivr.net)[cdn.jsdelivr.net](http://cdn.jsdelivr.net).
34-
35-
Inside your logic to send messages, add this inside the function:
3615

37-
```JavaScript
38-
//Block explicit messages using the CensorCore library
16+
To install CensorCore, include the script tag in the `<head>` of your HTML file to ensure it loads before your application code runs:
3917

40-
if (censor.isBlocked(text)) {
18+
Code
4119

42-
alert("Message blocked: Inappropriate Content");
43-
44-
return;
45-
46-
}
4720
```
48-
Your entire send function should look similar to this:
49-
50-
```JavaScript
51-
function sendMessage() {
21+
<script src="https://cdn.jsdelivr.net/gh/DerrickRichard/CensorCore-Library@latest/CensorCore.js"></script>
5222
53-
      const text = input.value;
54-
55-
      // Block explicit messages using the CensorCore library
23+
```
5624

57-
      if (censor.isBlocked(text)) {
25+
If you place the script near the closing `</html>` tag, the library may load after your code runs, which can prevent the wordlist from initializing correctly.
5826

59-
        alert("Message blocked: Inappropriate Content");
27+
After the script loads, a global object named `censor` will be available for use in your JavaScript.
6028

61-
        return;
29+
Make sure your internet connection allows loading scripts from the CDN at:
6230

63-
      }
31+
https://cdn.jsdelivr.net
6432

65-
      addMessage(text);
33+
Basic Integration
6634

67-
      input.value = '';
35+
Inside your message‑sending logic, add this check:
6836

69-
      input.focus();
37+
JavaScript
7038

71-
    }
7239
```
40+
// Block explicit messages using the CensorCore library
41+
if (censor.isBlocked(text)) {
42+
alert("Message blocked: Inappropriate Content");
43+
return;
44+
}
7345
74-
If you prefer, you can download the script and host it locally by cloning the repository or downloading the file directly, then updating the script src attribute accordingly.
46+
```
7547

76-
Example of local hosting:
48+
A full example:
7749

78-
`<script src="path/to/CensorCore.js"></script>`
50+
JavaScript
7951

80-
This setup requires no additional configuration and works out of the box.
52+
```
53+
function sendMessage() {
54+
const text = input.value;
8155
82-
Usage
83-
-----
56+
// Block explicit messages using the CensorCore library
57+
if (censor.isBlocked(text)) {
58+
alert("Message blocked: Inappropriate Content");
59+
return;
60+
}
8461
85-
Call `censor.isBlocked(text)` before sending or processing a message. Integrate this check into your message sending logic to prevent inappropriate content from being sent.
62+
addMessage(text);
63+
input.value = '';
64+
input.focus();
65+
}
8666
87-
Example:
67+
```
8868

89-
```JavaScript
90-
function sendMessage() {
69+
Advanced Usage (Version 2.0)
9170

92-
  const text = input.value;
71+
Use the new `analyze()` API for detailed moderation results:
9372

94-
  // Check if the message contains blocked words
73+
JavaScript
9574

96-
  if (censor.isBlocked(text)) {
75+
```
76+
const result = censor.analyze(text);
9777
98-
    alert("Message blocked: Inappropriate Content");
78+
if (result.blocked) {
79+
console.log("Blocked severity:", result.severity);
80+
console.log("Category:", result.category);
81+
console.log("Matches:", result.matches);
82+
}
9983
100-
    return; // Prevent sending the message
84+
```
10185

102-
  }
86+
Custom Rules
10387

104-
  // Proceed with sending the message
88+
You can add your own rules without modifying the main wordlist:
10589

106-
  addMessage(text);
90+
JavaScript
10791

108-
}
10992
```
93+
censor.extend([
94+
{ text: "my custom phrase", category: "custom", severity: "medium" }
95+
]);
11096
111-
In your sending logic, ensure you `call censor.isBlocked(text)` with the message text before actually sending or processing it. If it returns true, block the message and notify the user accordingly. You are able to adjust the alert content to your preferences.
97+
```
11298

11399
Wordlist Structure
114-
------------------
115100

116-
CensorCore loads a JSON file structured by category:
101+
CensorCore loads a JSON file structured by category. Your actual wordlist includes categories such as:
117102

118-
```json
119-
{
103+
profanity hate_speech harassment sexual_content violence self_harm drugs weapons extremism terrorism disallowed_phrases custom
120104

121-
"profanity": ["word1", "word2"],
105+
Each category is automatically assigned a severity level (low, medium, or high). All categories are merged into a single internal rule engine.
122106

123-
"hate_speech": ["word3", "word4"],
107+
The CensorCore wordlist is curated solely by Derrick Richard to ensure consistency and quality. Community members cannot directly edit the wordlist. To request a new word or phrase, please use the Word Request section in the repository's Discussions page.
124108

125-
"harassment": ["word5", "word6"]
109+
API Reference
126110

127-
}
128-
```
111+
censor.isBlocked(text) Returns true if the text contains any blocked content.
129112

130-
All categories are automatically merged into a single internal list. The CensorCore word list is curated solely by Derrick Richard to ensure consistency and quality. Community members cannot directly edit the word list. To request a new word or phrase, please submit a request in the Word Request section of the repository's Discussions page.
113+
censor.analyze(text) Returns a detailed moderation result including: - whether the text is blocked - highest severity - category - all matched rules
131114

132-
API Reference
133-
-------------
115+
censor.extend(rules) Adds custom moderation rules at runtime.
116+
117+
censor.isReady() Returns true when the wordlist has finished loading.
134118

135-
### censor.isBlocked(text: string): boolean
119+
censor.isFailed() Returns true if the wordlist failed to load.
136120

137-
Returns true if the provided text contains any banned words. Returns false otherwise.
121+
censor.onReady(callback) Fires when the moderation engine is ready.
122+
123+
censor.onError(callback) Fires if the moderation engine fails to load.
138124

139125
Design Philosophy
140-
-----------------
141126

142-
CensorCore intentionally avoids modifying the host page's DOM, intercepting events, or altering user interface behavior. Instead, it provides a clear and predictable function that developers can integrate into their own message--handling logic. This approach ensures transparency, stability, and compatibility across a wide range of applications.
127+
CensorCore avoids modifying the DOM, intercepting events, or altering UI behavior. Instead, it provides a predictable, developer‑controlled moderation function. This ensures transparency, stability, and compatibility across a wide range of applications.
143128

144129
About the Developer
145-
-------------------
146-
147-
CensorCore was created and is maintained by Derrick Richard, a high school developer focused on building practical, lightweight tools for the web. He publishes weekly programming articles on[ dev.to](https://dev.to), which can be found at:
148130

149-
<https://dev.to/derrickrichard/>
131+
CensorCore was created and is maintained by Derrick Richard, a high school developer focused on building practical, lightweight tools for the web.
150132

151-
More information about his work and background is available on his personal profile:
133+
He publishes weekly programming articles at: https://dev.to/derrickrichard/
152134

153-
<https://derrickrichard.github.io/profile/>
135+
More information about his work is available at: https://derrickrichard.github.io/profile/
154136

155-
The CensorCore word list is curated solely by Derrick Richard to ensure consistency and quality. Community members cannot directly edit the word list. To request a new word or phrase, please submit a request in the Word Request section of the repository's Discussions page.
137+
The CensorCore wordlist is curated solely by Derrick Richard to ensure consistency and quality. Community members cannot directly edit the wordlist. To request a new word or phrase, please submit a request in the Word Request section of the repository's Discussions page.
156138

157139
Versions
158-
--------
159140

160-
- v1.0.0: Initial release with basic filtering functionality and a basic JSON wordlist.
161-
- v1.1.0: CensorCore v1.1.0 makes the filtering engine faster and more dependable. The wordlist is now processed ahead of time, the matching is quicker, and the library handles text in a more consistent way. The code has also been cleaned up so it is easier to follow and maintain. This update adds a couple of small helper functions that let you check whether the wordlist has loaded or if something went wrong while loading it. The public API is locked so it cannot be changed by accident, and the library behaves more safely if it is used before it finishes loading. Overall, this release makes CensorCore smoother and more reliable without changing how you already use it.
141+
v1.0.0 -- Initial release with basic filtering functionality and a basic JSON wordlist.
142+
143+
v1.1.0 -- CensorCore v1.1.0 makes the filtering engine faster and more dependable. The wordlist is now processed ahead of time, the matching is quicker, and the library handles text in a more consistent way. The code has also been cleaned up so it is easier to follow and maintain. This update adds helper functions to check whether the wordlist has loaded or if something went wrong. The public API is locked to prevent accidental modification, and the library behaves more safely if used before loading finishes.
144+
145+
v2.0.0 -- CensorCore v2.0.0 is a major upgrade that introduces phrase detection, automatic severity levels, async lifecycle events, a detailed analyze() API, and custom rule support. The internal rule engine has been redesigned for clarity and flexibility while remaining fully backward‑compatible with the original isBlocked() function.
162146

163147
License
164-
-------
165148

166149
This project is released under the MIT License.

0 commit comments

Comments
 (0)