@lwc-bolts/sf2ts 0.0.4 → 1.0.0

package/dist/names.js

@@ -0,0 +1,67 @@
+/**
+ * Suffixes of custom API names: objects and fields (`__c`), relationships (`__r`), custom metadata types
+ * (`__mdt`), platform events (`__e`), big objects (`__b`) and external objects (`__x`).
+ */
+const CUSTOM_SUFFIXES = new Set(["c", "r", "mdt", "e", "b", "x"]);
+/** Whether a name ends in a custom suffix (`Invoice__c`, `acme__Lines__r`). */
+function isCustomName(name) {
+    const parts = name.split("__");
+    return parts.length > 1 && CUSTOM_SUFFIXES.has(parts.at(-1).toLowerCase());
+}
+/**
+ * A custom name with the project's namespace (`acme__Invoice__c` for `Invoice__c`), as records and the
+ * values of schema imports have it inside the namespace. Standard names (`Account`, `Name`), names that
+ * already have a namespace (`other__Invoice__c`), and every name without a project namespace are left as
+ * they are.
+ */
+export function recordName(name, namespace) {
+    return namespace && isCustomName(name) && name.split("__").length === 2 ? `${namespace}__${name}` : name;
+}
+/**
+ * An API name's namespace and its name without it. Salesforce names can't contain `__` themselves, so a
+ * name ending in a custom suffix has a namespace when it has three parts (`dlrs__Log__c`), and any other
+ * name when it has two (`dlrs__RollupController`, a label's `dlrs__fflib_error`).
+ */
+export function splitNamespace(apiName) {
+    const parts = apiName.split("__");
+    const custom = isCustomName(apiName);
+    if ((custom && parts.length === 3) || (!custom && parts.length === 2)) {
+        return { namespace: parts[0], name: parts.slice(1).join("__") };
+    }
+    return { namespace: undefined, name: apiName };
+}
+/**
+ * How a component in the project names an item in an import: inside a namespace, LWC rejects the
+ * project's own namespace and requires any other. So `namespace` is the item's namespace when it's
+ * another's (an installed package's, such as `dlrs`), and undefined when it's the project's or it has
+ * none; `name` is the item's name without its namespace either way.
+ */
+export function importNameParts(apiName, projectNamespace) {
+    const { namespace, name } = splitNamespace(apiName);
+    return namespace === undefined || namespace.toLowerCase() === projectNamespace?.toLowerCase()
+        ? { namespace: undefined, name }
+        : { namespace, name };
+}
+/**
+ * A name without the project's namespace (`Invoice__c` for `acme__Invoice__c`, `logo` for `acme__logo`),
+ * as LWC inside the namespace must import it. Other namespaces' names are left as they are.
+ */
+export function importName(name, namespace) {
+    const split = splitNamespace(name);
+    return namespace !== undefined && split.namespace?.toLowerCase() === namespace.toLowerCase() ? split.name : name;
+}
+/**
+ * The name of a metadata file: its file name up to the first `.`, such as `Account` for
+ * `objects/Account/Account.object-meta.xml`. Paths can use either separator.
+ */
+export function metadataName(path) {
+    const name = path.split(/[\\/]/).pop()?.split(".")[0];
+    if (!name) {
+        throw new Error(`no metadata name in the file path ${path}`);
+    }
+    return name;
+}
+/** The import form of a metadata file's name (see `metadataName`), such as `logo` for `acme__logo.resource-meta.xml` in project `acme`. */
+export function fileImportName(component, projectNamespace) {
+    return importName(metadataName(component.path), projectNamespace);
+}

package/dist/text-builder.d.ts

