@lwc-bolts/sf2ts 0.0.4 → 1.0.0

package/dist/converters/content-asset.js

@@ -0,0 +1,20 @@
+import { fileImportName } from "../names.js";
+import { writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function ContentAsset(component, context) {
+    const asset = parseMetadataXml(component.content, "ContentAsset");
+    // LWC imports content assets by developer name (the file name), not by the display masterLabel,
+    // which may contain spaces and other characters that aren't valid in an identifier
+    // the project's own namespace is left out of imports; another's (an installed package's) is kept
+    const assetName = fileImportName(component, context.projectNamespace);
+    const builder = new TextBuilder();
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/contentAssetUrl/${assetName}`,
+        variable: assetName,
+        type: "string",
+        // go-to-definition lands on the label, or on the root element without one
+        range: asset.child("masterLabel")?.contentRange ?? asset.nameRange,
+    });
+    return builder.output();
+}

package/dist/converters/custom-field.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+export declare function CustomField(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/custom-field.js

@@ -0,0 +1,107 @@
+import { importName, metadataName, recordName, splitNamespace } from "../names.js";
+import { qualifyApex } from "../apex/namespace.js";
+import { addSObjectInterfaces, fieldDoc, fieldTsType } from "../apex/sobjects.js";
+import { schemaValueType, writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function CustomField(component, context) {
+    const field = parseMetadataXml(component.content, "CustomField");
+    const namespace = context.projectNamespace;
+    // a field's file is in its object's `fields` folder: `objects/<Object>/fields/<Field>.field-meta.xml`
+    const fileField = metadataName(component.path);
+    const fileObject = component.path.split(/[\\/]/).at(-3);
+    if (!fileObject) {
+        throw new Error(`no object name in the file path ${component.path}`);
+    }
+    // LWC imports the field by its names without the project's namespace; records and the import's value
+    // name the object and field with the namespace
+    const objectName = importName(fileObject, namespace);
+    const fieldName = importName(fileField, namespace);
+    const objectApiName = recordName(objectName, namespace);
+    const fieldApiName = recordName(fieldName, namespace);
+    // go-to-definition lands on the field's name, or on the root element without one
+    const nameRange = field.child("fullName")?.contentRange ?? field.nameRange;
+    const doc = fieldDoc(field.childText("description"), field.childText("inlineHelpText"));
+    const builder = new TextBuilder();
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/schema/${objectName}.${fieldName}`,
+        variable: fieldName,
+        type: schemaValueType(objectApiName, fieldApiName),
+        doc,
+        range: nameRange,
+    });
+    const interfaces = sobjectInterfaces(field, {
+        objectName: objectApiName,
+        fieldName: fieldApiName,
+        nameRange,
+        doc,
+        namespace,
+        apexNamespace: context.apexNamespace,
+    });
+    if (interfaces.length > 0) {
+        addSObjectInterfaces(builder, context.apexNamespace, interfaces);
+    }
+    return builder.output();
+}
+/**
+ * The field's part of its object's record type: the field itself, and for a lookup its related record
+ * and the parent's child relationship. Compound geolocation fields declare their latitude and longitude.
+ * `objectName` and `fieldName` are API names, with the project's namespace (`namespace`) for custom ones;
+ * the records it refers to are types in `apexNamespace`.
+ */
+function sobjectInterfaces(field, { objectName, fieldName, nameRange, doc, namespace, apexNamespace, }) {
+    const fieldType = field.childText("type");
+    const typeRange = field.child("type")?.contentRange;
+    if (fieldType?.toLowerCase() === "location") {
+        const base = fieldName.replace(/__c$/, "");
+        return [
+            {
+                name: objectName,
+                properties: ["Latitude", "Longitude"].map((part) => ({
+                    name: `${base}__${part}__s`,
+                    type: "number",
+                    nameRange,
+                    doc,
+                })),
+            },
+        ];
+    }
+    const type = fieldTsType(fieldType, field.childText("summaryOperation"));
+    if (type === undefined) {
+        return [];
+    }
+    const properties = [{ name: fieldName, type, nameRange, typeRange, doc }];
+    const interfaces = [{ name: objectName, properties }];
+    const writtenReferenceTo = field.childText("referenceTo");
+    const referenceTo = writtenReferenceTo && recordName(importName(writtenReferenceTo, namespace), namespace);
+    const isRelationship = ["lookup", "masterdetail", "hierarchy"].includes(fieldType?.toLowerCase() ?? "");
+    // Standard lookups (AccountId -> Account) name their relationships differently; only custom ones follow `__r`.
+    if (isRelationship && referenceTo && fieldName.endsWith("__c")) {
+        const referenceRange = field.child("referenceTo")?.contentRange;
+        properties.push({
+            name: fieldName.replace(/__c$/, "__r"),
+            type: qualifyApex(apexNamespace, [referenceTo]),
+            nameRange,
+            typeRange: referenceRange,
+            doc,
+        });
+        const relationshipName = field.childText("relationshipName");
+        // A child relationship is in its field's namespace, as its fields are: the project's own, or an
+        // installed package's (`dlrs__Log__c.dlrs__Parent__c` gives `dlrs__Children__r`), whatever the parent's.
+        const relationshipNamespace = splitNamespace(fieldName).namespace;
+        // the parent's records list their children; declaring the parent also makes the related record's type resolve
+        interfaces.push({
+            name: referenceTo,
+            properties: relationshipName
+                ? [
+                    {
+                        name: relationshipNamespace ? `${relationshipNamespace}__${relationshipName}__r` : `${relationshipName}__r`,
+                        type: `${qualifyApex(apexNamespace, [objectName])}[]`,
+                        nameRange: field.child("relationshipName")?.contentRange,
+                    },
+                ]
+                : [],
+        });
+    }
+    return interfaces;
+}

