V3 API ergonomics

[hrgdavor]

We should look more into API from a perspective of how we would like to write jscad scripts more easily.

This may seem in oposite direction of above sentence, but does not have to be. I am personally for moving away from automagic require('') loading STL or other formats, but it will continue to be fully supported for jscad V2 scripts in new jscad prototype. I prefer for V3 code to be as close to a regular js project, so idea is to make jscad io easily usable in any js project, not just jscad scripts. I am working on input type=file and from first attempts jcad/io ergonomy is bit awkward.

ideally a script would import {deserialize} from '@jscad/io' or more specific import {deserializeStl} from '@jscad/io' and then

import {deserialize} from '@jscad/io'
export const main({inputFile, numOfSlices=10}){
  const object = deserialize(inputFile.name, inputFile.content)
  // return sliced object
}

that way such script could be used in nodejs

import {readFIleSync} from 'fs'
import * as slicer from './slicer.js'

const name = process.argv[1]
const content = readFileSync(name)
const sliced = slicer.main({inputFile={name,content}})
// do something with sliced object

My idea with deserialize is to expose the logic we already have in require automagic regarding file extensions. User loads the file contents somehow depending if it is node or browser env, and depending if mimeType or file name is known, tells that to deserialize so the right deserializer can be called. This is in case one is making a script that allows for import of models not known in advance what is the conent. In case user knows for example STL will be used, stl deserializer can be called directly.

[hrgdavor]

I may be repeating myself, but I am loking at a script one of users sent on discord to troubleshoot and it has these imports:

const { cube, sphere, cylinder } = require('@jscad/modeling').primitives
const { subtract, union } = require('@jscad/modeling').booleans
const { rotate, translate } = require('@jscad/modeling').transforms
const { extrudeLinear } = require('@jscad/modeling').extrusions
const { vectorText } = require('@jscad/modeling').text
const { degToRad } = require('@jscad/modeling').utils

this would be much nicer and IDE friendly

const {
  cube,
  sphere,
  cylinder,
  subtract,
  union,
  rotate,
  translate,
  extrudeLinear,
  vectorText,
  degToRad,
} = require("@jscad/modeling");

or import variant of it. at some point if I remember name of the func like degToRad it is pain in the ass trying to remember under which sub-package it is in modelling. And in vscode you can easily fold import like example 2, to avoid visual clutter.

[platypii]

I like the idea of flattening the imports. I think it makes it more user friendly. The code is more aesthetic. And it's not like the JSCAD api is all that big. I would vote to export at the top level of @jscad/modeling everything in primitives, operations, etc. We can keep the files nicely organized in the repo the way they are now, and just change the exports if we want to do this.