@@ -0,0 +1,34 @@
+import type { ConversionOutput, MapPair } from "./types.ts";
+/**
+ * TypeScript `SpanMapFeature` flags, for a mapped piece that only takes part in some editor features.
+ * Diagnostics aren't a feature: they're mapped whatever a piece's features are.
+ */
+export declare const MapFeature: {
+    readonly Definition: 8;
+    readonly All: 1048575;
+};
+/** A piece of a component's source, from `start` up to `end`, as UTF-16 offsets. */
+export interface SourceRange {
+    start: number;
+    end: number;
+}
+/**
+ * Builds generated text, recording which pieces of it came from which source text: each mapped piece is
+ * a pair of `MapPair`s, its start and its end. Unmapped text isn't recorded.
+ */
+export declare class TextBuilder {
+    #private;
+    /** The text written so far. */
+    get text(): string;
+    /** The mapped pieces of the text written so far. */
+    get mapData(): MapPair[];
+    /** The text written and its mapped pieces, as a converter returns them. */
+    output(): ConversionOutput;
+    /**
+     * Writes text, mapped to the source from `sourceStart` to `sourceEnd` when both are given, for the
+     * editor `features` given (see `MapFeature`), or for all of them.
+     */
+    write(text: string, sourceStart?: number, sourceEnd?: number, features?: number): void;
+    /** Writes text mapped to `range` in the source, or unmapped text when the source has no such range. */
+    writeMapped(text: string, range: SourceRange | null | undefined): void;
+}

package/dist/text-builder.js

