Driver v2: primitive package merged into bson; replace x/bsonx in index.go

[TopherGopher]

Part of the easymongo refactor (see PLAN.md on the refactor branch).

Working context (read this first)

• Repository github.com/tophergopher/easymongo. Start from branch claude/mongotest-easymongo-refactor-wu2vhm; create a branch issue-<number>-<short-slug> from it and open a pull request back into it. PLAN.md on that branch is the source of truth; read it before writing code.
• Go project, single module, all packages at the repo root except the new easymongotest/ subpackage. The final toolchain target is Go 1.27 (set by Toolchain: go 1.27, latest dependencies, tidy, remove replace directives #10); any Go 1.24 or newer works until then. Before pushing: gofmt -l . prints nothing, go vet ./..., go test -race ./....
• The existing test suite (*_test.go at the root, package easymongo_test, every test function calling setup(t) from common_test.go) is the regression net for this refactor. It must pass after your change. It needs a Docker daemon reachable through the normal Docker environment and the mongo:8 image.
• Order matters. The driver package cannot compile half-migrated (the *mongo.Client type flows from Connection to Database to Collection), so the four driver issues Driver v2: migrate connect.go (mongo.Connect, Disconnect, BSONOptions, write concern) #2, Driver v2: options struct literals become builders; drop MaxTime; ArrayFilters and Delete option changes #3, Driver v2: primitive package merged into bson; replace x/bsonx in index.go #4 and Driver v2: Distinct returns a DistinctResult that must be decoded #5 land together in one pull request, worked in that order. Before them, New easymongotest subpackage wrapping mongotest/v2 #7 and Switch the easymongo test suite to easymongotest #8 must land so the test suite no longer depends on the old github.com/tophergopher/mongotest v0.1.0 module (which itself imports easymongo and breaks the moment easymongo's types change). Until mongotest's v2 module is tagged, use a local replace github.com/tophergopher/mongotest/v2 => ../mongotest/v2 in go.mod and say so in the pull request; Toolchain: go 1.27, latest dependencies, tidy, remove replace directives #10 removes it.
• Method is test-driven: write the tests listed under "Tests first", confirm they fail for the expected reason, then implement. Never delete, skip or weaken an existing test to get green; if a test must change because the public API changed (for example primitive.ObjectID to bson.ObjectID), change only the types.
• Driver v2 reference: https://pkg.go.dev/go.mongodb.org/mongo-driver/v2 and the migration guide https://github.com/mongodb/mongo-go-driver/blob/master/docs/migration-2.0.md. Signatures quoted in these issues were checked against v2.9.0.
• Do not add third-party dependencies unless this issue lists them.
• Tracking issue for the whole refactor: Tracking: easymongo refactor (mongo-driver v2, easymongotest helpers, toolchain) #13. The mongotest side is tracked in Tracking: mongotest refactor (stdlib Docker client, driver v1/v2 modules, lighter dependencies) mongotest#48.
• Commit messages: imperative summary line, blank line, body explaining why. Mention this issue number in the pull request description.

Scope

• primitive.ObjectID becomes bson.ObjectID, primitive.NewObjectID() becomes bson.NewObjectID(), primitive.NewObjectIDFromTimestamp becomes bson.NewObjectIDFromTimestamp. Occurrences: insert_query.go return types (24, 44, 59, 69), delete_query.go (70), collection.go (163-172), common_test.go (40, 57-62), and any primitive.M/primitive.D in tests.
• This is a public API change for easymongo (Insert().One returns bson.ObjectID). Agreed with the maintainer: easymongo is 0.x, so this ships as a minor version bump with a CHANGELOG note, not as an easymongo/v2 module.
• index.go uses the deprecated go.mongodb.org/mongo-driver/x/bsonx package (bsonx.Doc{{Key: ..., Value: bsonx.Int32(1)}}) to build mongo.IndexModel.Keys. Replace with bson.D{{Key: field, Value: int32(1)}} / int32(-1) for descending. Indexes().CreateOne still returns (string, error).
• utils.go indexKeyToBsonE keeps returning bson.E; verify direction parsing for -name style keys.
• Re-export helpers if callers relied on easymongo types: consider type ObjectID = bson.ObjectID in easymongo so downstream code has one import. Decide and document.

Implementation details

Verified in v2.9.0: type bson.ObjectID [12]byte, bson.NewObjectID(), bson.NewObjectIDFromTimestamp(time.Time), bson.NilObjectID. mongo.IndexModel{Keys: bson.D{{Key: "name", Value: int32(1)}}} and coll.Indexes().CreateOne(ctx, model, opts ...options.Lister[options.CreateIndexesOptions]) (string, error); ListSpecifications(ctx, opts...) ([]mongo.IndexSpecification, error) returns values, not pointers.

Add to easymongo (new file types.go) so downstream code can avoid importing the driver for ids:

// ObjectID is an alias of the driver's bson.ObjectID.
type ObjectID = bson.ObjectID
func NewObjectID() ObjectID { return bson.NewObjectID() }

Change the Insert return types and DeleteByID/FindByID/ReplaceByID/UpsertByID parameters to ObjectID; since it is an alias, bson.ObjectID values work unchanged.

Mechanical rewrite help: grep -rln 'bson/primitive' --include=*.go . | xargs sed -i 's#go.mongodb.org/mongo-driver/bson/primitive#go.mongodb.org/mongo-driver/v2/bson#; s/primitive\./bson./g' then fix duplicate bson imports by hand and run gofmt -w ..

Tests first

• index_test.go: creating an ascending and a descending index yields index specs (via ListSpecifications) with the expected keys and names; Ensure twice is idempotent.
• insert_query_test.go: the returned id decodes back to the inserted document's _id.
• A test that NewObjectIDFromTimestamp filtering in collection.go (the CreatedBetween-style helpers) returns the expected subset.

Acceptance

• grep -rn "bson/primitive\|x/bsonx" --include=*.go . returns nothing.

Depends on: #3. Lands in the same pull request as #2, #3 and #5.