@factoidal/core 0.7.1 → 0.10.0

package/api.d.ts

@@ -0,0 +1,53 @@
+// TypeScript declarations for '@factoidal/core/api': the typed API over a
+// Lean engine the caller loaded (api.mjs).
+
+/**
+ * A loaded Lean engine handle (the value `loadL4()` of
+ * `@factoidal/core/l4-assets/l4factoidal.js` resolves to: an object with
+ * `call(op, args)`), a Promise of one, or a zero-argument function
+ * answering either.
+ */
+export type EngineSource =
+  | object
+  | Promise<object>
+  | (() => object | Promise<object>);
+
+export interface CreateApiOptions {
+  /** Reported as the returned API's `engine` field. Default 'lean4-wasm'. */
+  engineName?: string;
+}
+
+/**
+ * The typed API (the functions `@factoidal/core` exports) over `engine`.
+ * Throws a TypeError when `engine` is a plain object with no `call`
+ * method. `openStore()` on the result takes a reader function only.
+ */
+export function createApi(
+  engine: EngineSource,
+  options?: CreateApiOptions
+): typeof import('./index').default;
+
+/**
+ * The constructor createApi() is built on: a typed API over an ENTRY
+ * object (one method per dispatch op, string arguments, a JSON envelope
+ * string back), as entryFromEngine() builds it.
+ */
+export function buildApi(driver: {
+  engineName: string;
+  loadEntry: () => object | Promise<object>;
+  storeReaderFor?: (root: string) => import('./index').StoreReader;
+}): typeof import('./index').default;
+
+/** The entry object over a loaded engine handle (lib/lean-entry.mjs). */
+export function entryFromEngine(engine: object): Record<string, unknown>;
+
+export const Dataset: typeof import('./index').Dataset;
+export const DatasetHandle: typeof import('./index').DatasetHandle;
+export const Store: typeof import('./index').Store;
+export const dataFactory: import('./index').DataFactory;
+/** Position-carrying parse failure; see index.d.ts's ParseError. */
+export const ParseError: typeof import('./index').ParseError;
+/** Package version string, e.g. '0.9.0'. */
+export const version: string;
+
+export default createApi;

package/api.js

@@ -0,0 +1,5 @@
+// @factoidal/core/api for require(): the ES module api.mjs.
+
+'use strict';
+
+module.exports = require('./api.mjs');

package/api.mjs

@@ -0,0 +1,56 @@
+// @factoidal/core/api — the typed API over a Lean engine the caller loads.
+//
+// index.mjs and browser.js find and load the engine themselves. A bundler
+// build, or a page with its own asset layout, may want to load it another
+// way: import the loader, instantiate the module however the page needs,
+// and hand the result here.
+//
+//   import { createApi } from '@factoidal/core/api';
+//   import { loadL4 } from '@factoidal/core/l4-assets/l4factoidal.js';
+//   const factoidal = createApi(() => loadL4());
+//   const ds = await factoidal.parse('<a> <b> "c" .', { format: 'ntriples' });
+//
+// `engine` is the handle loadL4() resolves to (an object with
+// call(op, args)), a Promise of one, or a zero-argument function answering
+// either. Nothing here fetches or evaluates code; WebAssembly compilation
+// happens in the loader, which a Content-Security-Policy page allows with
+// 'wasm-unsafe-eval'.
+//
+// openStore() here takes a reader function only: there is no file system.
+
+import { buildApi, ParseError, DatasetHandle, Store } from './lib/api.mjs';
+import { entryFromEngine } from './lib/lean-entry.mjs';
+import { dataFactory } from './rdfjs.mjs';
+import { Dataset } from './lib/dataset.mjs';
+import { version } from './lib/version.mjs';
+
+function isThenable(x) {
+  return !!x && (typeof x === 'object' || typeof x === 'function') &&
+    typeof x.then === 'function';
+}
+
+/**
+ * The typed API (the functions index.mjs exports) over a Lean engine.
+ * @param {object|Promise<object>|(() => object|Promise<object>)} engine
+ * @param {{engineName?: string}} [options]
+ */
+export function createApi(engine, options) {
+  const opts = options || {};
+  // A plain handle is checked now, so a wrong argument fails here and not
+  // at the first query.
+  let entry = (typeof engine !== 'function' && !isThenable(engine))
+    ? entryFromEngine(engine)
+    : undefined;
+  return buildApi({
+    engineName: opts.engineName || 'lean4-wasm',
+    loadEntry: async () => {
+      if (entry !== undefined) return entry;
+      const produced = typeof engine === 'function' ? engine() : engine;
+      entry = entryFromEngine(await produced);
+      return entry;
+    },
+  });
+}
+
+export { buildApi, entryFromEngine, ParseError, DatasetHandle, Store, Dataset, dataFactory, version };
+export default createApi;

package/bin/engine.mjs