package/dist/converters/custom-label.d.ts

@@ -0,0 +1,10 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+import { TextBuilder } from "../text-builder.ts";
+import { type XmlElement } from "../xml.ts";
+export declare function CustomLabel(component: Component, context: ConversionContext): ConversionOutput;
+/**
+ * Declares a label's module as `c.Name`, mapped to its `<fullName>`. Its value is a string in the user's language.
+ * A label of another namespace (an installed package's, named `dlrs__Name`) is imported as `dlrs.Name`.
+ */
+export declare function writeLabel(builder: TextBuilder, label: XmlElement, projectNamespace: string | undefined): void;

package/dist/converters/custom-label.js

@@ -0,0 +1,36 @@
+import { importNameParts } from "../names.js";
+import { docParagraphs, docTag } from "../jsdoc.js";
+import { writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function CustomLabel(component, context) {
+    const label = parseMetadataXml(component.content, "CustomLabel");
+    if (!label.childText("fullName")) {
+        throw new Error("the label has no <fullName>");
+    }
+    const builder = new TextBuilder();
+    writeLabel(builder, label, context.projectNamespace);
+    return builder.output();
+}
+/**
+ * Declares a label's module as `c.Name`, mapped to its `<fullName>`. Its value is a string in the user's language.
+ * A label of another namespace (an installed package's, named `dlrs__Name`) is imported as `dlrs.Name`.
+ */
+export function writeLabel(builder, label, projectNamespace) {
+    const fullName = label.child("fullName");
+    if (fullName === undefined || fullName.text === "") {
+        return;
+    }
+    const imported = importNameParts(fullName.text, projectNamespace);
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/label/${imported.namespace ?? "c"}.${imported.name}`,
+        variable: `lbl${imported.name}`,
+        type: "string",
+        doc: docParagraphs(quoted(label.childText("value") || undefined), docTag("description", label.childText("shortDescription"))),
+        range: fullName.contentRange,
+    });
+}
+/** A label's value in double quotes, so the documentation shows where it starts and ends. */
+function quoted(value) {
+    return value === undefined ? undefined : `"${value}"`;
+}

package/dist/converters/custom-labels.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+export declare function CustomLabels(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/custom-labels.js

@@ -0,0 +1,10 @@
+import { TextBuilder } from "../text-builder.js";
+import { writeLabel } from "./custom-label.js";
+import { parseMetadataXml } from "../xml.js";
+export function CustomLabels(component, context) {
+    const builder = new TextBuilder();
+    for (const label of parseMetadataXml(component.content, "CustomLabels").childrenNamed("labels")) {
+        writeLabel(builder, label, context.projectNamespace);
+    }
+    return builder.output();
+}

package/dist/converters/custom-object.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+export declare function CustomObject(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/custom-object.js

@@ -0,0 +1,37 @@
+import { fileImportName, recordName } from "../names.js";
+import { qualifyApex } from "../apex/namespace.js";
+import { addSObjectInterfaces, standardFields } from "../apex/sobjects.js";
+import { docTag } from "../jsdoc.js";
+import { schemaValueType, writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function CustomObject(component, context) {
+    const obj = parseMetadataXml(component.content, "CustomObject");
+    // LWC imports the object by its name without the project's namespace; records and the import's value
+    // name it with the namespace
+    const objectName = fileImportName(component, context.projectNamespace);
+    const apiName = recordName(objectName, context.projectNamespace);
+    // go-to-definition lands on the label, or on the root element without one
+    const labelRange = obj.child("label")?.contentRange ?? obj.nameRange;
+    const doc = [docTag("description", obj.childText("description"))];
+    const builder = new TextBuilder();
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/schema/${objectName}`,
+        variable: objectName,
+        type: schemaValueType(apiName),
+        doc,
+        range: labelRange,
+    });
+    // The object's record type, with its standard fields; each field file adds its own field.
+    const properties = standardFields(objectName, {
+        owned: obj.childText("sharingModel") !== "ControlledByParent",
+        apexNamespace: context.apexNamespace,
+    });
+    const user = qualifyApex(context.apexNamespace, ["User"]);
+    addSObjectInterfaces(builder, context.apexNamespace, [
+        { name: apiName, nameRange: labelRange, doc, properties },
+        // referenced by CreatedBy and LastModifiedBy; declared here so the reference always resolves
+        ...(properties.some((p) => p.type === user) ? [{ name: "User", properties: [] }] : []),
+    ]);
+    return builder.output();
+}

