Ozone (o3) JavaScript Class Framework

Common errors

• TypeError: Object.create is not a function

  cause The JavaScript environment is not fully ES5 compatible and lacks the `Object.create` method, which `o3` relies on heavily for inheritance.
  fix Upgrade your JavaScript engine or ensure polyfills for ES5 features are loaded before initializing `o3`. However, the framework is not recommended for environments requiring extensive polyfilling.

• TypeError: Cannot read properties of undefined (reading 'Class')

  cause The `o3` module was not successfully required or imported, meaning the `o3` object is `undefined` when attempting to access `o3.Class`.
  fix Verify that `require('o3')` is correctly resolving the package. Check your `node_modules` directory and ensure the package is installed. If using a bundler, confirm its configuration allows CommonJS imports.

• TypeError: (0 , _o3.Class) is not a function

  cause Attempting to use ES Modules `import { Class } from 'o3';` syntax with `o3`, which is primarily a CommonJS module and does not expose `Class` via named ESM exports.
  fix Use CommonJS `require` syntax: `const { Class } = require('o3');` or `const o3 = require('o3'); const Class = o3.Class;`.

Warnings

• breaking The `o3` framework is strictly designed for ES5 compatible environments. It will not function correctly in older JavaScript engines (e.g., IE8 or below) lacking `Object.create` or full ES5 property enumeration support.
  Fix: Ensure your target environment supports ECMAScript 5. This framework is not suitable for pre-ES5 environments.
• deprecated The `o3` package is no longer actively maintained, with its last publish occurring over five years ago. Users should consider alternatives like native ES6+ classes or modern transpilers (e.g., Babel, TypeScript) which provide robust and actively supported class functionalities.
  Fix: For new projects, prefer native ES6+ class syntax. For existing projects, evaluate migration to modern patterns or be aware of potential security and compatibility issues due to lack of maintenance.
• gotcha The framework explicitly does not support Opera due to issues with its Karma test launcher at the time of development. While it might function, official compatibility is not guaranteed.
  Fix: Avoid using o3 in applications where Opera browser compatibility is a critical requirement.
• gotcha When inheriting from native classes like `Error`, special care must be taken with the constructor and `Error.captureStackTrace` to ensure correct stack trace capturing and `this` context binding.
  Fix: Always include `Error.captureStackTrace(this, this.constructor);` in custom Error class constructors when extending `Error` to preserve correct stack information. Ensure `this` context is correctly bound when calling super constructors via `call` or `apply`.

Install

• npm install o3 npm
• yarn add o3 yarn
• pnpm add o3 pnpm

Imports

• o3
  wrong:

  import o3 from 'o3';

  correct:

  const o3 = require("o3");

  The primary way to import the entire o3 module in CommonJS environments, which is its intended use case.
• Class
  wrong:

  const Class = require("o3");

  correct:

  const { Class } = require("o3");

  The `Class` constructor is a named export (or property of the main module object) within `o3`. Directly requiring `o3` gives you the main object, from which `Class` can be destructured or accessed as `o3.Class`.
• Class
  wrong:

  import { Class } from 'o3';

  correct:

  const Class = o3.Class; // after const o3 = require('o3');

  As an ES5-focused library primarily designed for CommonJS, ESM `import` syntax is not supported and will fail to resolve the module or its exports.

Quickstart

Demonstrates defining a base class and an inheriting class using o3's `Class` and `extend` methods, showcasing object instantiation and method calls.

const o3 = require("o3");
const Class = o3.Class;

// Define a base class inheriting from Object
const BasePerson = Class(Object, {
    prototype: {
        // Constructor function
        constructor: function BasePerson(name) {
            this.name = name;
        },
        // A method
        sayHello: function() {
            console.log(`Hello, my name is ${this.name}.`);
        }
    }
});

// Define a derived class using the inherited extend method
const Employee = BasePerson.extend({
    prototype: {
        constructor: function Employee(name, position) {
            // Call the super constructor
            BasePerson.prototype.constructor.call(this, name);
            this.position = position;
        },
        // Override or add new methods
        sayHello: function() {
            console.log(`Hello, I'm ${this.name} and I'm a ${this.position}.`);
        },
        work: function() {
            console.log(`${this.name} is working.`);
        }
    }
});

const person = new BasePerson("Alice");
person.sayHello();

const employee = new Employee("Bob", "Software Engineer");
employee.sayHello();
employee.work();