@@ -0,0 +1,46 @@
+/**
+ * TypeScript `SpanMapFeature` flags, for a mapped piece that only takes part in some editor features.
+ * Diagnostics aren't a feature: they're mapped whatever a piece's features are.
+ */
+export const MapFeature = {
+    Definition: 8,
+    All: 1048575,
+};
+/**
+ * Builds generated text, recording which pieces of it came from which source text: each mapped piece is
+ * a pair of `MapPair`s, its start and its end. Unmapped text isn't recorded.
+ */
+export class TextBuilder {
+    #text = "";
+    #mapData = [];
+    /** The text written so far. */
+    get text() {
+        return this.#text;
+    }
+    /** The mapped pieces of the text written so far. */
+    get mapData() {
+        return this.#mapData;
+    }
+    /** The text written and its mapped pieces, as a converter returns them. */
+    output() {
+        return { text: this.#text, mapData: this.#mapData };
+    }
+    /**
+     * Writes text, mapped to the source from `sourceStart` to `sourceEnd` when both are given, for the
+     * editor `features` given (see `MapFeature`), or for all of them.
+     */
+    write(text, sourceStart, sourceEnd, features) {
+        if (sourceStart !== undefined && sourceEnd !== undefined) {
+            this.#mapData.push({ sourcePos: sourceStart, destPos: this.#text.length, ...(features !== undefined && { features }) });
+            this.#text += text;
+            this.#mapData.push({ sourcePos: sourceEnd, destPos: this.#text.length });
+        }
+        else {
+            this.#text += text;
+        }
+    }
+    /** Writes text mapped to `range` in the source, or unmapped text when the source has no such range. */
+    writeMapped(text, range) {
+        this.write(text, range?.start, range?.end);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,128 @@
+/** The metadata types sf2ts converts, each by its converter (see converters/registry.ts). */
+export type MetadataType = "ApexClass" | "ContentAsset" | "CustomField" | "CustomLabel" | "CustomLabels" | "CustomObject" | "CustomPermission" | "LightningComponentBundle" | "LightningMessageChannel" | "StaticResource";
+/** What becomes of an Apex class's fields LWC can't read (see `ConvertOptions.inaccessibleApexProperties`). */
+export type InaccessibleApexProperties = "include" | "exclude" | "include as deprecated";
+/**
+ * A mapped piece of text is two consecutive pairs, its start and its end: where it is in the source
+ * (`sourcePos`) and in the output (`destPos`), as UTF-16 offsets.
+ */
+export interface MapPair {
+    sourcePos: number;
+    destPos: number;
+    /**
+     * On a piece's start: the editor features it takes part in, as TypeScript's `SpanMapFeature` flags
+     * (see `MapFeature`). Without them, it takes part in all of them.
+     */
+    features?: number;
+}
+/**
+ * A file to convert, by its metadata type. The options only some types take are on their own
+ * components: `ApexClassComponent` and `LightningComponentBundleComponent`.
+ */
+export type Component = ApexClassComponent | LightningComponentBundleComponent | MetadataComponent;
+/** What every component has: its file's path and content. */
+interface ComponentFile {
+    path: string;
+    content: string;
+}
+/** A component of a type that takes no options of its own. */
+export interface MetadataComponent extends ComponentFile {
+    type: Exclude<MetadataType, "ApexClass" | "LightningComponentBundle">;
+}
+/**
+ * A file of a Lightning web component bundle. sf2ts only reads the file itself: what it needs to know about
+ * the rest of the bundle is given here, which the caller finds out (`bundleApiVersion` and
+ * `defaultExportName` read it from the bundle's other files).
+ */
+export interface LightningComponentBundleComponent extends ComponentFile {
+    type: "LightningComponentBundle";
+    /**
+     * For a template (an `.html` file), the module it imports its bundle's component through, relative to the
+     * template: `./orders.js` (which TypeScript also resolves to `orders.ts`), or `../orders.js` from a
+     * subfolder of the bundle. Templates are matched to their bundle's class, as LWC does, so a bundle's
+     * alternate templates (rendered from `render()`) work too. Without it, the template is taken to be in the
+     * bundle's folder: `./<bundleName>.js`.
+     */
+    componentModule?: string;
+    /**
+     * For a template, the bundle's name (its folder's: `orders`, or an installed package's `dlrs__orders`),
+     * which names the `c/<name>` module it declares its slots under. Without it, the template's folder's name.
+     */
+    bundleName?: string;
+    /**
+     * For a template, the bundle's API version, from its `.js-meta.xml` (see `bundleApiVersion`), which the
+     * template is parsed at: the template compiler's latest without it.
+     */
+    apiVersion?: number;
+    /**
+     * For a template, whether the bundle has other templates, any of which may be the one rendered, which
+     * makes every `lwc:ref` optional.
+     */
+    alternateTemplates?: boolean;
+    /**
+     * For a `.js-meta.xml`, the name of the bundle's module's default export (see `defaultExportName`),
+     * which names the `c/<name>` module's export, as editors suggest it when auto-importing: the bundle's
+     * name without it.
+     */
+    defaultExportName?: string;
+}
+export interface ApexClassComponent extends ComponentFile {
+    type: "ApexClass";
+    /**
+     * Whether it is an SObject definition generated by the Salesforce extensions
+     * (`.sfdx/tools/sobjects`). Its fields are exposed without `@AuraEnabled`, and it declares no
+     * `@salesforce/apex` modules.
+     */
+    isSobject?: boolean;
+    /**
+     * For an SObject definition, the objects each polymorphic relationship (such as Task's `What`, declared
+     * as `SObject`) can refer to, by relationship name: `{ What: ["Account", "Case"] }`. Each is typed as one
+     * of its targets once all of them are declared, with the `Name` object's fields when it's declared too;
+     * TypeScript finds out which are. Others stay `SObject`.
+     */
+    polymorphicTargets?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * A problem in a component's file, at a UTF-16 offset and length in its content: `ConversionFailed` when
+ * the file couldn't be converted (covering the whole file, with empty output), or `TemplateError` for an
+ * error the LWC template compiler reports in a template.
+ */
+export interface Diagnostic {
+    kind: "ConversionFailed" | "TemplateError";
+    message: string;
+    start: number;
+    length: number;
+}
+/**
+ * A converted file. Metadata becomes declarations in a global script (`declare module "@salesforce/..."`
+ * and `declare namespace Apex`); a template becomes a module that imports its component and uses it the
+ * way the template does, so TypeScript checks the template against it. A file that declares nothing
+ * (such as an Apex interface) has empty `text`.
+ */
+export type ConvertedComponent = Component & ConversionOutput;
+/** What a file converts to: its TypeScript, the mapped pieces of it, and any problems. */
+export interface ConversionOutput {
+    text: string;
+    mapData: MapPair[];
+    diagnostics?: Diagnostic[];
+}
+export interface ConvertOptions {
+    /**
+     * The namespace Apex types are declared in, which may be dotted (`Org.Apex`). Defaults to `"Apex"`;
+     * `null` declares them globally, where a class can merge with a global type of the same name (such as
+     * the DOM's `Response`).
+     */
+    apexNamespace?: string | null;
+    /**
+     * What becomes of an Apex class's fields that LWC can't read (not `@AuraEnabled`, not `public` or
+     * `global`, or `static`): `"include as deprecated"` (the default) declares them marked `@deprecated`
+     * with what they'd need, so editors flag their use; `"include"` declares them like any other field;
+     * `"exclude"` leaves them out. SObject definitions' fields are always declared.
+     */
+    inaccessibleApexProperties?: InaccessibleApexProperties;
+    /**
+     * The project's namespace, used to know when to add or hide namespaces for modules and components
+     */
+    projectNamespace?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,3 @@
+// sf2ts's public types, which index.ts exports. Its own module, importing nothing, so the modules that
+// use them don't import index.ts, which imports them.
+export {};

package/dist/xml.d.ts

@@ -0,0 +1,32 @@
+import type { SourceRange } from "./text-builder.ts";
+/** An element of metadata XML: its text and children, and where it is in the source. */
+export declare class XmlElement {
+    readonly name: string;
+    readonly children: XmlElement[];
+    /** The element's own text, with entities and CDATA decoded: `A & B` for `A & B`. */
+    text: string;
+    /** Where its name is in its start tag. */
+    readonly nameRange: SourceRange;
+    /**
+     * Where its content is, between its tags, as written (`A & B`). It's empty for a self-closing
+     * element (`<a/>`), and runs to the end of the file for one that's never closed.
+     */
+    contentRange: SourceRange;
+    constructor(name: string, nameStart: number, contentStart: number);
+    /** Its first child named `name`. */
+    child(name: string): XmlElement | undefined;
+    /** Its children named `name`. */
+    childrenNamed(name: string): XmlElement[];
+    /** The text of its first child named `name`, or undefined without one. */
+    childText(name: string): string | undefined;
+}
+/**
+ * Parses metadata XML into its root element, or undefined when it has none. It never throws: an unclosed
+ * element is closed at the end of the file, and a closing tag that matches no open element is ignored.
+ */
+export declare function parseXml(content: string): XmlElement | undefined;
+/**
+ * Parses a metadata file into its root element, which must be `<root>`: a file without one, or of
+ * another type, throws, naming the root it has.
+ */
+export declare function parseMetadataXml(content: string, root: string): XmlElement;

package/dist/xml.js

@@ -0,0 +1,80 @@
+// Metadata XML, read tolerantly with htmlparser2, so a file being edited (with an unclosed or mismatched
+// tag) converts as far as it goes. Its own module, which only converters import, so htmlparser2 loads with
+// the first of them rather than when sf2ts is imported.
+import { Parser } from "htmlparser2";
+/** An element of metadata XML: its text and children, and where it is in the source. */
+export class XmlElement {
+    name;
+    children = [];
+    /** The element's own text, with entities and CDATA decoded: `A & B` for `A & B`. */
+    text = "";
+    /** Where its name is in its start tag. */
+    nameRange;
+    /**
+     * Where its content is, between its tags, as written (`A & B`). It's empty for a self-closing
+     * element (`<a/>`), and runs to the end of the file for one that's never closed.
+     */
+    contentRange;
+    constructor(name, nameStart, contentStart) {
+        this.name = name;
+        this.nameRange = { start: nameStart, end: nameStart + name.length };
+        this.contentRange = { start: contentStart, end: contentStart };
+    }
+    /** Its first child named `name`. */
+    child(name) {
+        return this.children.find((child) => child.name === name);
+    }
+    /** Its children named `name`. */
+    childrenNamed(name) {
+        return this.children.filter((child) => child.name === name);
+    }
+    /** The text of its first child named `name`, or undefined without one. */
+    childText(name) {
+        return this.child(name)?.text;
+    }
+}
+/**
+ * Parses metadata XML into its root element, or undefined when it has none. It never throws: an unclosed
+ * element is closed at the end of the file, and a closing tag that matches no open element is ignored.
+ */
+export function parseXml(content) {
+    const top = [];
+    const open = [];
+    // htmlparser2's indices are inclusive: a tag spans `startIndex` to `endIndex`
+    const parser = new Parser({
+        onopentag(name) {
+            const element = new XmlElement(name, parser.startIndex + 1, parser.endIndex + 1);
+            (open.at(-1)?.children ?? top).push(element);
+            open.push(element);
+        },
+        ontext(text) {
+            const element = open.at(-1);
+            if (element !== undefined) {
+                element.text += text;
+            }
+        },
+        onclosetag(_name, isImplied) {
+            const element = open.pop();
+            if (element === undefined) {
+                return;
+            }
+            // a self-closing element is closed where it's opened, with no content
+            const selfClosing = isImplied && parser.startIndex + 1 === element.nameRange.start;
+            element.contentRange = { start: element.contentRange.start, end: selfClosing ? element.contentRange.start : parser.startIndex };
+        },
+    }, { xmlMode: true });
+    parser.write(content);
+    parser.end();
+    return top[0];
+}
+/**
+ * Parses a metadata file into its root element, which must be `<root>`: a file without one, or of
+ * another type, throws, naming the root it has.
+ */
+export function parseMetadataXml(content, root) {
+    const element = parseXml(content);
+    if (element?.name !== root) {
+        throw new Error(`expected a <${root}> root element, ${element === undefined ? "but the file has none" : `found <${element.name}>`}`);
+    }
+    return element;
+}

package/package.json

@@ -1,47 +1,58 @@
 {
   "name": "@lwc-bolts/sf2ts",
-  "version": "0.0.4",
+  "version": "1.0.0",
   "private": false,
-  "description": "Convert Salesforce metadata to TypeScript declarations",
+  "description": "Converts Salesforce metadata to LWC compatible TypeScript",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Anthony Heber",
+    "email": "anthony@heber.dev",
+    "url": "https://github.com/aheber"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
   "exports": {
     ".": {
-      "module-sync": "./lib/index.mjs",
-      "module": "./lib/index.mjs",
-      "require": "./lib-cjs/bundle.cjs"
+      "@lwc-bolts/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rollup --config",
-    "watch": "rollup --config --watch",
-    "test": "node --test './tests/**/*.spec.*'"
+    "prebuild": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "generate:apex-library": "node scripts/generate-apex-library.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --conditions=@lwc-bolts/source --test 'test/**/*.test.ts'",
+    "test:update": "node --conditions=@lwc-bolts/source --test --test-update-snapshots 'test/**/*.test.ts'",
+    "test:coverage": "node --conditions=@lwc-bolts/source --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/apex/library.generated.ts' 'test/**/*.test.ts'"
   },
   "keywords": [
     "salesforce",
     "apex",
+    "lwc",
     "typescript"
   ],
-  "author": {
-    "name": "Anthony Heber",
-    "email": "anthony@heber.dev",
-    "url": "https://github.com/aheber"
-  },
-  "license": "MIT",
   "dependencies": {
-    "web-tree-sitter-sfapex": "2.4.1",
-    "xml2js": "^0.6.2"
+    "@lwc-bolts/lightning-base-components": "^1.0.0",
+    "@lwc/template-compiler": "~9.4.3",
+    "@sveltejs/acorn-typescript": "^1.0.13",
+    "acorn": "^8.19.0",
+    "htmlparser2": "^10.1.0",
+    "web-tree-sitter-sfapex": "^3.0.2"
   },
   "devDependencies": {
-    "@types/xml2js": "^0.4.14",
-    "rollup": "^4.30.1"
-  },
-  "files": [
-    "lib",
-    "lib-cjs",
-    "package.json",
-    "package-lock.json",
-    "README.MD"
-  ]
+    "@types/node": "^22.20.5",
+    "typescript": "7.1.0-beta"
+  }
 }

package/README.MD

@@ -1,5 +0,0 @@
-The purpose of this library is to take Salesforce Metadata content and transpile it to TypeScript Declaration (d.ts format) content so it can be written to a file or proxied on file reads for editors and language servers.
-
-This library does not engage with file systems and is not responsible for discovering or identifying available metadata.
-
-Apex should include raw AuraEnabled, AuraEnabled + cacheable, classes with fields (fields not AuraEnabled should show as deprecated with a note), and Apex Continuations, should also carry forward ApexDoc text comments so it can be exposed on definitions.

package/lib/converts/_index.mjs

@@ -1,8 +0,0 @@
-export { ApexClass } from "./apex-class.mjs";
-export { ContentAsset } from "./content-asset.mjs";
-export { CustomPermission } from "./custom-permission.mjs";
-export { CustomField } from "./custom-field.mjs";
-export { CustomLabel } from "./custom-label.mjs";
-export { CustomLabels } from "./custom-labels.mjs";
-export { CustomObject } from "./custom-object.mjs";
-export { StaticResource } from "./static-resource.mjs";