Add a `create` method

[brettstack]

Currently, put will replace the old item if it exists. A create method could simply wrap put and add a ConditionExpression

[jeremydaly]

The update method already does this. Plus the library automatically handles created and modified dates when using it. The goal is to be consistent with the DynamoDB API, so adding a non-standard naming convention could get confusing.

[brettstack]

Sorry, I should have been more clear. The create method would fail if the partition key exists (i.e it shouldn't update).

I get being consistent with the DynamoDB API, but this is a common use case, and adding ConditionExpression to put/update myself is a low-level pain. 😅 If you're really against adding a create method, how about a flag on the put method (create, createOnly, noUpdate)?

[darbio]

@brettstack - I agree with @jeremydaly.

You can always extend the library yourself in your code to add this helper util if you like.

It's not hard to define this behaviour with a put:

const result = await Entity.put({
    identifier, name
}, {
    conditions: [
        {
            attr: 'pk',
            exists: false,
        },
    ],
});

[brettstack]

Compare that to:

Entity.create({
    identifier, name
})

Or, if we must:

Entity.put({
    identifier, name
}, {
    createOnly: true
})

This is pretty low-level:

{
    conditions: [
        {
            attr: 'pk',
            exists: false,
        },
    ],
}

[jeremydaly]

I see your point @brettstack, so perhaps we could consider some “helper” methods that wrapped common patterns? It would have to be really clear that these were special methods as opposed to low level API methods.

[brettstack]

What did you have in mind to make this really clear? Is it enough to highlight this in the docs? Or did you want to scope these to something like Entity.helpers.create()

[darbio]

If the idea is to be able to dive in and out of the AWS SDK and not to be an ORM then I think this detracts from that goal. I've found this part of the library really useful for allowing me to see what is happening and implement missing features (such as transactions in v0.2).

Any user of this library needs to understand how DynamoDb works, so low level shouldn't be a problem IMO and increases the barrier to entry by having to understand DynamoDb and the library.

It's the whole implicit vs explicit argument. Is it better to be more explicit in your code, or let the library handle it for certain cases?

[omichowdhury]

Maybe the right solution here is better docs instead of more code. Add a recipes section that lists out common tasks like this and how they're implemented with this library.

I usually end up creating small wrapper layers to libraries to add common functionality like this, add logging, bake in defaults etc - and I'm happy with the tradeoffs.