@lwc-bolts/sf2ts 0.0.4 → 1.0.0

package/dist/apex/resolution.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Apex types as LWC receives them: Apex values are serialized to JSON, so dates, times and blobs
+ * arrive as strings (ISO-8601 / base64) and every numeric type as a number.
+ */
+export declare const PRIMITIVE_TYPES: Readonly<Record<string, string>>;
+export interface ResolverOptions {
+    /** The namespace Apex types are declared in; `null` declares them globally. */
+    readonly namespace: string | null;
+    /** The project's namespace, or undefined without one. */
+    readonly projectNamespace: string | undefined;
+    /** The installed package the file's class belongs to, when it isn't the project's. */
+    readonly packageNamespace: string | undefined;
+    /** The file's top-level type. */
+    readonly className: string;
+    /** Whether the file is an SObject definition, whose aliases are apart from classes' (see `#alias`). */
+    readonly isSobject: boolean;
+    /**
+     * The top-level type's nested classes, interfaces and enums, keyed by lower-cased name to their declared
+     * spelling. The file adds them as it finds them, before its fields refer to them.
+     */
+    readonly nestedTypes: ReadonlyMap<string, string>;
+}
+/**
+ * Resolves one Apex file's type references, and collects what its declarations then need: the library
+ * types they use, and the registries they read.
+ */
+export declare class TypeResolver {
+    #private;
+    constructor(options: ResolverOptions);
+    /** The namespace the file's types are declared in: the Apex namespace, or a package's in it. */
+    get typesNamespace(): string | null;
+    /** A name in the Apex namespace, as a reference: `Apex.Account`, or `Account` without one. */
+    qualify(parts: readonly string[]): string;
+    /** A type declared with the file's types (its classes), as a reference. */
+    qualifyOwn(parts: readonly string[]): string;
+    /**
+     * Resolves an Apex type reference (`Outer.Inner`, `Inner` from inside `Outer`, `Exception`,
+     * `System.Exception`) to its TypeScript type, as Apex looks names up. In order:
+     *
+     * 1. Through a namespace: the package's (`dlrs.RollupSummary`), which is one of its types, or the
+     *    project's (`acme.Invoices`), which is the name without it.
+     * 2. The file's own types, in their declared spelling, since Apex names are case-insensitive but
+     *    TypeScript names aren't.
+     * 3. A custom object (`Invoice__c`), named with the namespace of the code it's in.
+     * 4. A name a library type has (see library.ts): the project's types and SObjects, which shadow it,
+     *    then the library's namespaces in their configured order, through registries.
+     * 5. A library type through its namespace (`System.Exception`). Apex's primitive types are System's
+     *    (`System.String`), and a name in Schema that's no library type is an SObject (`Schema.Account`).
+     * 6. Any other name, as written in the Apex namespace (the project's classes in other files, and
+     *    standard objects).
+     *
+     * An installed package's class can't see the project's classes, and its copy may not have what it
+     * refers to, so its names are its package's types when the copy has them (`RollupSummary`,
+     * `RollupController.Result`), then library types and SObjects, and `unknown` otherwise, never an error
+     * in code that isn't the project's to fix.
+     *
+     * A reference that looks through registries is a conditional type, written where it's used (see
+     * `#lookup`).
+     *
+     * @param base whether the reference is a class's base class, which an interface can only extend by
+     *   name and which can't be `unknown`: a name a package's class can't find is `{}` instead
+     */
+    resolve(parts: readonly string[], { base }?: {
+        base?: boolean;
+    }): string;
+    /**
+     * The declarations the file's references need, in a block of their own, or "" without any: the
+     * library types they use (and their base classes), the registries they read, and the file's own type
+     * in `ownRegistry`, if given. Other files declare the same library types and registries, which merge.
+     */
+    declarations(ownName: string, ownRegistry: string | undefined): string;
+    /**
+     * The SObjects' registry (`Apex.__lwcSObjects`), which every declared SObject adds itself to, by
+     * lower-cased name: what `registryLookup` reads to refer to an SObject that may not be declared.
+     */
+    get sobjectsRegistry(): string;
+}

package/dist/apex/resolution.js

