@intersystems-community/ascot 0.2.0 → 0.3.0

package/README.md

@@ -12,19 +12,10 @@ npm install @intersystems-community/ascot
 
 ## Usage
 
-```ts
-import { createWorkspace, type Imported } from "@intersystems-community/ascot";
-
-// What the engine asks you for when a name isn't defined in the workspace, typically
-// answered from an IRIS instance over its REST API. Return `undefined` for "not found",
-// or for everything if you have no instance: the workspace is then checked on its own.
-class NoIris implements Imported {
-  async getCls(cls: string) { return undefined; }      // a class's members and metadata
-  async getInc(name: string) { return undefined; }     // the text of `name.inc`
-  async getIntOrMac(name: string) { return undefined; } // the text of routine `name`
-}
+````ts
+import { createWorkspace } from "@intersystems-community/ascot";
 
-const ws = await createWorkspace(new NoIris());
+const ws = await createWorkspace();
 
 // `open` is both open and edit: it stores the raw text (the kind comes from the uri's
 // extension: .cls, .mac, .int, .inc) and returns the uris whose cached analysis is now
@@ -47,12 +38,27 @@ await ws.diagnostics("file:///T.cls");
 
 await ws.hover("file:///T.cls", { line: 5, character: 7 }); // the `x` being written
 // "```objectscript\n%DataType = 1\n```"
+````
+
+To provide declarations for documents that aren't in the workspace, extend `IrisConnection`,
+override the lookups you can answer, and pass an instance:
+
+```ts
+import { IrisConnection, type ClassInfo } from "@intersystems-community/ascot";
+
+class MyIris extends IrisConnection {
+  override async getCls(cls: string): Promise<ClassInfo | undefined> {
+    return undefined; // look `cls` up, e.g. over IRIS's REST API
+  }
+}
+
+const connected = await createWorkspace(new MyIris());
 ```
 
 `createWorkspace` takes an optional second argument, a `Style` applied to every document:
 
 ```ts
