TSON (TypeScript Object Notation) is a powerful configuration format that extends JSON with TypeScript-like features. Think of it as JSON's more flexible cousin that actually understands how developers work.
Ever been frustrated by JSON's limitations? No comments, no trailing commas, no variables? TSON solves these pain points while maintaining the simplicity and ubiquity of JSON.
// This is valid TSON! 🎉
const API_VERSION = "v2";
const BASE_URL = "https://api.example.com";
{
// Comments are supported!
name: "My Awesome App",
version: API_VERSION,
api: {
baseUrl: BASE_URL,
timeout: 5000,
endpoints: [
"/users",
"/posts",
"/comments", // Trailing commas work too!
]
}
}
- 💬 Comments: Single-line (
//) and block comments (/* */) - 🔗 Variables: Const declarations for reusable values
- 📦 Imports: Import other TSON files for modular configurations
- 🎯 Trailing Commas: No more syntax errors from extra commas
- 🏗️ Compilation: Compile TSON to JSON for production
- 👀 File Watching: Auto-compile on file changes
- 🚨 Error Handling: Detailed error messages with line numbers
- ⚡ CLI Tool: Command-line interface for easy integration
- 🔧 TypeScript: Full TypeScript support with type definitions
npm install @mikofure/tson
Or with other package managers:
yarn add @mikofure/tson
bun add @mikofure/tson
pnpm add @mikofure/tsonimport { parseTSON } from 'tson';
// Parse a TSON file
const config = parseTSON('./config.tson');
console.log(config);
// Parse TSON string directly
import { parseTSONString } from 'tson';
const tsonContent = `
const PORT = 3000;
{
server: {
port: PORT,
host: "localhost"
}
}
`;
const result = parseTSONString(tsonContent);
// Output: { server: { port: 3000, host: "localhost" } }Create modular configurations by importing other TSON files:
database.tson
// Database configuration
{
host: "localhost",
port: 5432,
database: "myapp",
ssl: false
}
app.tson
// Main application config
import dbConfig from "./database.tson";
const APP_NAME = "My Application";
{
name: APP_NAME,
version: "1.0.0",
database: dbConfig,
features: {
auth: true,
logging: true
}
}
Compile TSON files to JSON for production use:
import { compileTSONToJSON } from 'tson';
// Compile single file
const outputPath = compileTSONToJSON('./config.tson', {
outputDir: './dist',
minify: true,
preserveComments: true
});
// Compile multiple files
import { compileTSONFiles } from 'tson';
const outputPaths = compileTSONFiles([
'./config/app.tson',
'./config/database.tson'
], {
outputDir: './dist/config',
minify: false
});Auto-compile TSON files when they change:
import { watchTSONFile } from 'tson';
// Watch and auto-compile
const stopWatching = watchTSONFile('./config.tson', {
outputDir: './dist',
minify: true
});
// Stop watching when done
// stopWatching();TSON comes with a powerful command-line tool:
# Parse and validate a TSON file
tson-cli config.tson
# Validate only (no output)
tson-cli config.tson --validate
# Format and prettify output
tson-cli config.tson --format
# Save output to file
tson-cli config.tson --output config.json
# Strict mode (throw on errors)
tson-cli config.tson --strict
# Disable specific features
tson-cli config.tson --no-comments --no-const| Option | Description |
|---|---|
--strict |
Throw errors instead of returning null |
--validate |
Only validate the file, don't parse |
--format |
Format and prettify the output |
--output, -o |
Output to file instead of console |
--no-const |
Disable const declaration support |
--no-imports |
Disable import statement support |
--no-comments |
Disable comment support |
--no-trailing-commas |
Disable trailing comma support |
--help, -h |
Show help message |
Parse a TSON file from disk.
interface TSONParseOptions {
allowTrailingCommas?: boolean; // default: true
allowComments?: boolean; // default: true
allowConst?: boolean; // default: true
allowImports?: boolean; // default: true
allowTSONImports?: boolean; // default: true
strict?: boolean; // default: false
baseDir?: string; // default: process.cwd()
}Parse TSON content from a string.
Compile a TSON file to JSON.
interface TSONCompileOptions {
outputDir?: string; // Output directory
minify?: boolean; // Minify JSON output
preserveComments?: boolean; // Save comments to .meta.json
outputExtension?: string; // File extension (default: '.json')
}Validate a TSON file without parsing.
Convert a JavaScript object to TSON format.
TSON provides detailed error information:
import { TSONParseError, isTSONParseError } from 'tson';
try {
const config = parseTSON('./config.tson', { strict: true });
} catch (error) {
if (isTSONParseError(error)) {
console.error(`Parse error in ${error.filePath}:${error.line}:${error.column}`);
console.error(error.message);
}
}Perfect for application configuration with environment-specific overrides:
// config/base.tson
const DEFAULT_TIMEOUT = 5000;
{
api: {
timeout: DEFAULT_TIMEOUT,
retries: 3
},
logging: {
level: "info"
}
}
// config/development.tson
import baseConfig from "./base.tson";
{
...baseConfig,
logging: {
...baseConfig.logging,
level: "debug" // Override for development
},
debug: true
}
Manage complex build setups with reusable components:
// webpack.config.tson
const IS_PRODUCTION = process.env.NODE_ENV === "production";
{
mode: IS_PRODUCTION ? "production" : "development",
devtool: IS_PRODUCTION ? false : "source-map",
optimization: {
minimize: IS_PRODUCTION,
// More webpack config...
}
}
Define API configurations with documentation:
// api-schema.tson
const API_VERSION = "v1";
{
// API endpoint definitions
endpoints: {
users: {
path: `/api/${API_VERSION}/users`,
methods: ["GET", "POST"],
auth: true
},
posts: {
path: `/api/${API_VERSION}/posts`,
methods: ["GET", "POST", "PUT", "DELETE"],
auth: true
}
}
}
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.tson$/,
use: [
{
loader: 'json-loader'
},
{
loader: 'tson-loader' // Custom loader needed
}
]
}
]
}
};// vite.config.ts
import { defineConfig } from 'vite';
export default defineConfig({
assetsInclude: ['**/*.tson'],
// Custom plugin for TSON processing
});// build-config.js
const { compileTSONFiles } = require('tson');
compileTSONFiles(['./config/*.tson'], {
outputDir: './dist/config',
minify: true
});We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Run tests:
npm test - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
# Clone the repository
git clone https://github.com/arizkami/tson.git
cd tson
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Start development mode
npm run devTSON is licensed under the BSD-3-Clause License.
- Inspired by the need for better configuration formats
- Built with TypeScript for type safety
- Designed for developer productivity
Made with ❤️ by Ariz Kamizuki
If you find TSON useful, please consider giving it a ⭐ on GitHub!