@@ -0,0 +1,306 @@
+// How an Apex file's type references become TypeScript types: Apex's primitive types, the file's own
+// types, the project's and installed packages' types, SObjects, and the standard library's (library.ts).
+// Which type a name is often depends on the whole project, while sf2ts converts one file at a time, so
+// such references check registries that the project's files add their types to (namespace.ts), and
+// TypeScript picks the type.
+import { apexLibrary } from "./library.js";
+import { CLASSES_REGISTRY, qualifyApex, registration, registryLookup, SOBJECTS_REGISTRY } from "./namespace.js";
+import { recordName } from "../names.js";
+import { RESERVED_WORDS } from "../identifiers.js";
+/**
+ * Apex types as LWC receives them: Apex values are serialized to JSON, so dates, times and blobs
+ * arrive as strings (ISO-8601 / base64) and every numeric type as a number.
+ */
+export const PRIMITIVE_TYPES = {
+    string: "string",
+    id: "string",
+    date: "string",
+    datetime: "string",
+    time: "string",
+    blob: "string",
+    decimal: "number",
+    double: "number",
+    integer: "number",
+    long: "number",
+    boolean: "boolean",
+    // any value, including null, which TypeScript's `Object` rejects
+    object: "unknown",
+    // a record of any SObject type, such as a polymorphic lookup (`Owner`, `What`)
+    sobject: "Record<string, unknown>",
+    // used by the generated SObject definitions for JSON-typed fields
+    json: "unknown",
+    void: "void",
+};
+/** Names TypeScript's types are, which an alias can't have. */
+const TYPE_KEYWORDS = new Set(["any", "bigint", "boolean", "never", "number", "object", "string", "symbol", "undefined", "unknown"]);
+/**
+ * Resolves one Apex file's type references, and collects what its declarations then need: the library
+ * types they use, and the registries they read.
+ */
+export class TypeResolver {
+    #options;
+    /** The library types the declarations reference, by namespace and name; they're declared with them. */
+    #libraryTypes = new Map();
+    /** The registries references resolve through, which are declared (empty) so they always exist. */
+    #registries = new Set();
+    /**
+     * The resolved types of references that look through registries, by type, to the names of the aliases
+     * the file declares for them, so each is written once however many references it has.
+     */
+    #aliases = new Map();
+    constructor(options) {
+        this.#options = options;
+    }
+    /** The namespace the file's types are declared in: the Apex namespace, or a package's in it. */
+    get typesNamespace() {
+        const { namespace, packageNamespace } = this.#options;
+        if (packageNamespace === undefined) {
+            return namespace;
+        }
+        return namespace === null ? packageNamespace : `${namespace}.${packageNamespace}`;
+    }
+    /** A name in the Apex namespace, as a reference: `Apex.Account`, or `Account` without one. */
+    qualify(parts) {
+        return qualifyApex(this.#options.namespace, parts);
+    }
+    /** A type declared with the file's types (its classes), as a reference. */
+    qualifyOwn(parts) {
+        const { packageNamespace } = this.#options;
+        return this.qualify(packageNamespace === undefined ? parts : [packageNamespace, ...parts]);
+    }
+    /**
+     * Resolves an Apex type reference (`Outer.Inner`, `Inner` from inside `Outer`, `Exception`,
+     * `System.Exception`) to its TypeScript type, as Apex looks names up. In order:
+     *
+     * 1. Through a namespace: the package's (`dlrs.RollupSummary`), which is one of its types, or the
+     *    project's (`acme.Invoices`), which is the name without it.
+     * 2. The file's own types, in their declared spelling, since Apex names are case-insensitive but
+     *    TypeScript names aren't.
+     * 3. A custom object (`Invoice__c`), named with the namespace of the code it's in.
+     * 4. A name a library type has (see library.ts): the project's types and SObjects, which shadow it,
+     *    then the library's namespaces in their configured order, through registries.
+     * 5. A library type through its namespace (`System.Exception`). Apex's primitive types are System's
+     *    (`System.String`), and a name in Schema that's no library type is an SObject (`Schema.Account`).
+     * 6. Any other name, as written in the Apex namespace (the project's classes in other files, and
+     *    standard objects).
+     *
+     * An installed package's class can't see the project's classes, and its copy may not have what it
+     * refers to, so its names are its package's types when the copy has them (`RollupSummary`,
+     * `RollupController.Result`), then library types and SObjects, and `unknown` otherwise, never an error
+     * in code that isn't the project's to fix.
+     *
+     * A reference that looks through registries is a conditional type, written where it's used (see
+     * `#lookup`).
+     *
+     * @param base whether the reference is a class's base class, which an interface can only extend by
+     *   name and which can't be `unknown`: a name a package's class can't find is `{}` instead
+     */
+    resolve(parts, { base = false } = {}) {
+        const unknown = base ? "{}" : "unknown";
+        const [first, ...rest] = parts;
+        if (first === undefined) {
+            return "";
+        }
+        const { projectNamespace, packageNamespace, className, nestedTypes } = this.#options;
+        // the namespace the code is in, whose custom objects it names without a namespace
+        const ownNamespace = packageNamespace ?? projectNamespace;
+        const inPackage = packageNamespace !== undefined;
+        // 1. through a namespace
+        if (inPackage && rest.length > 0 && first.toLowerCase() === packageNamespace.toLowerCase()) {
+            // the class itself, or another of the package's, which the copy may not have
+            return rest[0].toLowerCase() === className.toLowerCase()
+                ? this.resolve(rest, { base })
+                : this.#lookup(rest, this.#packageLookup(rest, unknown), base);
+        }
+        if (projectNamespace !== undefined && rest.length > 0 && first.toLowerCase() === projectNamespace.toLowerCase()) {
+            return this.resolve(rest, { base });
+        }
+        // 2. the file's own types
+        if (first.toLowerCase() === className.toLowerCase()) {
+            return this.qualifyOwn([className, ...rest.map((part) => nestedTypes.get(part.toLowerCase()) ?? part)]);
+        }
+        const nested = rest.length === 0 ? nestedTypes.get(first.toLowerCase()) : undefined;
+        if (nested !== undefined) {
+            return this.qualifyOwn([className, nested]);
+        }
+        if (rest.length === 0) {
+            // 3. a custom object, which a package's copy may refer to without its definition
+            const custom = recordName(first, ownNamespace);
+            if (custom !== first) {
+                return inPackage ? this.#lookup([custom], this.#sobjectLookup(custom, unknown), base) : this.qualify([custom]);
+            }
+            // 4. a name a library type has
+            const steps = apexLibrary.resolve(first);
+            if (!inPackage) {
+                return steps === undefined ? this.qualify([first]) : this.#lookup([first], this.#libraryLookup(first, steps, true), base);
+            }
+            return this.#lookup([first], this.#packageLookup([first], steps === undefined ? this.#sobjectLookup(first, unknown) : this.#libraryLookup(first, steps, false)), base);
+        }
+        // 5. a library type through its namespace
+        const namespace = apexLibrary.namespace(first);
+        const [name] = rest;
+        if (namespace !== undefined && name !== undefined && rest.length === 1) {
+            const primitive = namespace.name === "System" ? PRIMITIVE_TYPES[name.toLowerCase()] : undefined;
+            if (primitive !== undefined) {
+                return primitive;
+            }
+            const ref = apexLibrary.type(namespace.name, name);
+            if (ref !== undefined) {
+                return this.#libraryReference(ref);
+            }
+            if (namespace.sobjects) {
+                const sobject = recordName(name, ownNamespace);
+                return inPackage ? this.#lookup([sobject], this.#sobjectLookup(sobject, unknown), base) : this.qualify([sobject]);
+            }
+        }
+        // 6. any other name: in a package, another of its classes' nested types, or another package's type
+        return inPackage ? this.#lookup(parts, this.#packageLookup(parts, unknown), base) : this.qualify(parts);
+    }
+    /**
+     * The declarations the file's references need, in a block of their own, or "" without any: the
+     * library types they use (and their base classes), the registries they read, and the file's own type
+     * in `ownRegistry`, if given. Other files declare the same library types and registries, which merge.
+     */
+    declarations(ownName, ownRegistry) {
+        if (this.#libraryTypes.size === 0 && this.#registries.size === 0 && ownRegistry === undefined) {
+            // a package's registry is declared by its classes' files themselves, so its aliases can be all there is
+            return this.#aliasDeclarations();
+        }
+        // base classes are declared too
+        for (const ref of this.#libraryTypes.values()) {
+            const base = ref.type.kind === "class" ? ref.type.extends : undefined;
+            const [namespace, name] = base?.split(".") ?? [];
+            const baseRef = namespace !== undefined && name !== undefined ? apexLibrary.type(namespace, name) : undefined;
+            if (baseRef !== undefined) {
+                this.#libraryReference(baseRef);
+            }
+        }
+        const { namespace: apexNamespace } = this.#options;
+        const indent = apexNamespace === null ? "" : "  ";
+        const lines = [];
+        for (const registry of new Set([...this.#registries, ...(ownRegistry === undefined ? [] : [ownRegistry])])) {
+            lines.push(registry === ownRegistry ? registration(indent, registry, [ownName]) : `${indent}interface ${registry} {}\n`);
+        }
+        const byNamespace = new Map();
+        for (const ref of this.#libraryTypes.values()) {
+            byNamespace.set(ref.namespace, [...(byNamespace.get(ref.namespace) ?? []), ref]);
+        }
+        for (const [namespace, refs] of [...byNamespace].sort(([a], [b]) => a.localeCompare(b))) {
+            lines.push(`${indent}${indent === "" ? "declare " : ""}namespace ${namespace} {\n`);
+            const enums = [];
+            for (const { name, type } of refs.sort((a, b) => a.name.localeCompare(b.name))) {
+                if (type.kind === "enum") {
+                    enums.push(`${name}: ${type.values.length === 0 ? "never" : type.values.map((value) => JSON.stringify(value)).join(" | ")};`);
+                    continue;
+                }
+                const bases = [
+                    ...(type.kind === "class" && type.extends !== undefined ? [this.qualify(type.extends.split("."))] : []),
+                    // its properties' JSON names aren't known exactly, so any can be read
+                    ...(type.kind === "interface" || (type.kind === "class" && type.open) ? ["Record<string, unknown>"] : []),
+                ];
+                lines.push(`${indent}  interface ${name}${bases.length === 0 ? "" : ` extends ${bases.join(", ")}`} {}\n`);
+            }
+            if (enums.length > 0) {
+                lines.push(`${indent}  interface __lwcEnums {\n${enums.map((line) => `${indent}    ${line}\n`).join("")}${indent}  }\n`);
+            }
+            lines.push(`${indent}}\n`);
+        }
+        const libraryBlock = apexNamespace === null ? lines.join("") : `declare namespace ${apexNamespace} {\n${lines.join("")}}\n`;
+        return libraryBlock + this.#aliasDeclarations();
+    }
+    /** The file's aliases (see `#alias`), in a namespace named for its class, or "" without any. */
+    #aliasDeclarations() {
+        if (this.#aliases.size === 0) {
+            return "";
+        }
+        const aliases = [...this.#aliases].map(([type, name]) => `  type ${name} = ${type};\n`).join("");
+        return `declare namespace ${this.#aliasNamespace} {\n${aliases}}\n`;
+    }
+    /**
+     * The namespace the file's aliases are in: one of their own for the file's class, in the namespace of
+     * aliases for classes (`Apex.__lwcRefs.Billing`, `Apex.dlrs.__lwcRefs.RollupController`) or for SObject
+     * definitions (`Apex.__lwcSObjectRefs.Account`). A class has one file, and so does an SObject
+     * definition, so no other file declares aliases in it, even when a class and an SObject share a name.
+     * Being apart from the class's own namespace also keeps them out of editors' suggestions for it.
+     */
+    get #aliasNamespace() {
+        const { isSobject, className } = this.#options;
+        const scope = isSobject ? this.qualify(["__lwcSObjectRefs"]) : this.qualifyOwn(["__lwcRefs"]);
+        return `${scope}.${className}`;
+    }
+    /**
+     * A reference that looks through registries, of type `type`: written where it's used, in parentheses
+     * so it can be an array's element or part of an intersection; or, for a base class, as an alias, since
+     * an interface can only extend a type by name.
+     */
+    #lookup(parts, type, base) {
+        return base ? this.#alias(parts, type) : `(${type})`;
+    }
+    /** An alias for `type`, a base class's resolved type, named for the reference (`base`). */
+    #alias(parts, type) {
+        let name = this.#aliases.get(type);
+        if (name === undefined) {
+            let base = parts
+                .join("_")
+                .toLowerCase()
+                .replace(/[^\w$]/g, "_");
+            // names a type can't have, such as `object`, or a reserved word
+            if (TYPE_KEYWORDS.has(base) || RESERVED_WORDS.has(base)) {
+                base = `${base}_`;
+            }
+            const taken = new Set(this.#aliases.values());
+            name = base;
+            for (let n = 2; taken.has(name); n++) {
+                name = `${base}_${n}`;
+            }
+            this.#aliases.set(type, name);
+        }
+        return `${this.#aliasNamespace}.${name}`;
+    }
+    /** A library type, which is declared with the file's declarations. */
+    #libraryReference(ref) {
+        this.#libraryTypes.set(`${ref.namespace}.${ref.name}`.toLowerCase(), ref);
+        return ref.type.kind === "enum"
+            ? `${this.qualify([ref.namespace, "__lwcEnums"])}[${JSON.stringify(ref.name)}]`
+            : this.qualify([ref.namespace, ref.name]);
+    }
+    /**
+     * The SObjects' registry (`Apex.__lwcSObjects`), which every declared SObject adds itself to, by
+     * lower-cased name: what `registryLookup` reads to refer to an SObject that may not be declared.
+     */
+    get sobjectsRegistry() {
+        return this.#registry(SOBJECTS_REGISTRY);
+    }
+    /** A registry in the Apex namespace, which the file's declarations then declare. */
+    #registry(name) {
+        this.#registries.add(name);
+        return this.qualify([name]);
+    }
+    /**
+     * A name a library type has: the project's type of that name if it has one (unless `projectClasses` is
+     * false, in a package's class), else what `steps` find (an SObject, or the library type).
+     */
+    #libraryLookup(name, steps, projectClasses) {
+        const resolve = ([step, ...rest]) => {
+            if (step === undefined) {
+                return "never";
+            }
+            return step.kind === "type"
+                ? this.#libraryReference(step.ref)
+                : registryLookup(this.#registry(SOBJECTS_REGISTRY), name, resolve(rest));
+        };
+        return projectClasses ? registryLookup(this.#registry(CLASSES_REGISTRY), name, resolve(steps)) : resolve(steps);
+    }
+    /** An SObject that may not be declared: `unknown` when no file declares it, rather than an error. */
+    #sobjectLookup(name, unknown) {
+        return registryLookup(this.#registry(SOBJECTS_REGISTRY), name, unknown);
+    }
+    /**
+     * In a package's class, the package's type of a name (`RollupSummary`, `RollupController.Result`) when
+     * it has one, and otherwise `otherwise`. Its types are in its registry, which each of its classes' files
+     * adds itself and its nested types to, by lower-cased dotted name.
+     */
+    #packageLookup(path, otherwise) {
+        return registryLookup(this.qualifyOwn([CLASSES_REGISTRY]), path.join("."), otherwise);
+    }
+}