package/dist/converters/custom-permission.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+export declare function CustomPermission(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/custom-permission.js

@@ -0,0 +1,21 @@
+import { fileImportName } from "../names.js";
+import { docParagraphs, docTag } from "../jsdoc.js";
+import { writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function CustomPermission(component, context) {
+    const perm = parseMetadataXml(component.content, "CustomPermission");
+    // the project's own namespace is left out of imports; another's (an installed package's) is kept
+    const permName = fileImportName(component, context.projectNamespace);
+    const builder = new TextBuilder();
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/customPermission/${permName}`,
+        variable: `has${permName}`,
+        // `true` when the user has the permission, and `undefined` when they don't
+        type: "true | undefined",
+        doc: docParagraphs(perm.childText("label"), docTag("description", perm.childText("description"))),
+        // go-to-definition lands on the label, or on the root element without one
+        range: perm.child("label")?.contentRange ?? perm.nameRange,
+    });
+    return builder.output();
+}

package/dist/converters/lightning-component-bundle.d.ts

@@ -0,0 +1,7 @@
+import type { ConversionContext } from "../context.ts";
+import type { ConversionOutput, LightningComponentBundleComponent } from "../types.ts";
+/**
+ * Converts a file of a Lightning web component's bundle with the converter for its kind (see
+ * `BUNDLE_FILES`). Any other file of the bundle, such as its JavaScript or CSS, gets a diagnostic.
+ */
+export declare function LightningComponentBundle(component: LightningComponentBundleComponent, context: ConversionContext): Promise<ConversionOutput>;

package/dist/converters/lightning-component-bundle.js

@@ -0,0 +1,31 @@
+/**
+ * The files of a Lightning web component's bundle that sf2ts converts, each by a converter of its own,
+ * loaded on its first file.
+ */
+const BUNDLE_FILES = [
+    {
+        // create the `c/<name>` module which re-exports the component exports
+        description: "<name>.js-meta.xml",
+        pattern: /\.js-meta\.xml$/i,
+        load: async () => (await import("../lightning-component-bundle/metadata.js")).convertBundleMetadata,
+    },
+    {
+        // create modules from the template files so imports and references can go both directions
+        description: ".html templates",
+        pattern: /\.html$/i,
+        load: async () => (await import("../lightning-component-bundle/templates/template.js")).convertBundleTemplate,
+    },
+];
+/**
+ * Converts a file of a Lightning web component's bundle with the converter for its kind (see
+ * `BUNDLE_FILES`). Any other file of the bundle, such as its JavaScript or CSS, gets a diagnostic.
+ */
+export async function LightningComponentBundle(component, context) {
+    const file = BUNDLE_FILES.find(({ pattern }) => pattern.test(component.path));
+    if (file === undefined) {
+        const fileName = component.path.split(/[\\/]/).pop();
+        throw new Error(`${fileName} isn't a bundle file sf2ts converts; it converts a bundle's ${BUNDLE_FILES.map(({ description }) => description).join(" and ")}`);
+    }
+    const convert = await file.load();
+    return convert(component, context);
+}

package/dist/converters/lightning-message-channel.d.ts

@@ -0,0 +1,10 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+/**
+ * Declares the `@salesforce/messageChannel/<Name>__c` module LWC imports a Lightning message channel
+ * from. The imported value is an opaque string passed to `lightning/messageService`,
+ * we also add a branded type naming the channel (the property doesn't exist at runtime) should you want to discriminate
+ * one channel from another. A channel that isn't another namespace's can also be imported through the default namespace,
+ * as `@salesforce/messageChannel/c__<Name>__c`, which is the same channel, with the same brand.
+ */
+export declare function LightningMessageChannel(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/lightning-message-channel.js

@@ -0,0 +1,39 @@
+import { fileImportName, splitNamespace } from "../names.js";
+import { docParagraphs, docTag } from "../jsdoc.js";
+import { writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+/**
+ * Declares the `@salesforce/messageChannel/<Name>__c` module LWC imports a Lightning message channel
+ * from. The imported value is an opaque string passed to `lightning/messageService`,
+ * we also add a branded type naming the channel (the property doesn't exist at runtime) should you want to discriminate
+ * one channel from another. A channel that isn't another namespace's can also be imported through the default namespace,
+ * as `@salesforce/messageChannel/c__<Name>__c`, which is the same channel, with the same brand.
+ */
+export function LightningMessageChannel(component, context) {
+    const channel = parseMetadataXml(component.content, "LightningMessageChannel");
+    // the project's own namespace is left out of imports; another's (an installed package's) is kept
+    const channelName = `${fileImportName(component, context.projectNamespace)}__c`;
+    const fieldLines = channel.childrenNamed("lightningMessageFields").flatMap((field) => {
+        const name = field.childText("fieldName");
+        if (name === undefined) {
+            return [];
+        }
+        const fieldDescription = field.childText("description");
+        return [`- \`${name}\`${fieldDescription === undefined ? "" : `: ${fieldDescription}`}`];
+    });
+    const doc = docParagraphs(channel.childText("masterLabel"), docTag("description", channel.childText("description")), fieldLines.length === 0 ? undefined : ["Message fields:", ...fieldLines]);
+    const moduleNames = splitNamespace(channelName).namespace === undefined ? [channelName, `c__${channelName}`] : [channelName];
+    const builder = new TextBuilder();
+    for (const moduleName of moduleNames) {
+        writeDefaultExportModule(builder, {
+            name: `@salesforce/messageChannel/${moduleName}`,
+            variable: channelName,
+            type: `string & { readonly __messageChannel: ${JSON.stringify(channelName)} }`,
+            doc,
+            // go-to-definition lands on the label, or on the root element without one
+            range: channel.child("masterLabel")?.contentRange ?? channel.nameRange,
+        });
+    }
+    return builder.output();
+}

