@cap-js/cds-typer 0.2.5-beta.1

package/lib/components/inline.js

@@ -0,0 +1,217 @@
+const { SourceFile, Buffer } = require('../file')
+
+/**
+ * Inline declarations of types can come in different flavours.
+ * The compiler can therefore be adjusted to print out one or the other
+ * by plugging different implementations of this abstract class into
+ * their resolution mechanism.
+ */
+class InlineDeclarationResolver {
+
+    /**
+     * @param {string} name
+     * @param {import('../compile').TypeResolveInfo} type
+     * @param {import('../file').Buffer} buffer
+     * @param {string} statementEnd
+     * @private
+     * @abstract
+     */
+    printInlineType(name, type, buffer, statementEnd) { /* abstract */ }
+
+    /**
+     * Attempts to resolve a type that could reference another type.
+     * @param {any} val 
+     * @param {import('../compile').TypeResolveInfo} into @see Visitor.resolveType
+     * @param {SourceFile} file temporary file to resolve dummy types into.
+     * @public
+     */
+    resolveInlineDeclaration(items, into, relativeTo) {
+        const dummy = new SourceFile(relativeTo.path.asDirectory())
+        dummy.classes.currentIndet = relativeTo.classes.currentIndent
+        dummy.classes.add('{')
+        dummy.classes.indent()
+
+        into.structuredType = {}
+        for (const [subname, subelement] of Object.entries(items ?? {})) {
+            // in inline definitions, we sometimes have to resolve first
+            // FIXME: does this tie in with how we sometimes end up with resolved typed in resolveType()?
+            const se = (typeof subelement === 'string')
+                ? this.visitor._resolveTypeName(subelement)
+                : subelement
+            into.structuredType[subname] = this.visitor.visitElement(subname, se, dummy)
+        }
+        dummy.classes.outdent()
+        dummy.classes.add('}')
+        // FIXME: pass as param
+        //dummy.classes.add(element.constructor.name === 'array' ? '}[]' : '}')
+        into.imports = (into.imports ?? []).concat(...Object.values(dummy.imports))
+        into.isInlineDeclaration = true
+        //into.structuredType = dummy
+        Object.defineProperty(into, 'type', {
+            get: () => dummy.classes.join('\n')
+        })
+    }
+
+    /**
+     * Visits a single element in an entity.
+     * @param {string} name name of the element
+     * @param {import('../compile').CSN} element CSN data belonging to the the element.
+     * @param {SourceFile} file the namespace file the surrounding entity is being printed into.
+     * @param {Buffer} [buffer] buffer to add the definition to. If no buffer is passed, the passed file's class buffer is used instead.
+     * @public
+     */
+    visitElement(name, element, file, buffer = file.classes) {
+        this.depth++
+        for (const d of this.visitor._docify(element.doc)) {
+            buffer.add(d)
+        }
+        const type = this.visitor.resolveAndRequire(element, file)
+        this.depth--
+        if (this.depth === 0) {
+            this.printInlineType(name, type, buffer)
+        }        
+        return type
+    }
+
+    /**
+     * Separator between value V and type T: `v : T`.
+     * Depending on the visitor's setting, this is may be `?:` for optional
+     * properties or `:` for required properties.
+     * @returns {'?'|':'}
+     */
+    getPropertyTypeSeparator() {
+        return this.visitor.options.propertiesOptional ? '?:' : ':'
+    }
+
+    /** @param {import('../compile').Visitor} visitor */
+    constructor(visitor) {
+        this.visitor = visitor
+        // type resolution might recurse. This indicator is used to determine
+        // when the type has been fully resolve (depth === 0) and should be printed
+        this.depth = 0
+    }
+
+    /**
+     * Produces a string representation of how to produce a [Typescript type lookup](https://www.typescriptlang.org/docs/handbook/2/indexed-access-types.html#handbook-content)
+     * under the current configuration.
+     * @example
+     * ```ts
+     * type T = {
+     *   a: {
+     *     b: number
+     *   }
+     * }
+     * 
+     * T['a']['b']  // number
+     * ```
+     * but especially with inline declarations, the access will differ between flattened and nested representations.
+     * @param {string[]} members a list of members, in the above example it would be `['a', 'b']`
+     * @returns {string} type access string snippet. In the above sample, we would return `"['a']['b']"`
+     * @public
+     * @abstract
+     */
+    getTypeLookup(members) { /* abstract */ }
+}
+
+/**
+ * Resolves inline declarations in a flat fashion.
+ * @example
+ * ```cds
+ * // cds
+ * entity E {
+ *   x: { a: Integer; b: String; }
+ * }
+ * ```
+ * ↓
+ * ```ts
+ * // ts
+ * class E {
+ *   x_a: number;
+ *   x_b: string;
+ * }
+ * ```
+ */
+class FlatInlineDeclarationResolver extends InlineDeclarationResolver {
+    constructor(visitor) { super(visitor) }
+
+    prefix(p) {
+        return p ? `${p}_` : ''
+    }
+
+    flatten(prefix, type) {
+        return type.typeInfo.structuredType
+            ? Object.entries(type.typeInfo.structuredType).map(([k,v]) => this.flatten(`${this.prefix(prefix)}${k}`, v))
+            : [`${prefix} ${this.getPropertyTypeSeparator()} ${type.typeName}`]
+    }
+
+    printInlineType(name, type, buffer) {
+        for(const prop of this.flatten(name, type).flat()) {
+            buffer.add(prop)
+        }
+    }
+
+    getTypeLookup(members)  {
+        return `['${members.join('_')}']`
+    }
+}
+
+/**
+ * Resolves inline declarations to a structured type.
+ * @example
+ * ```cds
+ * // cds
+ * entity E {
+ *   x: { a: Integer; b: String; }
+ * }
+ * ```
+ * ↓
+ * ```ts
+ * // ts
+ * class E {
+ *   x: { a: number; b: string; }
+ * }
+ * ```
+ */
+class StructuredInlineDeclarationResolver extends InlineDeclarationResolver {
+    constructor(visitor) { 
+        super(visitor)
+        this.printDepth = 0 
+    }
+
+    flatten(name, type, buffer, statementEnd = ';') {
+        // in addition to the regular depth during resolution, we may have another depth while printing
+        // nested types on which the line ending depends
+        this.printDepth++
+        const lineEnding = this.printDepth > 1 ? ',' : statementEnd
+        if (type.typeInfo.structuredType) {
+            const prefix = name ? `${name} ${this.getPropertyTypeSeparator()}`: ''
+            buffer.add(`${prefix} {`)
+            buffer.indent()
+            for (const [n, t] of Object.entries(type.typeInfo.structuredType)) {
+                this.flatten(n, t, buffer)
+            }
+            buffer.outdent()
+            buffer.add(`}${lineEnding}`)
+        } else {
+            buffer.add(`${name} ${this.getPropertyTypeSeparator()} ${type.typeName}${lineEnding}`)
+        }
+        this.printDepth--
+        return buffer
+    }
+
+    printInlineType(name, type, buffer, statementEnd) {
+        // FIXME: indent not quite right
+        const sub = new Buffer()
+        sub.currentIndent = buffer.currentIndent
+        buffer.add(this.flatten(name, type, sub, statementEnd).join())
+    }
+
+    getTypeLookup(members)  {
+        return members.map(m => `['${m}']`).join('')
+    }
+}
+
+module.exports = {
+    FlatInlineDeclarationResolver,
+    StructuredInlineDeclarationResolver
+}

