miniSphere 5.4.0

miniSphere 5.4.0 is the fifth release in the 5.0 series. This release brings support for the .cjs extension, adds a new strictImports development flag and brings a slew of bug fixes and other enhancements.

important note:
the .tar.gz tarball no longer includes ChakraCore binaries. to get these, first check if your distribution has a ChakraCore dev package available and install it if so; if not, then run sudo make deps from the miniSphere source directory to download the binaries from Microsoft and install them. you should only need to do this once.

What's New?

• miniSphere and Cell now support the .cjs file extension introduced in Node.js v13.2.0. Scripts with this extension are always loaded as CommonJS modules, regardless of whether require() or import is used. This can be helpful if you need to load a CommonJS module using a relative path, since relative require() is not supported in ESM files.

• miniSphere 5.4 adds a new optional strictImports flag in the development section of game.json. This flag, when enabled, causes SpheRun to enforce that your import specifiers are Oozaru-compatible--in particular, any imports referring to files in the project must include the file extension, such as .js. Like other development flags, strictImports has no effect in production.

• DirectoryStream now includes additional depth and extension properties on result objects, making it easier to filter directory entries based on those criteria. Keep in mind that since the new properties are part of the experimental API level 3, they will be disabled in retrograde mode.

• Mouse#getEvent() no longer returns null in case of an empty queue. Instead it now returns an object whose .event is set to null in this case to facilitate safe destructuring of the return value. This might break code that specifically checked for a return value of null. The old behavior is being treated as a bug and the change may be backported if necessary, so any code that does this should be updated as soon as possible.

• Several Query methods were renamed to align with the corresponding LINQ names. This will inevitably break code that uses these methods; check the changelog for the full list. Note that the Sphere Runtime API is not yet frozen.

• Cell now supports using a directory name for Tool#stage(). Directories are considered to be permanantly out-of-date, so Cell will always run a tool which claims to build one. This eases things for tools that dynamically determine their sources or create multiple output files, which would often be considered erroneously up-to-date because Cell didn't consider all the files involved.

• To improve sandboxing and ensure out-of-source builds always work correctly, starting with this version, Cell code can no longer write files and directories under $/. This change might break builds that depend on $/ being writable.

• Cell now tracks all files created using FS.writeFile() as build artifacts. These files will be therefore now be deleted when running cell clean, even if they have no corresponding Target.

Full Changelog

• Adds several Query methods: apply, call, concat, elementAt, join, memoize, pull, single, skipLast, skipWhile, takeLast, takeWhile, and zip.
• Adds Mouse#position which returns a tuple [x, y] for easy destructuring.
• Adds mouse-button activation support to the console module.
• Adds a new FS.match() API for matching filenames and paths against "glob" patterns such as **/*.js, useful for filtering DirectoryStream output.
• Adds new depth and extension properties to DirectoryStream output to make filtering even easier.
• Adds support for using a directory as the output of Tool#stage() in Cell.
• Adds support for the .cjs file extension to facilitate smoother interop between ESM and CommonJS code.
• Adds a strictImports manifest flag to enforce Oozaru-compatible imports.
• Improves sandboxing by disabling write access to $/ in Cell code.
• Improves Cell build hygiene by tracking files created with FS.writeFile() as build artifacts and cleaning them as necessary.
• Renames Query#drop() to Query#skip() for consistency with LINQ.
• Renames Query#reduce() to Query#aggregate().
• Renames Query#over() to Query#selectMany().
• Renames Query#uniq() to Query#distinct().
• Fixes a bug where destructuring the return value of Mouse#getEvent() can throw an error due to being null.
• Fixes a bug where Query#any() and Query#all() can return undefined in certain cases instead of a boolean value.
• Fixes a bug where Query#count() can return null instead of 0.
• Fixes a bug where require() can't be used to load system modules like sphere-runtime.
• Fixes a bug where Cell fails to properly normalize the pathname passed to Tool#stage(), potentially leading to undesirable behavior later.