Home

Oriented-Direct (.osp) — Official Language Specification & Technical Manual (v1.3.0)

Oriented-Direct is a modern, high-performance, unambiguous programming language that transpiles directly into clean, standard ECMAScript (ES Modules) with zero external runtime dependencies.

Designed from first principles for browser and Node.js environments, Oriented-Direct eliminates historic JavaScript verbosity, replaces legacy DOM APIs with native compile-time directives, enforces immutability by default, guarantees strict equality, and provides a built-in zero-configuration multi-module bundler and local development server (ospc dev).

---

1. Core Architecture and Design Philosophy

JavaScript was conceived in 1995 as a lightweight browser scripting language. Over three decades, web development accumulated complex layers of external abstractions (frameworks, virtual DOM engines, transpilers, and package managers) to mitigate language deficiencies.

Oriented-Direct resolves these architectural challenges directly at the language level:

1. DOM as a First-Class Citizen: Native @ directives eliminate the verbosity of document.querySelector and event listener boilerplate.
2. Immutability by Default: Variables declared with val are immutable constants; mutable state requires explicit mut.
3. Strict Equality Guarantee: Comparison operators (is, is not, ==, !=) compile exclusively to strict identity checks (=== and !==). Loose type coercion bugs are eliminated.
4. Linear Data Pipelines: The pipeline operator (|>) allows clean, readable, left-to-right functional data transformations.
5. Zero-Dependency Project Ecosystem: The compiler (ospc) contains a built-in module resolver, multi-module bundler, and development server, removing the requirement for Webpack, Vite, or Babel.

---

2. Compiler Installation and CLI Reference

The compiler binary is ospc (or oriented-direct).

CLI Command Matrix

Command	Description
ospc dev [port]	Compiles the project, copies declared assets, and launches an HTTP development server with automatic file-watching recompilation (default port: 3000).
ospc serve [port]	Alias for ospc dev.
ospc build [entry.osp]	Compiles and bundles the project according to package.json or CLI flags.
ospc build --public	Bundles code into public/app.js and copies static assets (index.html, styles.css) into public/.
ospc compile <file.osp>	Transpiles a single .osp file to an equivalent .js file.
ospc run <file.osp>	Transpiles/bundles the target file and immediately executes it using Node.js.
ospc watch [entry.osp]	Monitors the file tree and recompiles automatically upon filesystem modifications.
ospc --help / ospc -v	Displays usage instructions or compiler version details.

---

3. Project Configuration (package.json / osp.json)

Oriented-Direct projects are configured declaratively in package.json under the "osp" property or inside a dedicated osp.json file.

{
  "name": "my-oriented-direct-app",
  "version": "1.3.0",
  "type": "module",
  "scripts": {
    "dev": "ospc dev",
    "build": "ospc build --public",
    "watch": "ospc watch --public"
  },
  "osp": {
    "entry": "src/main.osp",
    "outDir": "public",
    "outFile": "app.js",
    "bundle": true,
    "format": "esm",
    "port": 3000,
    "minify": false,
    "assets": [
      "index.html",
      "styles.css",
      "assets/"
    ]
  }
}

Standard Project Layout

my-project/
├── package.json           # Build, bundler, and server configuration
├── index.html             # Source HTML5 interface
├── styles.css             # Source styles
├── src/                   # 100% Oriented-Direct source code
│   ├── main.osp           # Application entry point
│   ├── utils/             # Helper utilities and shared functions
│   └── modules/           # Domain-specific components
└── public/                # Self-contained production distribution directory
    ├── index.html         # Asset copied automatically by compiler
    ├── styles.css         # Asset copied automatically by compiler
    └── app.js             # Monolithic bundled JavaScript output

---

4. Language Grammar and Syntax Reference

4.1 Variable Declarations

Oriented-Direct prohibits let, const, and var.

val maximumDepth = 450;    // Immutable constant (compiles to const)
mut currentHeartRate = 110; // Reassignable variable (compiles to let)

currentHeartRate = 45;

---

4.2 Logical Operators and Comparisons

All comparisons compile to strict JavaScript operators.

