@doodad-js/core

Object-oriented programming framework for Javascript.

Latest version is : [![NPM Version][npm-image]][npm-url]

<<<< PLEASE UPGRADE TO THE LATEST VERSION AS OFTEN AS POSSIBLE >>>>

Features

- More Classical OOP
- Inheritance and Composition
- Interfaces (and Mix-ins and Traits)
- Class extenders
- Method and attribute scopes (public, protected and private)
- Base classes and interfaces
- Expandable objects (these objects can be extended like a class)
- Custom events management
- DOM events management
- NodeJs events management
- Exceptions
- Singletons
- Polymorphism
- Static classes
- Useful utility functions
- Namespaces and a registry
- Compatible with most recent browsers (excepted Microsoft Internet Explorer) and Node.Js (6, 7, 8 and 9).
- Compatible with Windows, Linux and MacOS X (and Android).
- Supports browserify and webpack.

Quick Start

$3

Do a normal "require" of the package "@doodad-js/core" in your code, and create your bundle with "browserify" or "webpack".

NOTE: The entry point should automatically be set to "browserify/browserify.min.js".

$3

Download and extract the .zip file from the [latest release][latest-url].

In your HTML file, load JSON5, UUID and the Doodad package :
``html



`

or their debug version :
`html



`

From Javascript, when the scripts are loaded, create the root namespace :
`js
window.createRoot()
.then((root) => {
// Your code there...
})
.catch(err => {
console.error(err);
});
`

You can create a shortcut to the namespaces this way :
`js
const doodad = root.Doodad,
types = doodad.Types,
tools = doodad.Tools,
mixins = doodad.MixIns,
interfaces = doodad.Interfaces,
extenders = doodad.Extenders,
namespaces = doodad.Namespaces,
... ;
`

$3

Download and install Doodad from NPM using the command prompt (Windows) or your favorite shell (Unix/Linux) :
`bash
npm install @doodad-js/core --save
`

By default, Doodad is running in production mode, which disables every validations. You may want to activate the development mode by setting the "NODE_ENV" environment variable :

Windows (command prompt) :
`dos
set NODE_ENV=development
`
Linux/Unix (shell) :
`bash
export NODE_ENV=development
`

Now, in your Node.js script, create the root namespace :
`js
require('@doodad-js/core').createRoot()
.then((root) => {
// Your code there...
})
.catch(err => {
console.error(err);
});
`

You can create a shortcut to the namespaces this way :
`js
const doodad = root.Doodad,
types = doodad.Types,
tools = doodad.Tools,
mixins = doodad.MixIns,
interfaces = doodad.Interfaces,
extenders = doodad.Extenders,
namespaces = doodad.Namespaces,
... ;
`

$3

Doodad must be built using [@doodad-js/make][make-url] and its dependencies.

Scopes

- doodad.PUBLIC: Accessible from the outside.
- doodad.PROTECTED: Accessible from the inside only.
- doodad.PRIVATE: Accessible only from the inside of the prototype. Can't be overriden or replaced.

#### Protection level

First, for the private and the protected scopes to work, Doodad must use Javascript object properties, which have big impacts on performances. That's why they are disabled in production mode.

Also, Doodad allows reflection on every fields and methods to all loaded Doodad modules, but NOT to external scripts.

Last, the efficiency of these scopes depends on an internal flag that remembers in which class instance we are while executing a method. Unfortunatly, __because Javascript's strict mode refuses access to the caller's object, Doodad can't know with precision when we leave the framework's context__. To rectify this issue, I've recently (since the version 9.0.0) added a new method accessible by "this.callOutside" with a new callback type accessible by "doodad.OutsideCallback". You have to use one of them when you are inside a method and calling something, or getting called by something, that should be external to the object, like a callback function, or an external library if it can hold a reference to your object. I'm sorry for the inconveniences.

If you absolutely want private and protected scopes on production, and don't care about performances, you can pass these options to "createRoot" :
`js
{
startup: {
enableProperties: true
},
Doodad: {
enforceScopes: true
}
}
`

Class Modifiers

- doodad.BASE: The class is not ready for object instantiation and must be extended.
- doodad.INTERFACE: The class defines an Interface. https://en.wikipedia.org/wiki/Protocol_%28object-oriented_programming%29
- doodad.MIX_IN: The class defines a Mix-in. https://en.wikipedia.org/wiki/Mixin
- doodad.TRAIT: The class defines a Trait (currently implemented as "per convention", ie without validation). http://scg.unibe.ch/research/traits
- doodad.SEALED: Objects instantiated from this class are sealed. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/seal
- doodad.STATIC: The class does not allow instantiating.
- doodad.ISOLATED: The class defines an isolated interface. This kind of interface makes the methods separated from the methods of its host class. To get access to them, you must call "getInterface".
- doodad.EXPANDABLE: Instances of the class can be extended with ".extend". NOTE: You need to call ".create" after to apply the new construction.

Attribute Modifiers :

Example 1 (inheritance):
`js
const Turtle1 = types.INIT(doodad.Object.$extend({
$TYPE_NAME: 'Turtle1',

talk: doodad.PUBLIC(function() {
return "Hi !";
}),
}));

const turtle1 = new Turtle1();

console.log(turtle1.talk());

const Turtle2 = types.INIT(Turtle1.$extend({
$TYPE_NAME: 'Turtle2',

talk: doodad.OVERRIDE(function() {
return this._super() + " dOOOOdad";
}),
}));

