Update doc_test.go with more usage examples

[Jtaylorapps]

Added simple examples for common use cases, including Get, Put, and Delete operations. Includes additional examples for Get and Delete operations while leveraging indexes.

[JohnStarich]

Thanks for the contribution @Jtaylorapps! I think these examples would make a great addition.

Since idb/doc_test.go is functioning as a "whole file" example already, let's make a new example file for these. Perhaps in idb/examples_test.go.

Let's try to make them render as examples visible in pkg.go.dev: https://pkg.go.dev/testing#hdr-Examples
(more detail for how they work here)

For each function, a self-contained doc example might look like this:

func ExamplePutAndGetKey() {
    var (
        db = idb.Global()
        objectStoreName = "foo"
        key = js.ValueOf("bar")
    )
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    // ...
    fmt.Println("Value at key", key, "is =", value)
    // Output:
    // Value at key "bar" is = "baz"
}

[Jtaylorapps]

@JohnStarich Do you mean something to the tune of this? My is definitely to get stuff appearing in pkg.go.dev, though I'm pretty unfamiliar with its nuances, Perhaps examples such as the below should be made and the original examples such as Get and Put could be added to the standard API? Despite their divergence from the IndexedDb spec, they feel far more idiomatic for Go.

func ExamplePut() {
	var (
		databaseName = "test"
		objectStoreName = "foo"
		value = js.ValueOf("bar")
	)

	ctx := context.Background()
	openRequest, _ := idb.Global().Open(ctx, databaseName, 1,
		func(db *idb.Database, oldVersion, newVersion uint) error {
		_, _ = db.CreateObjectStore(objectStoreName, idb.ObjectStoreOptions{
			AutoIncrement: true,
		})
		return nil
	})
	db, _ := openRequest.Await(ctx)

	putFunc := func(db *idb.Database, objectStoreName string, value js.Value) (*idb.Request, error) {
		// Prepare the Transaction
		txn, err := db.Transaction(idb.TransactionReadWrite, objectStoreName)
		if err != nil {
			return nil, err
		}
		store, err := txn.ObjectStore(objectStoreName)
		if err != nil {
			return nil, err
		}

		// Perform the operation
		request, err := store.Put(value)
		if err != nil {
			return nil, err
		}

		// Wait for the operation to return
		err = txn.Await(ctx)
		if err != nil {
			return nil, err
		}
		return request, nil
	}
	request, _ := putFunc(db, objectStoreName, value)
	result, _ := request.Result()
	fmt.Println("Value at key", result, "is =", value)
	// Output:
	// Value at key <number: 1> is = bar
}

[JohnStarich]

@JohnStarich Do you mean something to the tune of this?

Yep! That works 👍

If it were me, I'd in-line the put func for easier reading, but I'm good either way.
You can also simplify the txn.Await()...request.Result() bit to request.Await(), since that will automatically commit the transaction, wait for it to complete, and then return the request's result.

My [goal] is definitely to get stuff appearing in pkg.go.dev, though I'm pretty unfamiliar with its nuances,

That's fair, the example stuff isn't super easy to test. You could try it out locally with my gopages tool for a quick and dirty check. It uses the same example detection and formatting as pkg.go.dev. No worries if it isn't perfect, I can help you test it or we can tweak it later in a future PR.

Perhaps examples such as the below should be made and the original examples such as Get and Put could be added to the standard API? Despite their divergence from the IndexedDb spec, they feel far more idiomatic for Go.

That's an interesting idea. Can you open an issue for discussing the idea further?

At first blush, I think we'd at least want them in a new package. IndexedDB isn't exactly easy to grok for anyone, so there's definitely some room for improvement.

[Jtaylorapps]

Cool, I'll try to convert a few of the examples and put it up on the PR before the holiday weekend!

Is the result return the primary difference between req.Await and txn.Await?

Lastly, I went ahead and opened an issue. Looking forward to seeing what we can do with it - I spent a lot of time working out how to use the IndexedDb API. I really like the idea of keeping a faithful replication of the IDB spec, but at the same time a little simplification would probably benefit the majority of consumers of the API.

[JohnStarich]

Is the result return the primary difference between req.Await and txn.Await?

There is a subtle difference between req.Await() and txn.Await(), but for this example there's not really a meaningful difference so it might be clearer to do the wait and result fetch in one go.

If you're curious, these two operations map to waiting on two different JS events on their respective objects:

• IDBTransaction complete event
• IDBRequest success event

Where there can be many IDBRequests attached to a single IDBTransaction.

Lastly, I went ahead and opened an issue. Looking forward to seeing what we can do with it - I spent a lot of time working out how to use the IndexedDb API. I really like the idea of keeping a faithful replication of the IDB spec, but at the same time a little simplification would probably benefit the majority of consumers of the API.

Awesome, thanks! I'll hop over to that issue to continue the discussion.