Check or not objects in a Javascript API?

Question

I'm writing an API in JavaScript, and I'm confused whether or not I should check if the API user is passing me the correct type on which the API expects to work. Actually not the type, but if you are passing me the object with the properties on which API will work. Is it a good practice for me to issue an error if the user does not pass an object with the properties expected for the API, or should I leave this on behalf of the JavaScript compiler?

I should check the type like this:

function PackageManager() {
    this.packages = {};
}

PackageManager.prototype.addPackage = function(assetPackage) {
    Array.isArray(assetPackage) ? this.addAssetPackages(assetPackage) : this.addAssetPackage(assetPackage);
}

PackageManager.prototype.addAssetPackages = function(assetPackages) {
     for(let i = 0; i < assetPackages.length; i++) 
         this.addAssetPackage(assetPackages[i]);
}

PackageManager.prototype.addAssetPackage = function(assetPackage) {
    if (!this.isAssetPackage(assetPackage))
        throw new TypeError('You are passing the argument "'+ assetPackage +'" and the addPackage function expects an AssetPackage.');
    this.packages[assetPackage.name] = {
        name: assetPackage.name,
        assets: assetPackage.assets
    };
}

PackageManager.prototype.isAssetPackage = function(val) {
    return (this.isObject(val) && val.name && val.assets ? true : false);
}

PackageManager.prototype.isObject = function(val) {
    return (typeof val === "object" && val !== null ? true : false);
}
export default PackageManager;

or simply let the API user handle the compiler:

function PackageManager() {
    this.packages = {};
}

PackageManager.prototype.addPackage = function(assetPackage) {
     Array.isArray(assetPackage) ? this.addPackages(assetPackage) : addAssetPackage(assetPackage);
}

PackageManager.prototype.addPackages = function(assetPackages) {
     for(let i = 0; i < assetPackages.length; i++)
         addAssetPackage(assetPackages[i]);
}

PackageManager.prototype.addAssetPackage = function(assetPackage) {
    this.packages[assetPackage.name] = {
        name: assetPackage.name,
        assets: assetPackage.assets
    };
}

export default PackageManager;

how do you handle this case in your JavaScript APIs?

Answer 1

Being that JavaScript is a dynamically typed language, you can assume the users of that language know it is dynamically-typed. If you expect a certain kind of object, document it either in the how-to guides for your API, or using something like JsDoc.

The constant checking of data types at runtime is replicating what a compiler does. If you need to verify this, you need a strongly typed language. If your target platform does not support a strongly typed language, then you don't need to check data types.

1. Document what you expect
2. Add error handling where it makes business sense
3. Do not add error handling if it would normally be verified by a compiler in a strongly typed language
4. Assume your users know they are not using a strongly typed language
5. Tell them to RTFM when something wonky goes wrong

Oh, and make sure the "F" in RTFM means "Friendly" and "well-written."

There is 1 exception, however. And this exception is perfectly illustrated in your PackageManager#addPackage method. If you want to support method overloading in a language that does not support method overloading, you absolutely must check data types.

Answer 2

In this particular example code, the only required field to not blow up is name, because it gets used in

this.packages[assetPackage.name] = ...

The other field, assets, could be null (or missing) and the code would run fine. Now, perhaps, you want to ensure that assets also exists.

How I would document this

1. Document that you expect objects with a required name field,
2. If desired, document that other fields, like assets and foobar, are required.

How I would "validate"

1. Test for the required fields, but don't bother with typeof val === "object" because that is, well, pretty pointless here. You would make that test if you want to handle a String or a Number differently, as part of function overloading, but that is not the case here.
2. Just test if (!val.name) throw... (if you want, also test val.assets, etc...) (purists note: this also prohibits empty names, YMMV, so you might preferif (val.name == null)
3. Consider user friendly defaults for values (other than name). For example, if assets is an object, and you don't want nulls later on, use assets: assetPackage.assets || {}

p.s. If your software is security related, controls a pacemaker, etc., you need more valudation!