-const strict = await createWorkspace(new NoIris(), { command: { form: "long" }, function: { case: "pascal" }, commandDo: { form: "short" } });
+const strict = await createWorkspace(undefined, { command: { form: "long" }, function: { case: "pascal" }, commandDo: { form: "short" } });
 ```
 
 Load every file of a project into one `Workspace` so cross-file references resolve, and
@@ -61,30 +67,29 @@ usually not a removal, so keep the on-disk text open instead.
 
 ## API
 
-`createWorkspace(imported, style?)` returns a `Workspace` whose methods mirror the engine's
+`createWorkspace(iris?, style?)` returns a `Workspace` whose methods mirror the engine's
 exports, all returning promises. Positions and ranges are zero-based line/character pairs,
 as in the Language Server Protocol.
 
-| Method | Returns |
-| --- | --- |
-| `open(uri, text)` | uris whose analysis is now stale |
-| `close(uri)` | uris whose analysis is now stale |
-| `diagnostics(uri)` | `Diagnostic[]` |
-| `inlayHint(uri, range)` | `InlayHint[]` |
-| `definition(uri, position)` | `Location \| undefined` |
-| `references(uri, position, includeDeclaration)` | `Location[]` |
-| `hover(uri, position)` | markdown `string \| undefined` |
-| `documentSymbol(uri)` | the class or routine and its members or labels |
-| `workspaceSymbol(query)` | classes and members across the workspace by prefix |
-| `queryCls(query)` | `[uri, ClassInfo][]` for classes by prefix |
-| `queryMem(cls, query)` | `[uri, MemberInfo][]` for a class's members by prefix |
+| Method                                          | Returns                                               |
+| ----------------------------------------------- | ----------------------------------------------------- |
+| `open(uri, text)`                               | uris whose analysis is now stale                      |
+| `close(uri)`                                    | uris whose analysis is now stale                      |
+| `diagnostics(uri)`                              | `Diagnostic[]`                                        |
+| `inlayHint(uri, range)`                         | `InlayHint[]`                                         |
+| `definition(uri, position)`                     | `Location \| undefined`                               |
+| `references(uri, position, includeDeclaration)` | `Location[]`                                          |
+| `hover(uri, position)`                          | markdown `string \| undefined`                        |
+| `documentSymbol(uri)`                           | the class or routine and its members or labels        |
+| `workspaceSymbol(query)`                        | classes and members across the workspace by prefix    |
+| `queryCls(query)`                               | `[uri, ClassInfo][]` for classes by prefix            |
+| `queryMem(cls, query)`                          | `[uri, MemberInfo][]` for a class's members by prefix |
 
 All result types (`Diagnostic`, `Location`, `ClassInfo`, `MemberInfo`, ...) are exported
 from the package.
 
-Calls are serialized: one runs at a time, and the rest queue behind it. Every `Workspace`
-created by this package shares one wasm instance and one `Imported` class, so construct
-them all from the same implementation.
+Calls are serialized: one runs at a time, and the rest queue behind it, across every
+`Workspace` created by this package, since they share one wasm instance.
 
 ## Bundling
 

package/dist/index.d.ts

@@ -8,15 +8,19 @@ type RawWorkspace = InstanceType<Root["exported"]["Workspace"]>;
 export type Workspace = {
     [K in keyof RawWorkspace]: RawWorkspace[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : RawWorkspace[K];
 };
-/** The shape your `imported.iris-connection` implementation must satisfy. */
-export interface Imported {
-    getCls(cls: string): Promise<ClassInfo | undefined>;
-    getInc(name: string): Promise<RoutineSource | undefined>;
-    getIntOrMac(name: string): Promise<RoutineSource | undefined>;
+export declare class IrisConnection {
+    /** A class's own members and metadata. */
+    getCls(_cls: string): Promise<ClassInfo | undefined>;
+    /** The text of `name.inc`. */
+    getInc(_name: string): Promise<RoutineSource | undefined>;
+    /** The text of `name.int` or `name.mac`: `{ tag: "none" }` if there is no such routine,
+     * `val: undefined` if its source isn't available. */
+    getIntOrMac(_name: string): Promise<{
+        tag: "none";
+    } | {
+        tag: "some";
+        val: RoutineSource | undefined;
+    }>;
 }
-/**
- * A `Workspace` backed by `imported`, with every method pre-serialized so overlapping
- * calls (e.g. from two documents' diagnostics resolving concurrently) can't trip ascot's
- * internal `RefCell` borrows or jco's single-in-flight-call constraint.
- */
-export declare function createWorkspace(imported: Imported, style?: Style): Promise<Workspace>;
+/** A workspace whose calls run one at a time, resolving what it doesn't contain through `iris`. */
+export declare function createWorkspace(iris?: IrisConnection, style?: Style): Promise<Workspace>;

package/dist/index.js

@@ -33,21 +33,31 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IrisConnection = void 0;
 exports.createWorkspace = createWorkspace;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-// jco needs the actual `IrisConnection` class (not just an instance) up front, to bind
-// resource-identity checks (`instanceof`) at instantiation time -- so the wasm module is
-// loaded lazily on the first `createWorkspace` call, using that call's own argument's
-// class. Every later call must be constructed from that same class; in practice callers
-// only ever have one `Imported` implementation, so this holds.
-let wasm;
-async function loadWasm(IrisConnection) {
-    return (wasm ??= import("../generated/ascot.js").then(({ instantiate }) => instantiate((name) => new WebAssembly.Module(fs.readFileSync(path.resolve(__dirname, "../lib", name))), {
-        "iris:ascot/common": {},
-        "iris:ascot/imported": { IrisConnection },
-    })));
+class IrisConnection {
+    /** A class's own members and metadata. */
+    async getCls(_cls) {
+        return undefined;
+    }
+    /** The text of `name.inc`. */
+    async getInc(_name) {
+        return undefined;
+    }
+    /** The text of `name.int` or `name.mac`: `{ tag: "none" }` if there is no such routine,
+     * `val: undefined` if its source isn't available. */
+    async getIntOrMac(_name) {
+        return { tag: "some", val: undefined };
+    }
 }
+exports.IrisConnection = IrisConnection;
+const wasm = import("../generated/ascot.js").then(({ instantiate }) => instantiate((name) => new WebAssembly.Module(fs.readFileSync(path.resolve(__dirname, "../lib", name))), {
+    "iris:ascot/common": {},
+    "iris:ascot/imported": { IrisConnection },
+}));
+wasm.catch(() => { }); // reported by createWorkspace instead
 // jco's jspi glue allows only one in-flight suspended call per component instance --
 // overlapping calls (e.g. diagnostics() and hover() both awaiting a REST round trip)
 // trip its exclusive-lock check. Every `Workspace` this package creates shares the same
@@ -74,14 +84,9 @@ function serialize(instance) {
         },
     });
 }
-/**
- * A `Workspace` backed by `imported`, with every method pre-serialized so overlapping
- * calls (e.g. from two documents' diagnostics resolving concurrently) can't trip ascot's
- * internal `RefCell` borrows or jco's single-in-flight-call constraint.
- */
-async function createWorkspace(imported, style) {
-    const IrisConnection = Object.getPrototypeOf(imported).constructor;
-    const root = await loadWasm(IrisConnection);
-    return serialize(new root.exported.Workspace(imported, style));
+/** A workspace whose calls run one at a time, resolving what it doesn't contain through `iris`. */
+async function createWorkspace(iris, style) {
+    const root = await wasm;
+    return serialize(new root.exported.Workspace(iris, style));
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAY,EAAE,oCAAgB;AAC9B,MAAY,IAAI,sCAAkB;AA+BlC,uFAAuF;AACvF,yFAAyF;AACzF,sFAAsF;AACtF,wFAAwF;AACxF,+DAA+D;AAC/D,IAAI,IAA+B,CAAC;AAEpC,KAAK,UAAU,QAAQ,CAAC,cAA2D;IAClF,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CACzE,WAAW,CACV,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAClG;QACC,mBAAmB,EAAE,EAAE;QACvB,qBAAqB,EAAE,EAAE,cAAc,EAAE;KAChC,CACV,CACD,CAAC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,qFAAqF;AACrF,wFAAwF;AACxF,kEAAkE;AAClE,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;AAE5C,SAAS,SAAS,CAAC,QAAsB;IACxC,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE;QAC1B,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAClD,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9C,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;gBACnC,MAAM,IAAI,GAAG,IAAI,CAAC;gBAClB,IAAI,OAAoB,CAAC;gBACzB,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC3D,MAAM,IAAI,CAAC;gBACX,IAAI,CAAC;oBACJ,OAAO,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;wBAAS,CAAC;oBACV,OAAO,EAAE,CAAC;gBACX,CAAC;YACF,CAAC,CAAC;QACH,CAAC;KACD,CAAyB,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACI,KAAK,0BAA0B,QAAkB,EAAE,KAAa;IACtE,MAAM,cAAc,GAAG,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC;IACnE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC5C,OAAO,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAY,EAAE,oCAAgB;AAC9B,MAAY,IAAI,sCAAkB;AA4BlC;IACC,0CAA0C;IAC1C,KAAK,CAAC,MAAM,CAAC,IAAY;QACxB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,8BAA8B;IAC9B,KAAK,CAAC,MAAM,CAAC,KAAa;QACzB,OAAO,SAAS,CAAC;IAClB,CAAC;IACD;yDACqD;IACrD,KAAK,CAAC,WAAW,CAChB,KAAa;QAEb,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;CACD;;AAED,MAAM,IAAI,GAAkB,MAAM,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CACpF,WAAW,CACV,CAAC,IAAY,EAAE,EAAE,CAChB,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EACjF;IACC,mBAAmB,EAAE,EAAE;IACvB,qBAAqB,EAAE,EAAE,cAAc,EAAE;CAChC,CACV,CACD,CAAC;AACF,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,sCAAsC;AAE5D,qFAAqF;AACrF,qFAAqF;AACrF,wFAAwF;AACxF,kEAAkE;AAClE,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;AAE5C,SAAS,SAAS,CAAC,QAAsB;IACxC,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE;QAC1B,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAClD,IAAI,OAAO,KAAK,KAAK,UAAU;gBAAE,OAAO,KAAK,CAAC;YAC9C,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;gBACnC,MAAM,IAAI,GAAG,IAAI,CAAC;gBAClB,IAAI,OAAoB,CAAC;gBACzB,IAAI,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC3D,MAAM,IAAI,CAAC;gBACX,IAAI,CAAC;oBACJ,OAAO,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACxC,CAAC;wBAAS,CAAC;oBACV,OAAO,EAAE,CAAC;gBACX,CAAC;YACF,CAAC,CAAC;QACH,CAAC;KACD,CAAyB,CAAC;AAC5B,CAAC;AAED,mGAAmG;AAC5F,KAAK,0BAA0B,IAAqB,EAAE,KAAa;IACzE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IACxB,OAAO,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC"}