Skip to main content

API Reference

Programmatic usage of OmniScript Format

omniscript-parser

Zero-dependency TypeScript parser for converting OSF text to Abstract Syntax Tree (AST) and back.

Installation

npm install omniscript-parser

Usage

import { parse, serialize } from 'omniscript-parser';

// Parse OSF to AST
const osfCode = `
@meta { title: "My Document"; }
@doc {
  # Hello World
}
`;

const ast = parse(osfCode);
console.log(ast);
// Output: { blocks: [...] }

// Serialize AST back to OSF
const osfOutput = serialize(ast);
console.log(osfOutput);

API

parse(osfCode: string, options?: ParseOptions): OSFDocument

Parses OSF text into an Abstract Syntax Tree (AST).

Parameters: osfCode - String containing OSF content; options - Include resolution settings

Returns: OSFDocument object with blocks array (and includes when present)

Throws: Error if syntax is invalid

serialize(ast: OSFDocument): string

Converts an AST back to OSF text format.

Parameters: ast - OSFDocument object

Returns: String containing formatted OSF code

Types

interface OSFDocument {
  version?: string;
  blocks: OSFBlock[];
  includes?: IncludeDirective[];
}

type OSFValue = string | number | boolean | OSFValue[] | { [key: string]: OSFValue };

type OSFBlock =
  | MetaBlock
  | DocBlock
  | SlideBlock
  | SheetBlock
  | ChartBlock
  | DiagramBlock
  | OSFCodeBlock
  | TableBlock;

interface MetaBlock {
  type: 'meta';
  props: Record<string, OSFValue>;
}

interface ChartBlock {
  type: 'chart';
  chartType: 'bar' | 'line' | 'pie' | 'scatter' | 'area';
  title: string;
  data: ChartDataSeries[];
  options?: ChartOptions;
}

interface TableBlock {
  type: 'table';
  caption?: string;
  style?: 'bordered' | 'striped' | 'minimal';
  alignment?: ('left' | 'center' | 'right')[];
  headers: string[];
  rows: { cells: { text: string }[] }[];
}

interface IncludeDirective {
  type: 'include';
  path: string;
  resolved?: OSFDocument;
}

omniscript-converters

Professional document converters for exporting OSF to PDF, DOCX, PPTX, and XLSX.

Installation

npm install omniscript-parser omniscript-converters

Usage - PDF

import { parse } from 'omniscript-parser';
import { PDFConverter } from 'omniscript-converters';

const osfCode = `@meta { title: "My Document"; }`;
const ast = parse(osfCode);

const converter = new PDFConverter();
const result = await converter.convert(ast, { theme: 'Corporate' });

// Write to file
import fs from 'fs';
fs.writeFileSync('output.pdf', result.buffer);

Usage - DOCX

import { DOCXConverter } from 'omniscript-converters';

const converter = new DOCXConverter();
const result = await converter.convert(ast);

fs.writeFileSync('output.docx', result.buffer);

Usage - PPTX

import { PPTXConverter } from 'omniscript-converters';

const converter = new PPTXConverter();
const result = await converter.convert(ast, { theme: 'Modern' });

fs.writeFileSync('output.pptx', result.buffer);

Usage - XLSX

import { XLSXConverter } from 'omniscript-converters';

const converter = new XLSXConverter();
const result = await converter.convert(ast);

fs.writeFileSync('output.xlsx', result.buffer);

Converter Options

interface ConverterOptions {
  theme?: string;           // Theme name (default: 'default')
  pageSize?: 'A4' | 'Letter';
  orientation?: 'portrait' | 'landscape';
  fontSize?: number;
  fontFamily?: string;
  timeoutMs?: number;       // PDF rendering timeout (ms)
  puppeteerArgs?: string[]; // Custom Puppeteer launch args
}

Themes

Available themes: default, Corporate, Modern,Minimal, Academic, Dark, Light

omniscript-cli

Command-line interface for parsing, validating, and converting OSF files.

Installation

npm install -g omniscript-cli

Commands

osf parse <file>

Parse and validate an OSF file, output AST as JSON.

osf parse document.osf

osf render <file> --format <type>

Convert OSF to specified format (pdf, docx, pptx, xlsx, html).

osf render doc.osf --format pdf --output output.pdf
osf render doc.osf --format docx --theme Corporate

osf lint <file>

Check OSF file for syntax errors and best practice violations.

osf lint document.osf

osf export <file> --target <type>

Export OSF to another text format (md, json).

osf export doc.osf --target md --output README.md

Complete Example

// File: generate-report.ts
import { parse, serialize } from 'omniscript-parser';
import { PDFConverter, DOCXConverter } from 'omniscript-converters';
import fs from 'fs';

async function generateReport() {
  // Create OSF content
  const osfCode = `
@meta {
  title: "Q4 Business Report";
  author: "Finance Team";
  date: "2025-10-15";
  theme: "Corporate";
}

@doc {
  content: "# Executive Summary
  
  Revenue grew **25%** this quarter.
  ";
}

@chart {
  type: "bar";
  title: "Revenue by Quarter";
  data: [
    { label: "Q1"; values: [100]; },
    { label: "Q2"; values: [120]; },
    { label: "Q3"; values: [140]; },
    { label: "Q4"; values: [175]; }
  ];
}
  `;

  // Parse to AST
  const ast = parse(osfCode);
  
  // Generate PDF
  const pdfConverter = new PDFConverter();
  const pdfResult = await pdfConverter.convert(ast);
  fs.writeFileSync('report.pdf', pdfResult.buffer);
  
  // Generate DOCX
  const docxConverter = new DOCXConverter();
  const docxResult = await docxConverter.convert(ast);
  fs.writeFileSync('report.docx', docxResult.buffer);
  
  console.log('✅ Generated report.pdf and report.docx');
}

generateReport();
← User GuideView on GitHub →