package/dist/apex/sobjects.d.ts

@@ -0,0 +1,45 @@
+import type { TextBuilder, SourceRange } from "../text-builder.ts";
+export interface SObjectProperty {
+    name: string;
+    /** TypeScript type, with Apex types referenced in the namespace they're declared in (see `qualifyApex`) */
+    type: string;
+    nameRange?: SourceRange | null;
+    typeRange?: SourceRange | null;
+    /** JSDoc lines */
+    doc?: (string | undefined)[];
+}
+export interface SObjectInterface {
+    name: string;
+    nameRange?: SourceRange | null;
+    /** JSDoc lines */
+    doc?: (string | undefined)[];
+    properties: SObjectProperty[];
+}
+/**
+ * The standard fields of an object, by the kind its API name's suffix identifies. They match the types
+ * the Salesforce extensions' SObject definitions (`.sfdx/tools/sobjects`) give them, since a property
+ * declared in both must have the same type. Standard objects' fields vary, so only `Id` is declared.
+ * `owned` is whether records have an owner, which children of a master-detail relationship
+ * (`ControlledByParent` sharing) don't; only the owner's Id is declared (see below). The users who
+ * created and last modified a record are `User`s in `apexNamespace`.
+ */
+export declare function standardFields(objectName: string, { owned, apexNamespace }: {
+    owned: boolean;
+    apexNamespace: string | null;
+}): SObjectProperty[];
+/**
+ * The TypeScript type of a field, or undefined when it can't be known from the field alone (such as a
+ * roll-up summary of a field's minimum) or the type isn't supported. Such fields are left undeclared
+ * rather than risk a type that conflicts with the generated SObject definitions.
+ */
+export declare function fieldTsType(fieldType: string | undefined, summaryOperation: string | undefined): string | undefined;
+/**
+ * Documentation shared by a field's schema module and its Apex property: its description, and the
+ * help text users see next to it.
+ */
+export declare function fieldDoc(description: string | undefined, inlineHelpText: string | undefined): (string | undefined)[];
+/**
+ * Declares SObject interfaces in the Apex namespace (or globally, when `namespace` is null). Interfaces
+ * merge across files, so each object and field file declares the part of a type it knows about.
+ */
+export declare function addSObjectInterfaces(builder: TextBuilder, namespace: string | null, interfaces: SObjectInterface[]): void;

