transforms between snake/camel cased field names

[altintx]

Looking for a way to use snake_case on the server side and camelCase on the client. Put together a POC at https://github.com/altintx/jsonapi-client/pull/1/files but do not believe it to be right. Specifically, I believe schema.ts:30: is expecting the names to be the same between the interface and the schema. For the linked implementation, I imagined doing something like

interface INotification {
  subject: Person;
  id: string;
  subjectId: string;
  sentAt: Date;
  contentJson: Json;
  status: 'error' | 'draft' | 'sent' | 'ready';
  createdAt: Date;
  updatedAt: Date;
}
const NotificationSchema = new Schema<INotification>({
  attributes: {
    subjectId: {},
    sentAt: {},
    contentJson: {},
    status: {},
    createdAt: {},
    updatedAt: {},
  },
  relationships: {
    subject: {},
  }
}, { serverTransform: "snake_case", clientTransform: "camelCase" }); // <---------
export class Notification extends model(NotificationSchema) { }

but like I said, my approach is hardly an ideal starting ground

[altintx]

This was decidedly a bad direction. The following works much better. Defines the intefaces and schemas to match server, and then presents a camelized frontend to JS

type SnakeToCamelCase<S extends string> =
  S extends `${infer T}_${infer U}`
    ? `${T}${Capitalize<SnakeToCamelCase<U>>}`
    : S;

type ModelCamelCase<TModel> = {
  [K in keyof TModel as SnakeToCamelCase<K & string>]: TModel[K];
}

type STJapiModel<IModel> = ReturnType<typeof model<IModel>>
type ModelClass<IModel> = (STJapiModel<IModel> & ModelCamelCase<IModel>)
function camelize<IModel>(m: STJapiModel<IModel>): ModelClass<IModel> {
  for (const section of ["attributes", "relationships"] as const) {
    for (const [field] of Object.entries(m.schema[section])) {
      const camelCaseField = field.replace(/_([a-z])/g, (g) => g[1]!.toUpperCase());
      Object.defineProperty(m.prototype, camelCaseField, {
        get: function () {
          return this[field];
        },
        set: function (value) {
          this[field] = value;
        },
        enumerable: true,
      });
    }
  }
  return m as unknown as ModelClass<IModel>;
}


export const Notification = camelize<INotification>(model(NotificationSchema));
export type Notification = ModelClass<INotification>;

[stantanasi]

I was thinking about implementing something like this.
In my case, I imagined adding a name field to the schema definition for each attribute and relationship.

For example:

export const ArticleSchema = new Schema<IArticle>({
  attributes: {
    title: {
      name: 'article_title',
    },
  },

  relationships: {
    author: {
      name: 'article_author',
    },

    comments: {
      name: 'article_comments',
    },
  },
});

export const PeopleSchema = new Schema<IPeople>({
  attributes: {
    // ...
  },

  relationships: {
    // ...
    comments: {
      name: 'people_comments'
    },
  },
});

The main challenge, though, is with the .include method. For example, take this:

await Article.find()
  .include({ author: { comments: true } })

It should generate this URL:

GET /articles?include=article_author.people_comments

The first include article_author is easy to generate, I can retrieve the schema from the Article class and use the defined name.
But for sub-includes, I run into a problem:
right now, there’s no way to access the schema of a relationship directly. So I can’t resolve to find the defined name in PeopleSchema (people_comments) without knowing the related class or its schema.

[altintx]

How would you feel about only aliasing attributes in that case, and dealing with relationship names as a separate problem?

[stantanasi]

Yeah, no problem at all — that makes sense!

Do you like the idea of having a name field for aliasing, or would you prefer handling it in a different way?
Personally, I find the name field pretty flexible, but I’m totally open if you see a cleaner or more scalable approach.

[stantanasi]

So I started implementing it:

export const ArticleSchema = new Schema<IArticle>({
  attributes: {
    title: {
      name: 'article_title',
    },
  },

  relationships: {
    // ...
  },
});

✅ What works:

// GET /articles?fields[articles]=article_title,author
await Article.find()
  .fields({
    articles: ['title', 'author'],
  })

// GET /articles?sort=-article_title
await Article.find()
  .sort({ title: 'desc' })

// GET /articles?filter[article_title]=JSON:API%20paints%20my%20bikeshed!
await Article.find({
  title: 'JSON:API paints my bikeshed!',
})

// GET /comments/5/article?fields[articles]=article_title
await Comment.findById('5').get('article')
  .fields({
    'articles': ['title'],
  })

❌ What doesn’t work (when using .get to fetch relationship requests):

// GET /comments/5/article?filter[title]=The%20article%20title
await Comment.findById('5').get('article', {
  title: 'The article title',
})

// GET /comments/5/article?sort=-title
await Comment.findById('5').get('article')
  .sort({ title: 'desc' })

Let me know if this approach works for you, or if you’d prefer another method! Always open to ideas

[altintx]

That's fantastic! I've got a CSV import feature to build; I'll build in terms of this and see how it goes. Thank you, will report back by Monday.

[stantanasi]

I found maybe a better way, that could work with everything:

It will need to create 2 interfaces, for every model with different names

export interface IArticle {
  title: string;
  createdAt: Date;
  updatedAt: Date;

  author: People;
  comments: Comment[];
}

