Ever wonder what your favorite books look like without words?
Punc is a modern TypeScript library for analyzing punctuation patterns in text files. It extracts punctuation marks, counts their frequency, calculates words per sentence, and can generate PDF visualizations showing only the punctuation.
- 🔍 Punctuation Analysis: Extract and count punctuation marks from text files
- 📊 Statistical Analysis: Calculate words-per-sentence averages
- 📄 PDF Generation: Create visual PDFs showing only punctuation patterns
- 🎯 TypeScript Support: Full type safety and IntelliSense support
- 🚀 Modern ES Modules: Built with latest JavaScript standards
- ✅ Comprehensive Testing: 100% test coverage with Jest
- 🔧 Developer Experience: ESLint, Prettier, and automated CI/CD
npm install puncimport punc, { createPDF } from 'punc';
// Analyze punctuation in a text file
const result = await punc('path/to/your/file.txt');
console.log('Punctuation counts:', result.count);
console.log('Punctuation only:', result.body);
console.log('Words per sentence:', result.wordsPerSentence);
console.log('Spaced text:', result.spaced);
// Generate a PDF visualization
const pdfResult = await createPDF('path/to/your/file.txt');
console.log('PDF created:', pdfResult.pathToFile);Analyzes punctuation in a text file and returns detailed statistics.
Parameters:
filePath(string): Path to the text file to analyzeoptions(PuncOptions | string, optional): Configuration options
Returns: Promise<PuncResult>
Example:
const result = await punc('alice.txt', {
encoding: 'utf8',
mapping: {
';': 0, ':': 0, "'": 0, '"': 0, ',': 0,
'!': 0, '?': 0, '.': 0, '(': 0, ')': 0, '-': 0
}
});Creates a PDF visualization showing only punctuation marks.
Parameters:
filePath(string): Path to the text fileoptions(PuncOptions | string, optional): Configuration options
Returns: Promise<PDFResult>
Example:
const pdfResult = await createPDF('alice.txt');
console.log('PDF saved to:', pdfResult.pathToFile);interface PunctuationCount {
';': number;
':': number;
"'": number;
'"': number;
',': number;
'!': number;
'?': number;
'.': number;
'(': number;
')': number;
'-': number;
}
interface PuncResult {
body: string; // Punctuation marks only
count: PunctuationCount; // Count of each punctuation mark
wordsPerSentence: number; // Average words per sentence
spaced: string; // Text with words replaced by spaces
}
interface PDFResult {
success: boolean;
pathToFile: string;
}- Node.js 18+
- npm
git clone https://github.com/JoeKarlsson/punc.git
cd punc
npm installnpm run build # Build the project (TypeScript + ESBuild)
npm run dev # Watch mode for development
npm test # Run tests with Jest
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run lint # Run ESLint code quality checks
npm run lint:fix # Fix ESLint issues automatically
npm run format # Format code with Prettier
npm run type-check # Check TypeScript types without emitting files
npm run markdown-lint # Check and fix markdown formatting
npm run check # Run all checks (type-check + lint + markdown-lint + test)
npm run clean # Clean build artifacts# Run all tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watchThe library tracks these punctuation marks:
;- Semicolon:- Colon'- Single quote"- Double quote,- Comma!- Exclamation mark?- Question mark.- Period(- Opening parenthesis)- Closing parenthesis-- Hyphen/dash
This project was inspired by this article on Medium, which was in turn inspired by this person's work.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.