Tidying up the neo4j package

[fbiville]

I just extracted some statistics about the neo4j package that you know and love.

This is what it looks like on the 5.0 branch:

Package "neo4j" TL;DR ⬇️
----
 - 23 exported type alias/declaration definition(s)
 - 14 exported const definition(s)
 - 39 exported function definition(s)
 - 23 exported interface definition(s)
 - 9 exported struct definition(s)

Note: The results may not be 100% accurate, as I wrote an AST visitor in a pretty quick'n'dirty way.

For one of the next major versions, I was thinking that maybe it's time to put some APIs to their own package.
Why? I believe the current way of stuffing everything into the same package hurts discoverability.

Ideally, I would love to keep neo4j only for the basic Driver elements you'll find in all official drivers (and some community ones) as well:

• Driver (will be gone in 6.0) / DriverWithContext and their siblings (AuthToken, Config, ...)
• Session(will be gone in 6.0) / SessionWithContext and their siblings (SessionConfig, TransactionConfig, ...)
• Transaction(will be gone in 6.0) / ExplicitTransaction / ManagedTransaction
• Result (will be gone in 6.0) / ResultWithContext and their siblings (ResultSummary, ...)

That would leave helpers out and they would need a new home (or even new homes if they don't really belong together).
Here is a short list of the helpers we've got today:

Record type assertion helpers:

• func AsRecord(from any, err error) (*Record, error)
• func AsRecords(from any, err error) ([]*Record, error)

Result aggregation helpers:

• (will be gone in 6.0) func Collect(result Result, err error) ([]*Record, error)
• func CollectTWithContext[T any](ctx context.Context, result ResultWithContext, mapper func(*Record)) ([]T, error)
• (will be gone in 6.0) func CollectT[T any](result Result, mapper func(*Record)) ([]T, error)
• func CollectWithContext(ctx context.Context, result ResultWithContext, err error) ([]*Record, error)
• (will be gone in 6.0) func Single(result Result, err error) (*Record, error)
• func SingleTWithContext[T any](ctx context.Context, result ResultWithContext, mapper func(*Record)) (T, error)
• (will be gone in 6.0) func SingleT[T any](result Result, mapper func(*Record)) (T, error)

Transaction function generic helpers:

• func ExecuteRead[T any](ctx context.Context, session SessionWithContext, work ManagedTransactionWorkT[T], configurers ...func(config *TransactionConfig)) (T, error)
• func ExecuteWrite[T any](ctx context.Context, session SessionWithContext, work ManagedTransactionWorkT[T], configurers ...func(config *TransactionConfig)) (T, error)

Record generic mapping helpers and their associated type constraint:

• func GetProperty[T PropertyValue](entity Entity, key string) (T, error)
• func GetRecordValue[T RecordValue](record *Record, key string) (T, bool, error)

Arguably, the date/time helpers could be moved too:

• func DateOf(t time.Time) Date
• func DurationOf(months int64, nanos int) Duration
• func LocalDateTimeOf(t time.Time) LocalDateTime
• func LocalTimeOf(t time.Time) LocalTime

What do you think? How has been your experience with navigating the Go driver API so far?
I'm interested in your opinion regardless of your level of experience with the Go driver ;)

[fbiville]

Since v5.7.0, we gradually started introducing new packages to fight the cruft.

• Config now lives in config (but aliased in the neo4j to preserve backward compatibility at least until 6.0 is out)
• notification category and severity level live in notifications

[fbiville]

The public auth package was introduced in v5.8.0 (as well as an internal one).
It includes:

• the new TokenManager interface and a default implementation returned by ExpirationBasedTokenManager
• neo4j.AuthToken is now an alias to the internal auth.Token type

Future releases will likely move other bits out of the neo4j package (in a non-breaking way, by introducing aliases), as stated by issues like #472 and #473.

[lucapirolo]

Hi @fbiville is any help wanted with this refactor above?

[StephenCathcart]

Hi @lucapirolo, I'd still like to tidy up the neo4j package as @fbiville mentioned above ready for 6.0 so any help is welcome 😄 . I need to have a think about the best way to separate/categorize the packages, things like SessionConfig and TransactionConfig ideally should be moved to the config package (but just moving them straight over creates a cyclic dependency). Any suggestions/help with this is most welcome 👍.

[lucapirolo]

Hi @StephenCathcart & @fbiville ,

#548

I've centralised all bookmarks-related code into a new 'bookmarks' package. This should help in separating concerns and maintaining clarity in the codebase.
Updated all references from 'neo4j.Bookmarks' to 'bm.Bookmarks' and implemented 'bm' as a package alias. This was to clear up any naming ambiguities, particularly in functions like 'cleanupBookmarks(bookmarks bookmarks.Bookmarks)'.
To ensure backward compatibility i have added Bookmarks aliases in the neo4j package.

I think changes like these will eventually allow us to move the SessionConfig and TransactionConfig without cyclic dependency. If this approach works for you. i am happy to look at what next to refactor.

Excited to keep pushing forward on this!

[lucapirolo]

Hi i have done some extra work on this. #549. I look forward to any feedback and hope this helps!