Interested in validators?

[ef4]

We have written validation code that follows the exact structure of these types, using the new typescript asserts feature. It's great for safely casting documents that came over the network into the types from this package.

Since the validators need to match exactly with how the types are defined, I think it would be appropriate to upstream the validators into this package. Do you agree?

If so I can make a PR adding the validators. They would live in a separate module inside this package, so they wouldn't add anything to apps that don't choose to import from jsonapi-typescript/validators.

[mike-north]

assertion guards are a relatively new feature (TS 3.7), and while I feel that it is aligned with these JSON types, I would not want to impose breaking changes on consumers that would only be solvable with a compiler upgrade.

They would live in a separate module inside this package, so they wouldn't add anything to apps that don't choose to import from jsonapi-typescript/validators.

I think that this means that consumers would be ok to compile with older TS versions (i.e., 2.8 is the minimum required for @types/ember currently), providing they do not import the module you're proposing to add.

If you can implement this such that existing use with TS 2.8 can continue as-is, I'm 100% open to your proposal, even if it means that TS 3.7 is required in order to use the validators. I can assist with writing tests such that this required condition is maintained and protected from future regression.

[mike-north]

Btw looks like this library currently works with TS >= 2.3. I'd be fine with a minimum requirement of 2.8, but would not want to jump ahead of the @types/ember minimum requirement (2.8).

[earthlyreason]

For what it's worth, you can make validators without using asserts. Type guards, which have been around since very early versions of TypeScript, can provide essentially the same functionality. Here is a an incomplete, off-the-cuff example:

import type * as JSONAPI from "jsonapi-typescript";

// SHALLOW checks for various top-level JSON:API types
// Note that `type` is treated as optional.

const is_plain_object = (x: any) =>
  x !== null && typeof x === "object" && !Array.isArray(x);

const is_resource = (x: any) => is_plain_object(x) && typeof x.id === "string";

const is_primary_data = (x: any): x is JSONAPI.PrimaryData =>
  is_resource(x) || (Array.isArray(x) && x.every(item => is_resource(item)));

export const is_jsonapi_data_document = (x: any): x is JSONAPI.DocWithData =>
  is_primary_data(x?.data);

export const is_jsonapi_meta_document = (x: any): x is JSONAPI.DocWithMeta =>
  is_plain_object(x?.meta);

export const is_jsonapi_error_document = (x: any): x is JSONAPI.DocWithErrors =>
  Array.isArray(x?.errors);

export const is_jsonapi_document = (x: any): x is JSONAPI.Document =>
  is_jsonapi_data_document(x) ||
  is_jsonapi_meta_document(x) ||
  is_jsonapi_error_document(x);

You can then use this with type narrowing as documented.

if (is_jsonapi_document(body)) {
  // `body` is JSONAPI.Document here
} else {
  // `body` is whatever it was, possibly with JSONAPI.Document subtracted
}