package/lib/file.d.ts

@@ -0,0 +1,208 @@
+type KVs = [string, string][]
+type Namespace = {[key: string]: Buffer}
+type ActionParams = [string, string][]
+type AsDirectoryParams = {relative: string | undefined, local: boolean, posix: boolean}
+
+/**
+ * String buffer to conveniently append strings to.
+ */
+ export class Buffer {
+    public parts: string[];
+    private indentation: string;
+    private currentIndent: string;
+
+    constructor(indentation: string);
+
+    /**
+     * Indents by the predefined spacing.
+     */
+    indent(): void;
+
+    /**
+     * Removes one level of indentation.
+     */
+    outdent(): void; 
+
+    /**
+     * Concats all elements in the buffer into a single string.
+     * @param glue string to intersperse all buffer contents with
+     * @returns string spilled buffer contents.
+     */
+    join(glue: string): string;
+
+    /**
+     * Clears the buffer.
+     */
+    clear(): void;
+
+    /**
+     * Adds an element to the buffer with the current indentation level.
+     * @param part 
+     */
+    add(part: string): void;
+}
+
+/**
+ * Convenience class to handle path qualifiers.
+ */
+export class Path {
+    private parts: string[];
+
+    /**
+     * 
+     * @param parts parts of the path. 'a.b.c' -> ['a', 'b', 'c']
+     * @param kind FIXME: currently unused
+     */
+    constructor(parts: string[], kind: string);
+
+    /**
+     * @returns the path to the parent directory. 'a.b.c'.getParent() -> 'a.b'
+     */
+    getParent(): Path;
+
+    /**
+     * Transfoms the Path into a directory path.
+     * @param relative if defined, the path is constructed relative to this directory
+     * @param local if set to true, './' is prefixed to the directory
+     * @param posix if set to true, all slashes will be forward slashes on every OS. Useful for require/ import
+     * @returns directory 'a.b.c'.asDirectory() -> 'a/b/c' (or a\b\c when on Windows without passing posix = true)
+     */
+    asDirectory(params: AsDirectoryParams): string;
+
+    /**
+     * Transforms the Path into a namespace qualifier.
+     * @returns namespace qualifier 'a.b.c'.asNamespace() -> 'a.b.c'
+     */
+    asNamespace(): string;
+
+    /**
+     * Transforms the Path into an identifier that can be used as variable name.
+     * @returns identifier 'a.b.c'.asIdentifier() -> '_a_b_c', ''.asIdentifier() -> '_'
+     */
+    asIdentifier(): string;
+
+    /**
+     * @returns true, iff the Path refers to the current working directory, aka './'
+     */
+    isCwd(relative: string | undefined): boolean;
+}
+
+/**
+ * Source file containing several buffers.
+ */
+export class SourceFile {
+    public readonly path: Path;
+    private imports: {}
+    private types: Buffer;
+    private classes: Buffer;
+    private enums: Buffer;
+    private actions: Buffer;
+    private namespaces: Namespace;
+    private classNames: {}
+    private inflections: [string, string][]
+
+    constructor(path: string);
+
+    /**
+     * Adds a pair of singular and plural inflection.
+     * These are later used to generate the singular -> plural
+     * aliases in the index.js file.
+     * @param singular singular type without namespace.
+     * @param plural plural type without namespace
+     * @param original original entity name without namespace. 
+     *        In many cases this will be the same as plural.
+     */
+    addInflection(singular: string, plural: string, original: string);
+
+    /**
+     * Adds an action definition in form of a arrow function to the file.
+     * @param name name of the action
+     * @param params list of parameters, passed as [name, type] pairs
+     * @param returns the return type of the action
+     */
+    addAction(name: string, params: ActionParams, returns: string);
+
+    /**
+     * Adds an enum to this file.
+     * @param fq fully qualified name of the enum
+     * @param name local name of the enum
+     * @param kvs list of key-value pairs
+     */
+    addEnum(fq: string, clean: string, kvs: KVs);
+
+    /**
+     * Adds an arbitrary piece of code that is added
+     * right after the imports.
+     * @param code the preamble code.
+     */
+    addPreamble(code: string);
+
+    /**
+     * Adds a type alias to this file.
+     * @param fq fully qualified name of the enum
+     * @param name local name of the enum
+     * @param rhs the right hand side of the assignment
+     */
+    addType(fq: string, clean: string, rhs: string);
+
+    /**
+     * Adds a class to this file. 
+     * This differs from writing to the classes buffer,
+     * as it is just a cache to collect all classes that 
+     * are supposed to be present in this file. 
+     * @param clean cleaned name of the class 
+     * @param fq fully qualified name, including the namespace
+     */
+    addClass(clean: string, fq: string): void;
+
+    /**
+     * Retrieves or creates and retrieves a sub namespace
+     * with a given name.
+     * @param name of the sub namespace.
+     * @returns the sub namespace.
+     */
+    getSubNamespace(name: string): Namespace;
+
+    /**
+     * Adds an import if it does not exist yet.
+     * @param imp qualifier for the namespace to import.
+     */
+    addImport(imp: Path): void;
+
+    /**
+     * Writes all imports to a buffer, relative to the current file.
+     * Creates a new buffer on each call, as concatenating import strings directly
+     * upon discovering them would complicate filtering out duplicate entries.
+     * @returns all imports written to a buffer.
+     */
+    getImports(): Buffer;
+
+    /**
+     * Creates one string from the buffers representing the type definitions.
+     * @returns complete file contents.
+     */
+    toTypeDefs(): string;
+
+    /**
+     * Concats the classnames to an export dictionary 
+     * to create the accompanying JS file for the typings.
+     * @returns a string containing the module.exports for the JS file.
+     */
+    toJSExports(): string;
+}
+
+/**
+ * Base definitions used throughout the typing process,
+ * such as Associations and Compositions.
+ */
+declare const baseDefinitions: SourceFile;
+
+/**
+ * Writes the files to disk. For each source, a index.d.ts holding the type definitions
+ * and a index.js holding implementation stubs is generated at the appropriate directory.
+ * Missing directories are created automatically and asynchronously.
+ * @param root root directory to prefix all directories with
+ * @param sources source files to write to disk
+ * @returns Promise that resolves to a list of all directory paths pointing to generated files.
+ */
+export function writeout(root: string, sources: SourceFile[]): Promise<string[]>;