package/dist/converters/registry.d.ts

@@ -0,0 +1,22 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+/** Converts a component of one type, or of any (`Component`). */
+export type Converter<C extends Component = Component> = (component: C, context: ConversionContext) => ConversionOutput | Promise<ConversionOutput>;
+/**
+ * Each metadata type's converter, loaded on its first conversion, so importing sf2ts doesn't load what
+ * converting other types needs (the Apex parser, the template converter and its compiler, an XML
+ * parser). Node caches each module after its first import. It has a converter for each `MetadataType`,
+ * which `MetadataType`'s values are made from.
+ */
+export declare const converters: {
+    ApexClass: () => Promise<typeof import("./apex-class.ts").ApexClass>;
+    ContentAsset: () => Promise<typeof import("./content-asset.ts").ContentAsset>;
+    CustomField: () => Promise<typeof import("./custom-field.ts").CustomField>;
+    CustomLabel: () => Promise<typeof import("./custom-label.ts").CustomLabel>;
+    CustomLabels: () => Promise<typeof import("./custom-labels.ts").CustomLabels>;
+    CustomObject: () => Promise<typeof import("./custom-object.ts").CustomObject>;
+    CustomPermission: () => Promise<typeof import("./custom-permission.ts").CustomPermission>;
+    LightningComponentBundle: () => Promise<typeof import("./lightning-component-bundle.ts").LightningComponentBundle>;
+    LightningMessageChannel: () => Promise<typeof import("./lightning-message-channel.ts").LightningMessageChannel>;
+    StaticResource: () => Promise<typeof import("./static-resource.ts").StaticResource>;
+};