package/dist/apex/sobjects.js

@@ -0,0 +1,141 @@
+// SObject record types: the interfaces object and field metadata declare in the Apex namespace.
+import { docTag, jsDoc } from "../jsdoc.js";
+import { qualifyApex, registration, SOBJECTS_REGISTRY } from "./namespace.js";
+/**
+ * The standard fields of an object, by the kind its API name's suffix identifies. They match the types
+ * the Salesforce extensions' SObject definitions (`.sfdx/tools/sobjects`) give them, since a property
+ * declared in both must have the same type. Standard objects' fields vary, so only `Id` is declared.
+ * `owned` is whether records have an owner, which children of a master-detail relationship
+ * (`ControlledByParent` sharing) don't; only the owner's Id is declared (see below). The users who
+ * created and last modified a record are `User`s in `apexNamespace`.
+ */
+export function standardFields(objectName, { owned, apexNamespace }) {
+    const user = qualifyApex(apexNamespace, ["User"]);
+    let fields;
+    if (objectName.endsWith("__c")) {
+        fields = [
+            ["Id", "string"],
+            ["Name", "string"],
+            ["IsDeleted", "boolean"],
+            ["CreatedById", "string"],
+            ["CreatedBy", user],
+            ["CreatedDate", "string"],
+            ["LastModifiedById", "string"],
+            ["LastModifiedBy", user],
+            ["LastModifiedDate", "string"],
+            ["SystemModstamp", "string"],
+            // The owner (a user or a queue) is left to the SObject definition, whose type for it depends on the
+            // org: its targets, when the project has the object's describe, and `SObject` otherwise.
+            ...(owned ? [["OwnerId", "string"]] : []),
+        ];
+    }
+    else if (objectName.endsWith("__mdt")) {
+        fields = [
+            ["Id", "string"],
+            ["DeveloperName", "string"],
+            ["MasterLabel", "string"],
+            ["Label", "string"],
+            ["Language", "string"],
+            ["NamespacePrefix", "string"],
+            ["QualifiedApiName", "string"],
+            ["SystemModstamp", "string"],
+        ];
+    }
+    else if (objectName.endsWith("__e")) {
+        fields = [
+            ["ReplayId", "string"],
+            ["EventUuid", "string"],
+            ["CreatedById", "string"],
+            ["CreatedBy", user],
+            ["CreatedDate", "string"],
+        ];
+    }
+    else {
+        fields = [["Id", "string"]];
+    }
+    return fields.map(([name, type]) => ({ name, type }));
+}
+/**
+ * TypeScript types of field types, as LWC receives their values (see the Apex types in resolution.ts).
+ * Lookups hold the related record's Id; their related records are declared separately.
+ */
+const FIELD_TYPES = {
+    autonumber: "string",
+    checkbox: "boolean",
+    currency: "number",
+    date: "string",
+    datetime: "string",
+    email: "string",
+    encryptedtext: "string",
+    hierarchy: "string",
+    html: "string",
+    lookup: "string",
+    masterdetail: "string",
+    metadatarelationship: "string",
+    multiselectpicklist: "string",
+    number: "number",
+    percent: "number",
+    phone: "string",
+    picklist: "string",
+    text: "string",
+    textarea: "string",
+    longtextarea: "string",
+    time: "string",
+    url: "string",
+};
+/**
+ * The TypeScript type of a field, or undefined when it can't be known from the field alone (such as a
+ * roll-up summary of a field's minimum) or the type isn't supported. Such fields are left undeclared
+ * rather than risk a type that conflicts with the generated SObject definitions.
+ */
+export function fieldTsType(fieldType, summaryOperation) {
+    const type = fieldType?.toLowerCase();
+    if (type === "summary") {
+        const operation = summaryOperation?.toLowerCase();
+        return operation === "count" || operation === "sum" ? "number" : undefined;
+    }
+    return type === undefined ? undefined : FIELD_TYPES[type];
+}
+/**
+ * Documentation shared by a field's schema module and its Apex property: its description, and the
+ * help text users see next to it.
+ */
+export function fieldDoc(description, inlineHelpText) {
+    return [docTag("description", description), docTag("inlineHelpText", inlineHelpText)];
+}
+/**
+ * Declares SObject interfaces in the Apex namespace (or globally, when `namespace` is null). Interfaces
+ * merge across files, so each object and field file declares the part of a type it knows about.
+ */
+export function addSObjectInterfaces(builder, namespace, interfaces) {
+    const indent = namespace === null ? "" : "  ";
+    if (namespace !== null) {
+        builder.write(`declare namespace ${namespace} {\n`);
+    }
+    for (const { name, nameRange, doc, properties } of interfaces) {
+        builder.write(`${jsDoc(indent, doc ?? [])}${indent}interface `);
+        builder.writeMapped(name, nameRange ?? null);
+        if (properties.length === 0) {
+            builder.write(" {}\n");
+            continue;
+        }
+        builder.write(" {\n");
+        for (const property of properties) {
+            builder.write(`${jsDoc(`${indent}  `, property.doc ?? [])}${indent}  `);
+            builder.writeMapped(property.name, property.nameRange ?? null);
+            builder.write("?: ");
+            builder.writeMapped(property.type, property.typeRange ?? null);
+            builder.write(";\n");
+        }
+        builder.write(`${indent}}\n`);
+    }
+    // every SObject registers, so references can look one up without an error when it isn't declared:
+    // those whose names library types have shadow them (`Location`, over `System.Location`), and installed
+    // packages' classes fall back to them
+    if (interfaces.length > 0) {
+        builder.write(registration(indent, SOBJECTS_REGISTRY, interfaces.map(({ name }) => name)));
+    }
+    if (namespace !== null) {
+        builder.write("}\n");
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,16 @@
+import type { ConvertOptions, InaccessibleApexProperties } from "./types.ts";
+/** `convert`'s options as the converters use them: defaults applied, and an empty namespace as none. */
+export interface ConversionContext {
+    /** The namespace Apex types are declared in (`"Apex"` by default), or `null` to declare them globally. */
+    readonly apexNamespace: string | null;
+    /** What becomes of Apex classes' fields LWC can't read (`"include as deprecated"` by default). */
+    readonly inaccessibleApexProperties: InaccessibleApexProperties;
+    /** The project's namespace, or undefined without one. */
+    readonly projectNamespace: string | undefined;
+}
+/**
+ * Applies `convert`'s defaults, and throws for a namespace that would make the declarations invalid: an
+ * `apexNamespace` that isn't a dotted TypeScript identifier, or a `projectNamespace` that isn't a
+ * namespace prefix, and for an `inaccessibleApexProperties` that isn't one of its values.
+ */
+export declare function conversionContext(options?: ConvertOptions): ConversionContext;

package/dist/context.js

@@ -0,0 +1,28 @@
+import { DEFAULT_APEX_NAMESPACE } from "./apex/namespace.js";
+import { isIdentifier, NAMESPACE_RESERVED_WORDS } from "./identifiers.js";
+const INACCESSIBLE_APEX_PROPERTIES = ["include", "exclude", "include as deprecated"];
+/**
+ * A Salesforce namespace prefix: letters, digits and single underscores, starting with a letter and not
+ * ending with an underscore.
+ */
+const NAMESPACE_PREFIX = /^[A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)*$/;
+/**
+ * Applies `convert`'s defaults, and throws for a namespace that would make the declarations invalid: an
+ * `apexNamespace` that isn't a dotted TypeScript identifier, or a `projectNamespace` that isn't a
+ * namespace prefix, and for an `inaccessibleApexProperties` that isn't one of its values.
+ */
+export function conversionContext(options) {
+    const apexNamespace = options?.apexNamespace === undefined ? DEFAULT_APEX_NAMESPACE : options.apexNamespace;
+    if (apexNamespace !== null && !apexNamespace.split(".").every((part) => isIdentifier(part) && !NAMESPACE_RESERVED_WORDS.has(part))) {
+        throw new TypeError(`apexNamespace ${JSON.stringify(apexNamespace)} isn't a namespace TypeScript can declare; use dotted identifiers (such as "Acme.Apex"), or null`);
+    }
+    const inaccessibleApexProperties = options?.inaccessibleApexProperties ?? "include as deprecated";
+    if (!INACCESSIBLE_APEX_PROPERTIES.includes(inaccessibleApexProperties)) {
+        throw new TypeError(`inaccessibleApexProperties must be one of ${INACCESSIBLE_APEX_PROPERTIES.map((value) => JSON.stringify(value)).join(", ")}, but got ${JSON.stringify(inaccessibleApexProperties)}`);
+    }
+    const projectNamespace = options?.projectNamespace?.trim() || undefined;
+    if (projectNamespace !== undefined && !NAMESPACE_PREFIX.test(projectNamespace)) {
+        throw new TypeError(`projectNamespace ${JSON.stringify(projectNamespace)} isn't a Salesforce namespace prefix`);
+    }
+    return { apexNamespace, inaccessibleApexProperties, projectNamespace };
+}

package/dist/converters/apex-class.d.ts

@@ -0,0 +1,7 @@
+import type { ConversionContext } from "../context.ts";
+import type { ApexClassComponent, ConversionOutput } from "../types.ts";
+/**
+ * Converts an Apex class. The Apex parser loads on the first class (reading its WebAssembly from disk),
+ * once: concurrent conversions share the load, and later ones reuse the parser.
+ */
+export declare function ApexClass(comp: ApexClassComponent, context: ConversionContext): Promise<ConversionOutput>;

package/dist/converters/apex-class.js

@@ -0,0 +1,23 @@
+import { getApexParser } from "web-tree-sitter-sfapex";
+import { convertApexFile } from "../apex/file.js";
+import { importNameParts, metadataName } from "../names.js";
+let apexParser;
+/**
+ * Converts an Apex class. The Apex parser loads on the first class (reading its WebAssembly from disk),
+ * once: concurrent conversions share the load, and later ones reuse the parser.
+ */
+export async function ApexClass(comp, context) {
+    apexParser ??= getApexParser();
+    const prsr = await apexParser;
+    const isSobject = comp.isSobject === true;
+    return (convertApexFile(prsr, comp.content, {
+        isSobject,
+        apexNamespace: context.apexNamespace,
+        projectNamespace: context.projectNamespace,
+        // a class of another namespace (an installed package's) is named for it, as `dlrs__RollupController.cls`;
+        // an SObject definition's name is its object's
+        packageNamespace: isSobject ? undefined : importNameParts(metadataName(comp.path), context.projectNamespace).namespace,
+        polymorphicTargets: new Map(Object.entries(isSobject ? (comp.polymorphicTargets ?? {}) : {}).map(([name, targets]) => [name.toLowerCase(), targets])),
+        inaccessibleProperties: context.inaccessibleApexProperties,
+    }) ?? { text: "", mapData: [] });
+}

package/dist/converters/content-asset.d.ts

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