Operation	Oriented-Direct Syntax	Compiled JavaScript
Strict Equality	a is b or a == b	a === b
Strict Inequality	a is not b or a != b	a !== b
Logical Conjunction	a and b	a && b
Logical Disjunction	a or b	a || b
Logical Negation	not a	!a
Nullish Coalescing	a ?? b	a ?? b

if (currentHeartRate < 20 and not isSurfaceBreathing) {
  @info("Deep bradycardia active");
}

---

4.3 Control Flow and Pattern Matching

Conditionals

if (depth > 200) {
  @log("Mesopelagic zone");
} else {
  @log("Epipelagic zone");
}

// Inverted conditional (executes when condition is falsy)
unless (isInitialized) {
  initializeSubsystems();
}

Pattern Matching (match)

val label = match (statusCode) {
  case 200 => "Operation Successful"
  case 404 => "Resource Not Found"
  case 500 => "Internal System Fault"
  default => "Unrecognized Status"
};

---

4.4 Iteration Constructs

Oriented-Direct provides four optimized looping paradigms:

// 1. C-Style 3-Part Loop (Use 'mut' for mutable iteration counters)
for (mut i = 0; i < buffer.length; i += 4) {
  processBufferChunk(i);
}

// 2. Numeric Range Loop
for (val step in 0..100 step 10) {
  @log("Progress checkpoint:", step);
}

// 3. Iterable / Array Collection Loop
for (val item in itemArray) {
  renderItem(item);
}

// 4. Object Key Enumeration Loop
for (val key of configurationObject) {
  @log(key, configurationObject[key]);
}

---

4.5 Sealed Structs and Classes

struct (Sealed Data Model)

Defining a struct automatically generates a class constructor fortified with Object.seal(this). This guarantees memory integrity and prevents accidental property additions at runtime.

struct TelemetryRecord { specimenId, latitude, longitude, depthMeters }

val record = new TelemetryRecord("HS-409", 47.5, -61.8, 382.4);

class (Stateful Components)

class AcousticSynthesizer {
  constructor(sampleRate) {
    this.sampleRate = sampleRate;
    this.audioContext = null;
  }

  start() {
    this.audioContext = new (@win.AudioContext || @win.webkitAudioContext)();
  }
}

---

4.6 Pipeline Operator (|>)

The pipeline operator passes the result of the left-hand expression as the first argument to the right-hand function.

val normalizedString = rawInput |> trimText |> toLowerCase |> sanitize;

---

5. Directives Reference (@ Macro System)

Directives provide zero-cost abstractions over the DOM, browser window, and console subsystems.

5.1 DOM Querying and Manipulation

Directive	Signature	Description
@doc	@doc	Points safely to the global document object.
@win	@win	Points safely to the global window object.
@find	@find(selector, parent?)	Executes parent.querySelector(selector). Safe against null parents.
@all	@all(selector, parent?)	Executes Array.from(parent.querySelectorAll(selector)).
@id	@id(idString)	Fast lookup via document.getElementById(idString).
@text	@text(el, content?)	Getter/setter for el.textContent.
@html	@html(el, content?)	Getter/setter for el.innerHTML.
@val	@val(el, value?)	Getter/setter for form element value (el.value).
@attr	@attr(el, name, value?)	Getter/setter for element attributes.
@css	@css(el, { key: val })	Applies inline styles via Object.assign(el.style, { ... }).
@create	@create(tag, attrs, ...children)	Declaratively constructs DOM elements with properties, inline styles, and child nodes.

5.2 Event Management

Directive	Signature	Description
@on	@on(target, event, handler, opts?)	Attaches an event listener (addEventListener). Returns the target.
@off	@off(target, event, handler, opts?)	Detaches an event listener (removeEventListener).
@emit	@emit(target, event, detailObj)	Dispatches a CustomEvent with { detail: detailObj, bubbles: true }.

5.3 Diagnostics and Console Directives

Directive	Compiled Equivalent
@log(...)	console.log(...)
@info(...)	console.info(...)
@warn(...)	console.warn(...)
@error(...)	console.error(...)

---