@@ -4,13 +4,15 @@
 //
 // This file resolves three files that must stay together and keep their
 // names -- l4factoidal.js, l4factoidal.mjs and l4factoidal.wasm -- and
-// imports the loader. The Emscripten glue resolves the .wasm sidecar from
+// imports the loader. The core engine (`@factoidal/core/core`, issue 713
+// stage 4) is the same three files under the name l4factoidal-core; every
+// function here takes the name, 'l4factoidal' (the full engine) by default. The Emscripten glue resolves the .wasm sidecar from
 // its own basename, so a rename breaks the load on every runtime
 // (skills/lean4-wasm-export, "the naming trap").
 //
-// `npm/factoidal/l4.js` does the same resolution for the CommonJS API. It
-// is not reused here because it is CommonJS and this command must load
-// under Deno without the require() compatibility path.
+// The library entries (`index.mjs`, `browser.js`) load the engine their
+// own way; this file stays free of require() so the command loads under
+// Deno without the CommonJS compatibility path.
 //
 // WHAT THIS FILE IS ALLOWED TO DO
 // Find the engine, load it, and turn bytes into the hexadecimal string
@@ -52,6 +54,16 @@ export function packageDirectory () {
   return fileUrlToPath(new URL('..', import.meta.url).href).replace(/\/$/, '')
 }
 
+/** The two engines: the full module and the core module (issue 713 stage 4). */
+export const ENGINE_NAMES = Object.freeze(['l4factoidal', 'l4factoidal-core'])
+
+function checkName (name) {
+  if (!ENGINE_NAMES.includes(name)) {
+    throw new TypeError(`unknown engine '${name}' (expected one of ${ENGINE_NAMES.join(', ')})`)
+  }
+  return name
+}
+
 /**
  * The loader file of the first engine source that exists, or null.
  *
@@ -59,38 +71,44 @@ export function packageDirectory () {
  *   1. this package's own l4-assets/ (what `npm install` gives);
  *   2. $FACTOIDAL_L4_ASSETS (a custom deployment);
  *   3. the repository checkout layout, docs/web/hub/assets/l4/.
+ *
+ * @param {string} [name] 'l4factoidal' (the full engine) or 'l4factoidal-core'
  */
-export function resolveEngine () {
-  const inPackage = joinPath(packageDirectory(), 'l4-assets/l4factoidal.js')
+export function resolveEngine (name = 'l4factoidal') {
+  checkName(name)
+  const inPackage = joinPath(packageDirectory(), `l4-assets/${name}.js`)
   if (readable(inPackage)) return inPackage
   const override = environment('FACTOIDAL_L4_ASSETS')
   if (override !== null) {
-    const path = joinPath(override, 'l4factoidal.js')
+    const path = joinPath(override, `${name}.js`)
     if (readable(path)) return path
-    throw new Error(`FACTOIDAL_L4_ASSETS=${override} holds no l4factoidal.js`)
+    throw new Error(`FACTOIDAL_L4_ASSETS=${override} holds no ${name}.js`)
   }
   const inCheckout = joinPath(packageDirectory(),
-    '../../docs/web/hub/assets/l4/l4factoidal.js')
+    `../../docs/web/hub/assets/l4/${name}.js`)
   if (readable(inCheckout)) return inCheckout
   return null
 }
 
-let enginePromise = null
+const enginePromises = new Map()
 
 /**
- * Load the engine once and return its handle: `call(op, args)` and
- * `callBlob(op, args, bytes)`.
+ * Load an engine once per process and return its handle: `call(op, args)`,
+ * `callBlob(op, args, bytes)`, `callBlobIO(op, args, bytes)`.
+ *
+ * @param {string} [name] 'l4factoidal' (the full engine) or 'l4factoidal-core'
  */
-export function loadEngine () {
-  if (enginePromise !== null) return enginePromise
-  enginePromise = (async () => {
-    const loaderPath = resolveEngine()
+export function loadEngine (name = 'l4factoidal') {
+  checkName(name)
+  if (enginePromises.has(name)) return enginePromises.get(name)
+  const promise = (async () => {
+    const loaderPath = resolveEngine(name)
     if (loaderPath === null) {
       throw new Error(
-        'the Lean engine assets are missing. They normally ship in this ' +
+        `the Lean engine assets are missing (${name}). They normally ship in this ` +
         "package's own l4-assets/ directory; if it is absent this install " +
         'is incomplete. Otherwise set FACTOIDAL_L4_ASSETS to a directory ' +
-        'holding l4factoidal.js, l4factoidal.mjs and l4factoidal.wasm.')
+        `holding ${name}.js, ${name}.mjs and ${name}.wasm.`)
     }
     const url = loaderPath.startsWith('file://')
       ? loaderPath
@@ -98,7 +116,8 @@ export function loadEngine () {
     const module = await import(url)
     return module.loadL4()
   })()
-  return enginePromise
+  enginePromises.set(name, promise)
+  return promise
 }
 
 const HEX = (() => {