// New interface with the server attribute name (snake_case or anything)
export interface IArticleServer {
  title: string;
  created_at: Date;
  updated_at: Date;

  article_author: People;
  comments: Comment[];
}

// Add the new interface here
export const ArticleSchema = new Schema<IArticle, IArticleServer>({
  attributes: {
    title: {},

    createdAt: {
      name: 'created_at', // The name depends on the second interface and is used when retrieving or sending JSON:API
      type: Date,
    },

    updatedAt: {
      name: 'updated_at', // The name depends on the second interface and is used when retrieving or sending JSON:API
      type: Date,
    },
  },

  relationships: {
    author: {
      name: 'article_author', // The name depends on the second interface and is used when retrieving or sending JSON:API
    },

    comments: {},
  },
});


class Article extends model(ArticleSchema) { }

Article.register('articles');

export default Article

Then when fetching data, every suggestion will be depending on the second interface, for example:

const articles = await Article.find({
  updated_at: new Date(), // Suggest the second interface
})
  .sort({
    created_at: 'desc', // Suggest the second interface
  })
  .include({
    article_author: {}, // Suggest the second interface
    comments: { article: { article_author: true } }, // Suggest the second interface
  })
articles[0].createdAt
articles[0].updatedAt
articles[0].author

articles[0].created_at // ERROR

Tell me what you think about that, and if you prefer this solution or the previous one

[altintx]

I think I /prefer/ the first, both because it allows more properties to be camelCased on the client side and at least superficially there's less boilerplate with that answer. But I'd be happy with either.

[stantanasi]

Okay thank you a lot for your feedback
I think I will try implementing both solution.

By creating a single interface, it will replace what can be replaced with the name field in the schema.
And by creating two interfaces, it will do the same but with the addition of suggesting the server side name (e.g. in snake_case)

[altintx]

I've tried quite a few TS JSON:API clients in the past few weeks, yours feels much better than anything else out there. Happy to see it develop new features.

[stantanasi]

Hi! It's now available in the new version 1.2.4 🎉

You can install it with:

npm install @stantanasi/jsonapi-client@latest

In the end, I only implemented the first solution (the one you prefer). I manage to make it work for everything with the add of a type field in schema's relationships definition.

export const ArticleSchema = new Schema<IArticle>({
  attributes: {
    title: {
      name: 'article_title' // The JSON:API name
    },
    // ...
  },

  relationships: {
    author: {
      type: 'people', // The JSON:API type of the relationship (not required but I recommend to add it everywhere, iit's only used for the transformation clientName (e.g. pascalCase) to serverName (e.g. snake_case)
      name: 'article_author', // The JSON:API name
    },

    comments: {
      type: 'comments', // The JSON:API type of the relationship
      name: 'article_comments', // The JSON:API name
    },
  },
});

// GET /articles?filter[article_title]=tesst&include=article_comments.comment_article.article_author.people_articles,article_author.people_articles&fields[articles]=article_title,article_author&sort=-article_title
await Article.find({
  title: 'tesst'
})
  .fields({
    articles: ['title', 'author'],
  })
  .sort({ title: 'desc' })
  .include({
    comments: { article: { author: { articles: true } } },
    author: { articles: true },
  })

// GET /articles/1/article_author?filter[first_name]=test&include=people_comments.comment_article.article_author.people_articles,people_articles.article_comments&fields[articles]=article_title,article_author&sort=first_name
await Article.findById('1').get('author', {
  "first-name": 'test'
})
  .fields({
    articles: ['title', 'author'],
  })
  .sort({ "first-name": 'asc' })
  .include({
    comments: { article: { author: { articles: true } } },
    articles: { comments: true },
  })

✅ What works:

Everything as long as you add the JSON:API relationship type when defining the schema

❌ What doesn’t work (as expected):

When a relationship can have two (or more) types:

export const ArticleSchema = new Schema<IArticle>({
  attributes: {
    body: {
      name: 'article_body'
    },
  },

  relationships: {
    // ...
    relations: {
      type: ['articles', 'comments'], // Possible but it will always take the first type
      name: 'article_relations',
    },
  },
});

export const CommentSchema = new Schema<IComment>({
  attributes: {
    // See that Comment and Article have the same client name (`body`) but different server name (`article_body`/`comment_body`)
    body: {
      name: 'comment_body'
    },
    // ...
  },

  relationships: {
    // ...
  },
});

So when fetching data like this:

// See that the filter `body` is transformed to `article_body` (and not `comment_body`)
// GET /articles/1/article_relations?filter[article_body]=The+body+value
Article.findById('1').get('relations', {
  body: 'The body value'
})

The same would happen if you use .include with a relationship with multiple types, it will always take the first one to transform the sub names.
Example:

export const CommentSchema = new Schema<IComment>({
  attributes: {
    // ...
  },

  relationships: {
    // See that Comment and Article have the same client name (`relations`) but different server name (`article_relations`/`comment_relations`)
    relations: {
      type: ['articles', 'people'],
      name: 'comment_relations',
    },
    // ...
  },
});

So when using .include:

// See that `relations` is transformed to `article_relations` (and not `comment_relations`), it takes the first `type` specified in ArticleSchema
// GET /articles?include=article_relations.article_relations.author
await Article.find()
  .include({
    relations: { relations: { author: true } },
  })

[altintx]

This is working beautifully thank you!