6. Multi-Module Development: Rules and Best Practices

Oriented-Direct v1.3.0 supports modular code splitting with import and export.

6.1 Function Hoisting and Export Guidelines

When bundling modules, the compiler wraps each module inside an isolated scope. In JavaScript, const and class variables exist within the Temporal Dead Zone (TDZ) before their declaration lines. Function declarations (function) are hoisted.

Recommended Practice

Always export utility and lifecycle routines using export fn:

// File: src/utils/formatters.osp
export fn formatPercentage(value) {
  return value + "%";
}

export fn formatPressure(atm) {
  return atm.toFixed(1) + " ATM";
}

Importing Modules

// File: src/main.osp
import { formatPercentage, formatPressure } from "./utils/formatters.osp";

val formatted = formatPercentage(98.5);

Critical Rule: Always include the .osp file extension in the import specifier path (from "./utils/formatters.osp").

---

7. Advanced Integration Patterns

7.1 WebGL and Hardware-Accelerated 3D Graphics (Three.js)

Oriented-Direct interfaces directly with WebGL contexts and 3D graphics libraries without requiring external type packages or runtime wrappers.

import { setupLighting } from "./observatory/lighting.osp";
import { buildEnvironment } from "./observatory/environment.osp";

export fn init3DHabitat() {
  val container = @id("webglViewport");
  unless (container) return;

  val THREE = @win.THREE;
  val scene = new THREE.Scene();
  val camera = new THREE.PerspectiveCamera(45, container.clientWidth / container.clientHeight, 0.1, 1000);
  val renderer = new THREE.WebGLRenderer({ antialias: true });

  renderer.setSize(container.clientWidth, container.clientHeight);
  container.appendChild(renderer.domElement);

  setupLighting(scene, THREE);
  buildEnvironment(scene, THREE);

  fn renderLoop() {
    requestAnimationFrame(renderLoop);
    renderer.render(scene, camera);
  }
  renderLoop();
}

7.2 Web Audio API and Real-Time Signal Synthesis

export fn synthesizePulse(frequencyHz, durationSeconds) {
  val AudioContextClass = @win.AudioContext || @win.webkitAudioContext;
  unless (AudioContextClass) return;

  val ctx = new AudioContextClass();
  val osc = ctx.createOscillator();
  val gain = ctx.createGain();

  osc.type = "sine";
  osc.frequency.setValueAtTime(frequencyHz, ctx.currentTime);

  gain.gain.setValueAtTime(0.01, ctx.currentTime);
  gain.gain.linearRampToValueAtTime(0.3, ctx.currentTime + 0.05);
  gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + durationSeconds);

  osc.connect(gain);
  gain.connect(ctx.destination);

  osc.start();
  osc.stop(ctx.currentTime + durationSeconds + 0.05);
}

---

8. Anti-Patterns and Troubleshooting Guide

1. Using JavaScript Logical Operators

• Incorrect: if (isValid && !hasError)
• Correct: if (isValid and not hasError)

2. Using val in Mutable C-Style Loop Counters

• Incorrect: for (val i = 0; i < count; i++) (Triggers constant mutation error)
• Correct: for (mut i = 0; i < count; i++)

3. Emitting let, const, or var

• Incorrect: let status = "ready";
• Correct: mut status = "ready";

4. Arrow Variable Exports Causing TDZ Errors in Bundled IIFEs

• Incorrect: export val calculateMass = (vol) => vol * 1.025;
• Correct: export fn calculateMass(vol) { return vol * 1.025; }

5. Compiling Output Directly to Project Root

• Incorrect: Manually transpiling single files to root app.js.
• Correct: Configure package.json with "outDir": "public" and execute ospc build --public or ospc dev.

---

9. Performance Metrics

Compared to equivalent TypeScript / JavaScript enterprise configurations:

• Token Density: ~45% to 50% fewer source tokens required to express complex DOM, event, and state pipelines.
• Runtime Footprint: Zero runtime framework overhead (~1 KB micro-helper injection).
• Cold-Start Build Time: Instantaneous compilation and bundling via built-in Node.js compiler engine without dependency graphs in node_modules.