`

$3

`html











`

📖 API Reference

$3

Registers the JSONata language with Monaco Editor.

Parameters:

- monaco - The Monaco editor instance
- options (optional) - Configuration options

Options:

`typescript
interface JSONataLanguageOptions {
enableDiagnostics?: boolean; // Enable real-time error checking (default: true)
enableCompletion?: boolean; // Enable autocomplete (default: true)
enableHover?: boolean; // Enable hover tooltips (default: true)
enableSignatureHelp?: boolean; // Enable parameter hints (default: true)
enableFormatting?: boolean; // Enable code formatting (default: true)
}
`

Example:

`typescript
import { registerJsonataLanguage } from 'monaco-jsonata';

const disposable = registerJsonataLanguage(monaco, {
enableDiagnostics: true,
enableCompletion: true,
enableHover: true,
enableSignatureHelp: true,
enableFormatting: true
});

// Later, to clean up:
disposable.dispose();
`

$3

Registers editor actions for the JSONata language, such as format commands in the context menu.

Parameters:

- monaco - The Monaco editor instance
- editor - The standalone code editor instance
- formatFunction (optional) - A formatter function (e.g., formatJsonata from @stedi/prettier-plugin-jsonata)

Formatter Function Type:

`typescript
type FormatJsonataFunction = (
code: string,
options?: {
printWidth?: number;
tabWidth?: number;
useTabs?: boolean;
}
) => string | Promise;
`

Example:

`typescript
import { registerJsonataActions } from 'monaco-jsonata';
import { formatJsonata } from '@stedi/prettier-plugin-jsonata/dist/lib';

// With formatter (adds "Format JSONata" to context menu)
const disposable = registerJsonataActions(monaco, editor, formatJsonata);

// Without formatter (no format action)
const disposable = registerJsonataActions(monaco, editor);

// Later, to clean up:
disposable.dispose();
`

Features Added:
- Right-click context menu: "Format JSONata" option
- Keyboard shortcut: Cmd+Shift+F (Mac) / Ctrl+Shift+F (Windows/Linux)

🎨 Features in Detail

$3

Advanced Monarch tokenizer with support for:

- JSONata function names ($sum, $map, etc.)
- Operators (~>, :=, .., etc.)
- Keywords (function, lambda, if, then, else, etc.)
- String literals (single, double, and backtick quotes)
- Regular expressions
- Numbers (including scientific notation, hex, octal, binary)
- Comments (line and block)

$3

Intelligent code completion featuring:

- All ~70 JSONata built-in functions with descriptions
- Function signatures as snippets with placeholders
- Examples in documentation
- Keyword suggestions (if, then, else, and, or, etc.)
- Common patterns (map, filter, reduce templates)
- Variable suggestions ($, $$, $v, $i, etc.)

Trigger autocomplete:
- Type $ to see all functions
- Press Ctrl+Space anywhere for context-aware suggestions

$3

Rich hover tooltips showing:

- Function signature
- Description
- Parameter details with types
- Return type
- Code examples
- Links to official JSONata documentation

Try it: Hover over any $function name

$3

Parameter hints while typing function calls:

- Shows function signature
- Highlights current parameter
- Displays parameter types and descriptions

Try it: Type $map( or $reduce( to see parameter hints

$3

Automatic error detection using the JSONata parser:

- Syntax errors highlighted in red
- Parse errors with helpful messages
- Suggestions for common mistakes
- Updates as you type (with debouncing)

$3

Pretty-print JSONata expressions:

- Smart indentation
- Proper spacing around operators
- Object and array formatting
- Preserves comments

Keyboard shortcut: Shift+Alt+F (or Shift+Option+F on Mac)

Programmatic:
`typescript
editor.getAction('editor.action.formatDocument').run();
`

Context Menu & Custom Keyboard Shortcut:

You can add a "Format JSONata" action to the right-click context menu with a custom keyboard shortcut:

`typescript
import { registerJsonataLanguage, registerJsonataActions } from 'monaco-jsonata';
import { formatJsonata } from '@stedi/prettier-plugin-jsonata/dist/lib';
import type * as Monaco from 'monaco-editor';