package/dist/converters/registry.js

@@ -0,0 +1,18 @@
+/**
+ * Each metadata type's converter, loaded on its first conversion, so importing sf2ts doesn't load what
+ * converting other types needs (the Apex parser, the template converter and its compiler, an XML
+ * parser). Node caches each module after its first import. It has a converter for each `MetadataType`,
+ * which `MetadataType`'s values are made from.
+ */
+export const converters = {
+    ApexClass: async () => (await import("./apex-class.js")).ApexClass,
+    ContentAsset: async () => (await import("./content-asset.js")).ContentAsset,
+    CustomField: async () => (await import("./custom-field.js")).CustomField,
+    CustomLabel: async () => (await import("./custom-label.js")).CustomLabel,
+    CustomLabels: async () => (await import("./custom-labels.js")).CustomLabels,
+    CustomObject: async () => (await import("./custom-object.js")).CustomObject,
+    CustomPermission: async () => (await import("./custom-permission.js")).CustomPermission,
+    LightningComponentBundle: async () => (await import("./lightning-component-bundle.js")).LightningComponentBundle,
+    LightningMessageChannel: async () => (await import("./lightning-message-channel.js")).LightningMessageChannel,
+    StaticResource: async () => (await import("./static-resource.js")).StaticResource,
+};

package/dist/converters/static-resource.d.ts

@@ -0,0 +1,3 @@
+import type { ConversionContext } from "../context.ts";
+import type { Component, ConversionOutput } from "../types.ts";
+export declare function StaticResource(component: Component, context: ConversionContext): ConversionOutput;

package/dist/converters/static-resource.js

