Clarification on the use of the JavaScript modules

[pschroen]

Hey @saharan! 👋

So related to the previous TypeScript issue, I have a fix for that and can create a PR, but I'm unsure on the intended use of the index files in the bin directory.

They appear to be leftover from a three.js implementation by @mrEuler (@VBT-YTokan?), which has since been removed by three.js and has never been used by the package entry point itself, including the old version on npm.

Anyone who's been using this package in the past or currently through GitHub has been importing directly from the namespaces, for example:

import { oimo } from 'oimophysics';
console.log(new oimo.common.Vec3(0, -9.8, 0));

Or re-exporting the namespaces like in the index files, which allows the use of the library with a more traditional syntax:

import * as OIMO from 'oimophysics';
console.log(new OIMO.Vec3(0, -9.8, 0));
// or
import { Vec3 } from 'oimophysics';
console.log(new Vec3(0, -9.8, 0));

The index files are also missing some exports, and renaming some primitives like BoxGeometry to OBoxGeometry to prevent conflicts when used in other libraries like three.js.

It's also worth noting we don't need to rename the classes in the exports, a user who needs to import those classes can also rename the named import to whatever they want in their own app, for example:

import { BoxGeometry as OBoxGeometry } from 'oimophysics';

Anyways, all this to say, I'm fine using the library any of these ways, just wanted to clarify how you want to move forward with the index files, if they are meant to be the main entry point for the JavaScript package, or more as an example of how to re-export the namespaces for your own app?

For reference:

• Failed to build a simple TypeScript example with Browserify #52 (comment)
• Please, upload a new version to NPM #53

[saharan]

To be honest, I don't really know the point of those index files, which is mostly because I don't use node.js for my own. I think using import is a better and more flexible way, so I want to get rid of those files if they are not needed, even more so if they're causing troubles.

Also, thank you very much for tackling with #52! I plan to make a new npm package, will that resolve the issue or change its solution? It would be grateful if you or somebody else could give me some advice on making/moving a package on npm.

Thank you!

[pschroen]

No problem, to be clear the main entry point files, OimoPhysics.js and OimoPhysics.d.ts are both fine, the problem/confusion is only with the index files, which aren't being used and safe to delete. 👍

I'm happy to help with moving the npm package if needed, after the package is moved we should also update the README with the recommended use for JavaScript.

As for which syntax, for consistency with the non-module library files, I'm thinking we should use the following import syntax for the ES module as well:

import * as OIMO from 'oimophysics';
...

This is the same convention that three.js uses too.

[pschroen]

Actually, now that I'm taking a closer look at the non-module library files (I've never used them before), the namespaces are being exported by name there, for example:

window["OIMO"] = {};
window["OIMO"]["BroadPhase"] = oimo_collision_broadphase_BroadPhase;

This is different from the JS modules generated:

var oimo = oimo || {};
if(!oimo.collision) oimo.collision = {};
if(!oimo.collision.broadphase) oimo.collision.broadphase = {};
oimo.collision.broadphase.BroadPhase = class oimo_collision_broadphase_BroadPhase {

I think that was maybe the original intent of the index files, to export each class by name, but they are old and missing exports:

OimoPhysics/bin/js_modules/index.js

Line 4 in 68c1ba6

export const World = oimo.dynamics.World;

Is there an option for Haxe to export the JS modules with the same exports that the non-module library files have?

For example, where the JS module file exports both BroadPhase and oimo_collision_broadphase_BroadPhase? That's essentially what the non-module library above is doing for comparison.

I still think we should delete the index files, this is more to have the JS modules work the same way.

[saharan]

I prefer the way the non-module library exposes its content too. Currently the module library keeps its nested namespace, which is because of the compiler option -D js_unflatten.

I tried removing Haxe's js_unflatten compiler option, but then it simply turns every single . before each type name to _, so oimo.collision.broadphase.BroadPhase will be oimo_collision_broadphase_BroadPhase and this is definitely not what we want.

I can insert a flattener function just before export {oimo} so that everything in oimo can be accessed like oimo.TypeName, but then OimoPhysics.d.ts will become inconsistent and fixing it is not that straightforward. I'm not sure if replacing oimo\.([a-z]+\.)* with oimo\. in OimoPhysics.d.ts will work.

I agree to delete the index files anyway.

[8Observer8]

@pschroen, is there any hack to make OimoPhysics show correct code completion in VSCode? I mean, for writing client side in Three.js I can install Three.js module for code completion in VSCode: npm i three, and after that code completion works:

But when I install npm i github:saharan/OimoPhysics#v1.2.3 it doesn't work:

[8Observer8]

I mean it's bad that I have to use the physics engine differently on the client and server. It is why the IntelliSense in Visual Studio Code does not work correctly in the example above on the client side. I think it is relative to the issue.

Server:

import { oimo } from "oimophysics";

const world = new oimo.dynamics.World();
world.setGravity(new oimo.common.Vec3(0, -9.8, 0));
console.log(world.getGravity());

Client:

import "oimophysics";

const world = new OIMO.World();
world.setGravity(new OIMO.Vec3(0, -9.8, 0));
console.log(world.getGravity());

npm i github:saharan/OimoPhysics#v1.2.3

I've added "type": "module":

{
  "name": "oimophysics-test",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "oimophysics": "github:saharan/OimoPhysics#v1.2.3"
  }
}

The IntelliSense in VSCode works correctly only on the server side:

Full code of the client example: https://plnkr.co/edit/MpOJMudckVsUYQA8

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Example</title>
</head>

<body>
    <canvas id="renderCanvas"></canvas>

    <script type="importmap">
        {
            "imports": {
                "gl-matrix": "https://cdn.skypack.dev/gl-matrix@3.4.3",
                "oimophysics": "https://cdn.jsdelivr.net/gh/saharan/OimoPhysics@1.2.3/bin/js/OimoPhysics.js"
            }
        }
    </script>

    <script type="module">
        import "oimophysics";

        const world = new OIMO.World();
        world.setGravity(new OIMO.Vec3(0, -9.8, 0));
        console.log(world.getGravity());
    </script>
</body>

</html>

[8Observer8]

So If you try to run the server code on the client side:

    <script type="importmap">
        {
            "imports": {
                "gl-matrix": "https://cdn.skypack.dev/gl-matrix@3.4.3",
                "oimophysics": "https://cdn.jsdelivr.net/gh/saharan/OimoPhysics@1.2.3/bin/js/OimoPhysics.js"
            }
        }
    </script>

    <script type="module">
        import { oimo } from "oimophysics";

        const world = new oimo.dynamics.World();
        world.setGravity(new oimo.common.Vec3(0, -9.8, 0));
        console.log(world.getGravity());
    </script>

You will see this error: The requested module 'oimophysics' does not provide an export named 'oimo'

[pschroen]

Hi @8Observer8, yes this is related to the issue, the problem being there are two many (currently three different ways) of using the library, all with different syntax and namespaces, causing a lot of confusion.

The difference between your server and client code snippets is that they are actually using different versions of the same library.

Non-module version with the window.OIMO namespace:
https://cdn.jsdelivr.net/gh/saharan/OimoPhysics@1.2.3/bin/js/OimoPhysics.js

ES module version with the oimo namespace (note the js_modules subdirectory):
https://cdn.jsdelivr.net/gh/saharan/OimoPhysics@1.2.3/bin/js_modules/OimoPhysics.js

Both are exported when compiled with Haxe, and the default entry point for the library is the module version above, so when using npm to install the library, you're getting the module version.

Plus the TypeScript definitions and code completion only work with the module version (with the oimo namespace), simply because those definitions are only exported with the module version.

Moving forward, I think we should only export the ES modules with the TypeScript definitions.