Declarations Errors in cloud.d.ts

[ericdrobinson]

If you convert the jsconfig.json file to a tsconfig.json file, set strict: true, and then open the assets.d.ts file (in VSCode, at least), you are presented with the following errors:

• Enum type 'ArtifactType' has members with initializers that are not literals. ts(2535) [9, 15]
• Enum type 'ArtifactType' has members with initializers that are not literals. ts(2535) [52, 15]

These refer to the fact that you have the following in a type declaration:

type PrototypeArtifact = {
    type: ArtifactType.PROTOTYPE,  // <-- Can't do this with ambient enums!

The problem here is that you are assigning a value to the type PrototypeArtifact.type but that you have not explicitly said what ArtifactType.PROTOTYPE is actually equivalent to. When you declare an ambient enum, you provide information on the names of each valid type but not the value. While this works for usage of that enum entry, you cannot use it in another ambient type declaration as you do above.

That said, enums in JavaScript are simple objects and we can easily see what their values are with a quick test (though it would be nice if Adobe simply documented them...):

// Outputs:
// { PROTOTYPE: 'prototype', SPECS: 'specs' }
console.log(require('cloud').ArtifactType);
// Outputs:
// { WEB: 'Web', IOS: 'iOS', ANDROID: 'Android' }
console.log(require('cloud').TargetPlatform);
// Outputs:
// { LINKABLE: 'linkable',
//   PASSWORD_PROTECTED: 'passwordProtected',
//   INVITE_ONLY: 'inviteOnly' }
console.log(require('cloud').AccessLevel);

Cool. With that information in hand, we can write the enums as follows:

export enum ArtifactType {
    PROTOTYPE   = 'prototype',
    SPECS       = 'specs'
}

export enum TargetPlatform  {
    WEB     = 'Web',
    IOS     = 'iOS',
    ANDROID = 'Android'
}

export enum AccessLevel {
    LINKABLE            = 'linkable',
    PASSWORD_PROTECTED  = 'passwordProtected',
    INVITE_ONLY         = 'inviteOnly'
}

Once those definitions are added the errors go away!

Definitions Out-of-Sync, Though...

It should also be noted that the declarations in cloud.d.ts appear to be out-of-sync with those in the current documentation.

In the current version, the PrototypeArtifact and SpecsArtifact types are effectively "extensions" of a new BaseSharedArtifact. It also appears that there's a documentation bug for the description of the BaseSharedArtifact.type member in that it appears to suggest that it is constantly ArtifactType.PROTOTYPE. I'd be willing to bet my hat that that is a copy-pasta error.

While it is possible to "extend" a type declaration, I would highly recommend converting these types into interfaces. Adobe's use of "typedef" in the documentation simply suggests that "this is the shape of an object". You can use a TypeScript interface to match that purpose (especially when typedef 'inheritance' is suggested).

Note that if you do adjust the declarations and unify the two Artifact types with the BaseSharedArtifact, you could get away without adding the enum values as explained above. It might be better, however, to do something like:

interface BaseSharedArtifact {
    type: ArtifactType;
    // Other common declarations...
}

interface PrototypeArtifact extends BaseSharedArtifact {
    type: ArtifactType.PROTOTYPE;
    // Prototype-specific declarations...
}

interface SpecsArtifact extends BaseSharedArtifact {
    type: ArtifactType.SPECS;
    // Specs-specific declarations...
}

At which point you would still need those enum values.