@@ -0,0 +1,20 @@
+import { fileImportName } from "../names.js";
+import { docTag } from "../jsdoc.js";
+import { writeDefaultExportModule } from "../module-declaration.js";
+import { TextBuilder } from "../text-builder.js";
+import { parseMetadataXml } from "../xml.js";
+export function StaticResource(component, context) {
+    const resource = parseMetadataXml(component.content, "StaticResource");
+    // the project's own namespace is left out of imports; another's (an installed package's) is kept
+    const resourceName = fileImportName(component, context.projectNamespace);
+    const builder = new TextBuilder();
+    writeDefaultExportModule(builder, {
+        name: `@salesforce/resourceUrl/${resourceName}`,
+        variable: resourceName,
+        type: "string",
+        doc: [docTag("description", resource.childText("description")), docTag("cacheControl", resource.childText("cacheControl"))],
+        // go-to-definition lands on the description, or on the root element without one
+        range: resource.child("description")?.contentRange ?? resource.nameRange,
+    });
+    return builder.output();
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,5 @@
+import type { Component, ConvertedComponent } from "./types.ts";
+/**
+ * A file that couldn't be converted: empty output, and a `ConversionFailed` diagnostic covering the file.
+ */
+export declare function conversionFailed(component: Component, error: unknown): ConvertedComponent;

package/dist/diagnostics.js

@@ -0,0 +1,18 @@
+/**
+ * A file that couldn't be converted: empty output, and a `ConversionFailed` diagnostic covering the file.
+ */
+export function conversionFailed(component, error) {
+    return {
+        ...component,
+        text: "",
+        mapData: [],
+        diagnostics: [
+            {
+                kind: "ConversionFailed",
+                message: `Unable to convert ${component.type} to TypeScript: ${error instanceof Error ? error.message : String(error)}`,
+                start: 0,
+                length: component.content.length,
+            },
+        ],
+    };
+}

package/dist/identifiers.d.ts

@@ -0,0 +1,12 @@
+/** Words that can't name a variable, such as a `const` declared after a component or a field. */
+export declare const RESERVED_WORDS: ReadonlySet<string>;
+/**
+ * Words that can't name a namespace, such as a part of the `apexNamespace` Apex types are declared in: the
+ * reserved words but `await`, which TypeScript accepts as a namespace's name (`declare namespace
+ * Acme.await`), though not as a variable's that's exported (`export default await;` is an expression).
+ */
+export declare const NAMESPACE_RESERVED_WORDS: ReadonlySet<string>;
+/** Whether a name is an identifier, so it can be written without quotes. */
+export declare function isIdentifier(name: string): boolean;
+/** A name for a `const`: the name itself, or with a `_` prefix when it's a reserved word (`_delete`). */
+export declare function variableName(name: string): string;

package/dist/identifiers.js

@@ -0,0 +1,19 @@
+// JavaScript identifiers in generated declarations, such as the `const` a module exports.
+/** Words that can't name a variable, such as a `const` declared after a component or a field. */
+export const RESERVED_WORDS = new Set(("break case catch class const continue debugger default delete do else enum export extends false finally for " +
+    "function if import in instanceof new null return super switch this throw true try typeof var void while with " +
+    "implements interface let package private protected public static yield await").split(" "));
+/**
+ * Words that can't name a namespace, such as a part of the `apexNamespace` Apex types are declared in: the
+ * reserved words but `await`, which TypeScript accepts as a namespace's name (`declare namespace
+ * Acme.await`), though not as a variable's that's exported (`export default await;` is an expression).
+ */
+export const NAMESPACE_RESERVED_WORDS = new Set([...RESERVED_WORDS].filter((word) => word !== "await"));
+/** Whether a name is an identifier, so it can be written without quotes. */
+export function isIdentifier(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name);
+}
+/** A name for a `const`: the name itself, or with a `_` prefix when it's a reserved word (`_delete`). */
+export function variableName(name) {
+    return RESERVED_WORDS.has(name) ? `_${name}` : name;
+}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { Component, ConvertedComponent, ConvertOptions, MetadataType as MetadataTypeName } from "./types.ts";
+export type { ApexClassComponent, Component, ConvertedComponent, ConvertOptions, Diagnostic, InaccessibleApexProperties, LightningComponentBundleComponent, MapPair, MetadataComponent, } from "./types.ts";
+export type MetadataType = MetadataTypeName;
+export declare const MetadataType: Readonly<{
+    ApexClass: "ApexClass";
+    ContentAsset: "ContentAsset";
+    CustomField: "CustomField";
+    CustomLabel: "CustomLabel";
+    CustomLabels: "CustomLabels";
+    CustomObject: "CustomObject";
+    CustomPermission: "CustomPermission";
+    LightningComponentBundle: "LightningComponentBundle";
+    LightningMessageChannel: "LightningMessageChannel";
+    StaticResource: "StaticResource";
+}>;
+/**
+ * Converts components to TypeScript: metadata to declarations, and templates to TypeScript that checks
+ * them. A file that can't be converted gets a `ConversionFailed` diagnostic and empty output rather than
+ * failing the others; invalid options (a namespace that can't be declared) reject. Each type's converter
+ * are lazy loaded.
+ */
+export declare function convert(components: Component[], options?: ConvertOptions): Promise<ConvertedComponent[]>;
+/**
+ * A Lightning web component bundle's API version, from the content of its `.js-meta.xml`, or undefined when
+ * it has none that can be read (such as one being written): a template's `apiVersion`. It loads the XML
+ * parser on its first call.
+ */
+export declare function bundleApiVersion(metadata: string): Promise<number | undefined>;
+/**
+ * The name of a component module's default export, from its JavaScript or TypeScript source, or undefined
+ * when it has no named one (or doesn't parse): a `.js-meta.xml`'s `defaultExportName`. It loads the
+ * JavaScript parser on its first call.
+ */
+export declare function defaultExportName(source: string): Promise<string | undefined>;

package/dist/index.js

