You generally should listen to the transaction’s “complete” event instead of the put/add request’s “success” event, because the transaction may fail after “success.” There’s at least one example of someone being confused by the wording. Perhaps the spec should point out that you usually want to listen to “complete” for write requests.
Use of a write request’s “success”/“error” events is probably reserved for advanced use cases (e.g. to commit part of a transaction even when the later requests fail, or to retry a write that failed, or to measure progress when a transaction has multiple parts).
Note that there are cases where listening for onsuccess is needed. For example if you are worried that a written entry might collide with an already existing one. In this case you might want to hold off further operations until the doubtful request has succeeded.
Added this note to Transaction.oncomplete and also for IDBObjectstore.add().
To determine if a transaction has completed successfully, listen to the transaction’s complete event rather than the IDBObjectStore.add request’s success event, because the transaction may still fail after the success event fires.