A shortcut method to query by primary key

[tarjei]

Hi, I often find myself querying for a single entity by an known primary key.

It would be super useful to have this as a separate method find(primaryKey).

[kettanaito]

Hey, @tarjei.

Do I understand you correctly that you'd like to propose a shorthand for this:

const db = factory({
  user: { id: primaryKey(String) }
})

// For this particular query by the primary key ("id").
db.user.findOne({
  where: { id: { equals: 'abc-123' } }
})

[kettanaito]

Yeah, I understand your reasons. My main reasoning is that this utility is purely practical, which does not necessarily mean it belongs in the design philosophy of what models are and how they can be operated with.

I'm usually tentative when it comes to shipping the specific quality of life improvements as a part of public API. It may feel like the most sensible thing in the world to you but for a library maintainer, each choice is a commitment to maintaining that choice for years. That's why I generally try designing generic APIs and encourage people to enhance their experience with custom utilities, if necessary. There's seldom a downside to that, people just get uncertain when their particular use case is not handled natively. Perhaps, a good way to illustrate it is that N amount of people may come up with N amount of new methods, and the API blows out of proportion into model.findByKey(), model.findLatestUpdated(), model.toSomethingTooSmart(). That's not a sustainable API direction.

The overhead of implementing the utility as I've suggested above is close to zero, as you are using the public API, which is maintained. I agree that not all abstractions are possible like that but this particular one seems to be. That's why I'd recommend building it as a part of your project's utilities.

A good balance between "satisfy my use case" and "let's sure this is maintainable" is community-driven utility packages. Think of @mswjs/data-utils:

import { enhance } from '@mswjs/data-utils'

// Just a random example of how that may work.
const db = enhance(factory({ ... }))

db.user.findByKey('abc-123')

I'm never against standalone solutions. You can version them, you can maintain them, and the most important thing is that they can scale infinitely, satisfying even the most niche use cases while the core library must not.

[SevenOutman]

Perhaps, a good way to illustrate it is that N amount of people may come up with N amount of new methods, and the API blows out of proportion into model.findByKey(), model.findLatestUpdated(), model.toSomethingTooSmart(). That's not a sustainable API direction.

@kettanaito That makes sense but I don't think findByKey belongs to this category because we already have primaryKey top-level API and findByKey is paired with it. It's not a shortcut for some custom query on "id" attribute but a helper function acting as supplement to primaryKey, allowing user to query the primaryKey of a model without being aware of which exact attribute it is.

[tarjei]

@kettanaito thank you for taking the time to answer my request so thoughtfully.

I tend to agree with @SevenOutman's reasoning, but I can understand your reasoning as well.

[kettanaito]

@SevenOutman, not sure I follow the connection here. The root-level primaryKey API is for designing models. The proposed findByKey is a quality-of-life improvement querying utility. They are not similar by any means conceptually.

As I said, the use cases are many, and any good API values versatility and dynamics over solving each particular use case. I've stated my point above, and I still stand by it: implementing such a utility is a low-cost solution if you find such queries repetitive. Perhaps, I would only recommend implementing it to return a partial query object instead of operating on the model (that's unnecessary):

db.user.findOne({
  which: hasKey('id', 'abc-123')
})

This will give you much more versatility, as you can inject withKey into any queries now.

[SevenOutman]

Perhaps, I would only recommend implementing it to return a partial query object instead of operating on the model (that's unnecessary):

db.user.findOne({
  which: hasKey('id', 'abc-123')
})

@kettanaito I'd say you may have misunderstood what @tarjei proposed as findByKey.

It's not a "life improving" shortcut for users who are "too lazy" to write some lines of code

// ❌ keyName can be any attribute on model
.findByKey(keyName, keyValue)

It's related to model designing for cases where user does not have to know or may not be able to know which attribute is defined as primary key, e.g. model is imported from a package

// ✅ query by the primary key's value, but don't have to know which attribute it is
.findByKey(valueOfPrimaryKey)

If this still look like a quality-of-life improving shortcut to you, I'd say primaryKey is also such a life improving shortcut 🤣

An alternative solution may be providing an API that returns the primary key attribute of a model, that way people are able to abstract a findByKey util themselves.