const turtle2 = new Turtle2();

console.log(turtle2.talk());
`

Example 2 (interfaces):
`js
const Turtles = types.INIT(doodad.INTERFACE(doodad.Class.$extend({
$TYPE_NAME: 'Turtles',

talk: doodad.PUBLIC(doodad.METHOD()),
})));

const Turtle1 = types.INIT(doodad.Object.$extend(
Turtles, // Implements "Turtles"
{
$TYPE_NAME: 'Turtle1',

talk: doodad.OVERRIDE(function() {
return "Hi";
}),
}));

const Turtle2 = types.INIT(doodad.Object.$extend(
Turtles, // Implements "Turtles"
{
$TYPE_NAME: 'Turtle2',

talk: doodad.OVERRIDE(function() {
return "Bonjour";
}),
}));

console.log(types._implements(Turtle1, Turtles) && types._implements(Turtle2, Turtles));
`

Example 3 (mix-ins) :
`js
const Turtles = types.INIT(doodad.MIX_IN(doodad.Class.$extend({
$TYPE_NAME: 'Turtles',

talk: doodad.PUBLIC(function() {
return "Hi";
}),
})));

const Turtle1 = types.INIT(doodad.Object.$extend(
Turtles, // Composes "Turtles"
{
$TYPE_NAME: 'Turtle1',
}));

console.log(types._implements(Turtle1, Turtles));
`

Example 4 (traits) :
`js
const TAnimals = types.INIT(doodad.TRAIT(doodad.Class.$extend({
$TYPE_NAME: 'TAnimals',

talk: doodad.PUBLIC(function() {
return this.getPhrase();
}),

getPhrase: doodad.PROTECTED(doodad.MUST_OVERRIDE()),
})));

const Turtle = types.INIT(doodad.Object.$extend(
TAnimals, // Composes "TAnimals"
{
$TYPE_NAME: 'Turtles',

phrase: doodad.PUBLIC(null),

create: doodad.OVERRIDE(function(phrase) {
this._super();
this.phrase = phrase;
}),

talk: doodad.RENAME_OVERRIDE(function slowTalk() {
return this._super().split('').join('...');
}),

getPhrase: doodad.OVERRIDE(function() {
return this.phrase;
}),
}));

const turtle = new Turtle("Hi !");

console.log(turtle.talk());
console.log(turtle.slowTalk());
`

Example 5 (expandable objects) :
`js
const IAnimal = types.INIT(doodad.INTERFACE(doodad.Class.$extend({
$TYPE_NAME: 'IAnimal',

makeNoise: doodad.MUST_OVERRIDE(),
})));

const perrot = new doodad.Object();

perrot.extend(
IAnimal, // Implements "IAnimal"
{
phrase: null,
create: doodad.OVERRIDE(function(phrase) {
this._super();
this.phrase = phrase;
}),
makeNoise: doodad.OVERRIDE(function() {
return this.phrase;
}),
})
.create("Hello world !");

console.log(perrot.makeNoise());
`

Future

I'm waiting after changes to the Javascript language to get something like :

`js
@interface
class Turtles {
@returns(types.isString)
talk()
}

class SmallTurtle implements Turtles {
@override
talk() {
return "hi";
}
}

class GiantTurtle implements Turtles {
@override
talk() {
return "HI";
}
}
``

But I'll have to see what is feasible after current proposals like "decorators", "public fields" and "private fields".

~~I'm also looking more forward on the future : WASM. With that, I hope to be able to make my own JS derived language, cleaned from everything that some like me (or just me) doesn't like, with the addition of my own (and, I believe, more realistic) classes.~~ (Suspended)

$3

With all the incoming changes to the Javascript language, "@doodad-js/core" could be reduced to some custom decorators, small utility functions and some prebuilt classes.

Other available packages

- @doodad-js/core: Object-oriented programming framework (release)
- @doodad-js/cluster: Cluster manager (alpha)
- @doodad-js/dates: Dates formatting (beta)
- @doodad-js/http: Http server (alpha)
- @doodad-js/http_jsonrpc: JSON-RPC over http server (alpha)
- @doodad-js/io: I/O module (alpha)
- @doodad-js/ipc: IPC/RPC server (alpha)
- @doodad-js/json: JSON parser (alpha)
- @doodad-js/loader: Scripts loader (beta)
- @doodad-js/locale: Locales (beta)
- @doodad-js/make: Make tools for doodad (alpha)
- @doodad-js/mime: Mime types (beta)
- @doodad-js/minifiers: Javascript minifier used by doodad (alpha)
- @doodad-js/safeeval: SafeEval (beta)
- @doodad-js/server: Servers base module (alpha)
- @doodad-js/templates: HTML page templates (alpha)
- @doodad-js/terminal: Terminal (alpha)
- @doodad-js/test: Test application
- @doodad-js/unicode: Unicode Tools (beta)
- @doodad-js/widgets: Widgets base module (alpha)
- @doodad-js/xml: XML Parser (beta)

License

[Apache-2.0][license-url]

This package also includes packages "uuid" and "json5", which are licensed under MIT.

[npm-image]: https://img.shields.io/npm/v/@doodad-js/core.svg
[npm-url]: https://npmjs.org/package/@doodad-js/core
[license-url]: http://opensource.org/licenses/Apache-2.0
[latest-url]: https://github.com/doodadjs/doodad-js/releases/latest
[make-url]: https://npmjs.org/package/@doodad-js/make