Docs question: when would deleted$ return false?

[rdworth]

Case

Docs question

Issue

Docs are unclear. In docs/RxDocument.md it says

### deleted$
Emits a boolean value, depending if the RxDocument is deleted or not.

The code example below it does not demonstrate an example of the callback returning false, and the description doesn't detail under what circumstance this would happen.

[pubkey]

RxDocument.deleted$ is an observable (BehaviorSubject) which emits the current deletion-status when a new subscription comes in or when the value changes.

Does this information help? Maybe we should document everywhere if something is a behavior-subject or a standard observable.

[rdworth]

My assumption is that the deleted$ callback would only be called if the value of deletion-status changes. No sure whether that's right based on what you're saying. Perhaps if that isn't how it works today it should be modified?

Assuming that is the way it works or might be made to work (notification only when value changes) I can't imagine the value changing from true to false. Is it possible to un-delete a document? Or is there some other use case that would cause the deletion-status to change in this direction?

If the assumption I made above is not correct and you don't want to change the behavior that the deleted$ callback can sometimes be triggered even when the corresponding deletion-status value has not changed, then we should document some of those scenarios and instruct the developer to add a guard if (!deleted) return;

If undeleting (or any other such use case) is not possible, seems simpler to only notify when deleted changes to true and then not worry about passing a boolean (and therefore not needing the guard) since by contract it will always have the same value. Unless of course that would be unnecessarily complex to implement on top of the observable.

[pubkey]

My assumption is that the deleted$ callback would only be called if the value of deletion-status changes.

No, that's not how it works. For consistency, RxDB always uses a rxjs-subject when a value can change over time. The value of deleted changes over time, so its also a subject. This makes it easier to use the values in async-pipes like here

To make a callback to run when the document is deleted, you can combine rxjs-methods like this:

myDocument.deleted$
  .filter(is => is==true)
  .first()
  .toPromise()
  .then(function(){
    console.log('deleted');
  });

You are right, we should put something like this into the docs, since I assume many people will want to use it like this.

There is currently no way to undelete a document, but I had this in mind and it would be possible to add this feature in the future.

[rdworth]

Ok, that makes sense. Thanks for explaining that. And glad to hear that someday it may be possible to un-delete. Agreed this is a perfect setup for that.

[pubkey]

I'm closing this since nothing has to be changed. I'm also no more sure if we should include the example mentioned above into the docs, since it's a standard rxjs-usage. Reopen if you think otherwise.

[rdworth]

@pubkey I agree 100% - nothing to do here. Issue closed.

Since both rxjs and rxdb are new to me I don't have a good feel for where that line is in all cases. Though working through the docs certainly has helped start painting that picture, and that is preferable to have an obscure black hole below the abstraction layer (or just always being told - go see rxjs docs for how to use this opaque thing). A bit of a balancing act. Maybe I'll have a better idea down the road as I learn both libraries and get a better feel for that line and how to document it well for newcomers and experienced users.

For now I think it's better to have this example than not, so I would leave it.

[pubkey]

I'm not sure about it. The thing is, that many devs don't know exactly how rxjs works and my hope is that in the near future they will and so we should not include this into the docs. Maybe a good solution would be to use more complex rxjs-code in our example-projects.

Reopen this to not forget about it.

TODO Question: Should rxjs-behavior be described in the docs?

[pubkey]

I'm closing this. I don't think the basic rxjs-behaviour should be included into the rxdb-docs. People who don't know the basics of rxjs, are unlikely to choose RxDB for their database. Also there would be no end in including the rxjs-basics and we would have to do this on every observable which could occur.