@@ -0,0 +1,47 @@
+import { conversionContext } from "./context.js";
+import { converters } from "./converters/registry.js";
+import { conversionFailed } from "./diagnostics.js";
+export const MetadataType = Object.freeze(Object.fromEntries(Object.keys(converters).map((type) => [type, type])));
+/**
+ * Converts components to TypeScript: metadata to declarations, and templates to TypeScript that checks
+ * them. A file that can't be converted gets a `ConversionFailed` diagnostic and empty output rather than
+ * failing the others; invalid options (a namespace that can't be declared) reject. Each type's converter
+ * are lazy loaded.
+ */
+export async function convert(components, options) {
+    // an async function, so invalid options reject rather than throw
+    const context = conversionContext(options);
+    return Promise.all(components.map((component) => convertOne(component, context)));
+}
+async function convertOne(component, context) {
+    try {
+        const loadConverter = Object.hasOwn(converters, component.type) ? converters[component.type] : undefined;
+        if (loadConverter === undefined) {
+            throw new Error(`unsupported metadata type ${component.type}; supported types are ${Object.keys(converters).join(", ")}`);
+        }
+        // each type's converter takes that type's component, which `component.type` says this is
+        const converter = (await loadConverter());
+        // use destructing to strip text, mapData, and diagnostics if present, leaving everything else as "input"
+        const { text: _text, mapData: _mapData, diagnostics: _diagnostics, ...input } = component;
+        return { ...input, ...(await converter(component, context)) };
+    }
+    catch (error) {
+        return conversionFailed(component, error);
+    }
+}
+/**
+ * A Lightning web component bundle's API version, from the content of its `.js-meta.xml`, or undefined when
+ * it has none that can be read (such as one being written): a template's `apiVersion`. It loads the XML
+ * parser on its first call.
+ */
+export async function bundleApiVersion(metadata) {
+    return (await import("./lightning-component-bundle/metadata.js")).bundleApiVersion(metadata);
+}
+/**
+ * The name of a component module's default export, from its JavaScript or TypeScript source, or undefined
+ * when it has no named one (or doesn't parse): a `.js-meta.xml`'s `defaultExportName`. It loads the
+ * JavaScript parser on its first call.
+ */
+export async function defaultExportName(source) {
+    return (await import("./lightning-component-bundle/metadata.js")).findDefaultExportName(source);
+}

package/dist/jsdoc.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Renders a JSDoc block at `indent`, or an empty string when there are no lines. `undefined` lines
+ * are dropped, empty strings become blank comment lines, and `*\/` in the text can't end the comment.
+ */
+export declare function jsDoc(indent: string, lines: (string | undefined)[]): string;
+/**
+ * Prefixes a JSDoc tag to a value, or returns undefined when the value is missing.
+ */
+export declare function docTag(tag: string, value: string | undefined): string | undefined;
+/**
+ * Documentation lines from paragraphs, each a line or several, with a blank line between them. Missing
+ * paragraphs, and missing lines in them, are left out.
+ */
+export declare function docParagraphs(...paragraphs: (string | undefined | readonly (string | undefined)[])[]): string[];

package/dist/jsdoc.js

@@ -0,0 +1,28 @@
+// Documentation comments on generated declarations, from metadata's descriptions and Apex's ApexDoc.
+/**
+ * Renders a JSDoc block at `indent`, or an empty string when there are no lines. `undefined` lines
+ * are dropped, empty strings become blank comment lines, and `*\/` in the text can't end the comment.
+ */
+export function jsDoc(indent, lines) {
+    const body = lines.filter((line) => line !== undefined).flatMap((line) => line.replace(/\*\//g, "*\\/").split(/\r\n|\r|\n/));
+    if (body.length === 0) {
+        return "";
+    }
+    return [`${indent}/**`, ...body.map((line) => (line === "" ? `${indent} *` : `${indent} * ${line}`)), `${indent} */`, ""].join("\n");
+}
+/**
+ * Prefixes a JSDoc tag to a value, or returns undefined when the value is missing.
+ */
+export function docTag(tag, value) {
+    return value === undefined ? undefined : `@${tag} ${value}`;
+}
+/**
+ * Documentation lines from paragraphs, each a line or several, with a blank line between them. Missing
+ * paragraphs, and missing lines in them, are left out.
+ */
+export function docParagraphs(...paragraphs) {
+    const present = paragraphs
+        .map((paragraph) => (typeof paragraph === "string" || paragraph === undefined ? [paragraph] : paragraph).filter((line) => line !== undefined))
+        .filter((lines) => lines.length > 0);
+    return present.flatMap((lines, i) => (i === 0 ? lines : ["", ...lines]));
+}

package/dist/lightning-component-bundle/component-source.d.ts

@@ -0,0 +1,6 @@
+import { type Program } from "acorn";
+/**
+ * Parses a component's module, or returns undefined when it doesn't parse (such as a file being edited),
+ * so callers find nothing in it rather than guessing.
+ */
+export declare function parseComponentSource(source: string): Program | undefined;