function setupEditor(monaco: typeof Monaco) {
// Register the language
registerJsonataLanguage(monaco);

// Create the editor
const editor = monaco.editor.create(container, {
value: '',
language: 'jsonata',
theme: 'jsonata-theme'
});

// Register editor actions (adds "Format JSONata" to context menu)
// Keyboard shortcut: Cmd+Shift+F (Mac) or Ctrl+Shift+F (Windows/Linux)
registerJsonataActions(monaco, editor, formatJsonata);

return editor;
}
`

This adds:
- Right-click context menu: "Format JSONata" option
- Keyboard shortcut: Cmd+Shift+F (Mac) / Ctrl+Shift+F (Windows/Linux)

The formatter function is optional. If you don't need formatting via context menu, you can omit it:

`typescript
registerJsonataActions(monaco, editor); // No formatter - skips format action
`

$3

Custom jsonata-theme optimized for JSONata syntax:

- Distinct colors for functions, keywords, operators
- Good contrast for readability
- Based on VS Code Dark+ theme

📚 JSONata Functions Coverage

This extension includes complete documentation for all JSONata built-in functions:

String Functions: $string, $length, $substring, $substringBefore, $substringAfter, $uppercase, $lowercase, $trim, $pad, $contains, $split, $join, $match, $replace, $eval, $base64encode, $base64decode, $encodeUrlComponent, $encodeUrl, $decodeUrlComponent, $decodeUrl

Numeric Functions: $number, $abs, $floor, $ceil, $round, $power, $sqrt, $random, $formatNumber, $formatBase, $formatInteger, $parseInteger

Aggregation Functions: $sum, $max, $min, $average

Boolean Functions: $boolean, $not, $exists

Array Functions: $count, $append, $sort, $reverse, $shuffle, $distinct, $zip

Object Functions: $keys, $lookup, $spread, $merge, $sift, $each, $error, $assert, $type

Higher-Order Functions: $map, $filter, $reduce, $singletonArray

Date/Time Functions: $now, $millis, $fromMillis, $toMillis

🔧 Advanced Usage

$3

`typescript
import { registerJsonataLanguage } from 'monaco-jsonata';
import * as monaco from 'monaco-editor';

registerJsonataLanguage(monaco);

const editor = monaco.editor.create(container, {
value: '',
language: 'jsonata',
theme: 'jsonata-theme',
// Monaco options
minimap: { enabled: false },
fontSize: 14,
lineNumbers: 'on',
scrollBeyondLastLine: false,
automaticLayout: true,
// Enable all features
quickSuggestions: {
other: true,
comments: false,
strings: false
},
suggestOnTriggerCharacters: true,
acceptSuggestionOnCommitCharacter: true,
acceptSuggestionOnEnter: 'on',
parameterHints: {
enabled: true
}
});
`

$3

For advanced use cases, you can import and use individual components:

`typescript
import {
createCompletionProvider,
createHoverProvider,
createSignatureHelpProvider,
createFormattingProvider,
setupDiagnostics,
jsonataFunctions,
jsonataTokensProvider
} from 'monaco-jsonata';

// Use individual providers
monaco.languages.registerCompletionItemProvider('jsonata', createCompletionProvider(monaco));
monaco.languages.registerHoverProvider('jsonata', createHoverProvider(monaco));
// ... etc
`

$3

`typescript
import { jsonataFunctions, jsonataFunctionMap } from 'monaco-jsonata';

// Get all functions
console.log(jsonataFunctions); // Array of all functions

// Lookup specific function
const sumFunc = jsonataFunctionMap.get('$sum');
console.log(sumFunc.signature); // "$sum(array)"
console.log(sumFunc.description); // "Returns the sum of all numbers in array"
console.log(sumFunc.params); // Parameter details
`

📝 Examples

See the examples directory for complete integration examples:

- React: react-example.tsx
- SvelteKit: sveltekit-example.svelte
- Vanilla JS: vanilla-js-example.html

🌐 Browser Compatibility

Works in all modern browsers that support Monaco Editor:

- Chrome/Edge 90+
- Firefox 88+
- Safari 14+

🔷 TypeScript Support

This package includes full TypeScript definitions. No need for @types/* packages.

`typescript
import type { JSONataFunction, JSONataLanguageOptions } from 'monaco-jsonata';
`

🛠️ Development

`bash


Install dependencies

npm install

Build library

npm run build:lib

Run demo application

npm run dev

Lint

npm run lint
`

📁 Project Structure

`
monaco-jsonata/
├── src/
│ ├── index.ts # Main export
│ ├── jsonata-language.ts # Language registration
│ ├── jsonata-functions.ts # Function definitions (~70 functions)
│ ├── tokenizer.ts # Monarch tokenizer
│ ├── completions.ts # Autocomplete provider
│ ├── hovers.ts # Hover provider
│ ├── signatures.ts # Signature help provider
│ ├── diagnostics.ts # Error checking
│ └── formatter.ts # Code formatter
├── examples/ # Integration examples
├── dist/ # Built library (generated)
└── package.json
``

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🙏 Acknowledgments

- JSONata - The JSONata query and transformation language
- Monaco Editor - The code editor that powers VS Code
- @stedi/prettier-plugin-jsonata - JSONata formatting inspiration

🔗 Related Projects

- jsonata - JSONata query and transformation library
- monaco-editor - Monaco Editor
- @monaco-editor/react - Monaco Editor React wrapper

---

Made with ❤️ for the JSONata community