reorganize the API from type DB to type Store

1 files changed, 58 insertions, 0 deletions

diff --git a/oblast.go b/oblast.go
new file mode 100644
index 0000000..9ed60a4
--- /dev/null
+++ b/oblast.go
@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
+// SPDX-License-Identifier: Apache-2.0
+
+// Package oblast is an ORM library for Go, focusing specifically on just the loading and storing of records in the most efficient manner possible.
+// No utilities are provided for generating DDL or managing schema migrations, or for building complex OLAP queries.
+//
+// # Usage pattern
+//
+// To use this library, first declare a record type, and create a [Store] for it once to analyze the type and prepare the respective OLTP queries:
+//
+//	type LogEntry struct {
+//		ID        int64     `db:"id,auto"`
+//		CreatedAt time.Time `db:"created_at"`
+//		Message   string    `db:"message"`
+//	}
+//	var logEntryStore = oblast.NewStore[LogEntry](
+//		oblast.PostgresDialect(),
+//		oblast.TableNameIs("log_entries"),
+//		oblast.PrimaryKeyIs("id"),
+//	)
+//
+// Then use it many times to perform load and store operations:
+//
+//	func doStuff(db *sql.DB) error {
+//		newEntry := LogEntry{
+//			CreatedAt: time.Now(),
+//			Message: "Hello World.",
+//		}
+//		err := logEntryStore.Insert(db, &newEntry)
+//		if err != nil {
+//			return err
+//		}
+//		fmt.Printf("created log entry %d", newEntry.ID)
+//
+//		allEntries, err := logEntryStore.SelectWhere(db, `created_at < NOW()`)
+//		if err != nil {
+//		  return err
+//		}
+//		fmt.Printf("there are %d log entries so far", len(allEntries))
+//	}
+package oblast // import "go.xyrillian.de/oblast"
+
+import "go.xyrillian.de/oblast/internal"
+
+// PlanOption is an option that can be given to NewStore() to influence query planning for a certain type of record.
+type PlanOption func(*internal.PlanOpts)
+
+// TableNameIs is a PlanOption for record types that correspond to exactly one database table (as opposed to a join of multiple tables).
+// This option is required to enable any of the methods of [Store] that use partially or fully auto-generated query strings.
+func TableNameIs(name string) PlanOption {
+	return func(opts *internal.PlanOpts) { opts.TableName = name }
+}
+
+// PrimaryKeyIs is a PlanOption for record types that correspond to a database table with a primary key.
+// This option is required to enable use of the [Store.Update] and [Store.Delete] methods.
+func PrimaryKeyIs(columnNames ...string) PlanOption {
+	return func(opts *internal.PlanOpts) { opts.PrimaryKeyColumnNames = columnNames }
+}