// SPDX-FileCopyrightText: 2026 Stefan Majewsky <majewsky@gmx.net>
// SPDX-License-Identifier: Apache-2.0

// Package info contains marker types that can be placed in user-defined struct types.
// Doing so enables certain operations within Oblast that rely on the metadata attached to these markers.
package info // import "go.xyrillian.de/oblast/info"

// seal is a private type that appears in interface definitions below,
// to ensure that only types from this package can implement these interfaces.
type seal struct{}

// TableNameIs is a zero-sized marker for struct types that correspond to tables.
// Put this as an embedded field on your struct type and put the table name in the field's `db` tag.
//
//	// For example, this struct type...
//	type LogEntry struct {
//		info.TableNameIs  `db:"log_entries"`
//		info.PrimaryKeyIs `db:"id"`
//		ID                int64     `db:"id,auto"`
//		CreatedAt         time.Time `db:"created_at"`
//		Message           string    `db:"message"`
//	}
//	// ...corresponds to this table schema (shown here in PostgreSQL syntax):
//	CREATE TABLE log_entries (
//		id          BIGSERIAL    NOT NULL PRIMARY KEY,
//		created_at  TIMESTAMPTZ  NOT NULL,
//		message     TEXT         NOT NULL
//	);
//
// This marker is required for all operations that use autogenerated SQL statements.
type TableNameIs struct{}

// hasTableMarker implements the IsTable interface.
func (TableNameIs) hasTableMarker(seal) {}

// IsTable is implemented by all types that have an embedded field of type [TableNameIs].
type IsTable interface {
	hasTableMarker(seal)
}

// PrimaryKeyIs is a zero-sized marker for struct types that correspond to tables with a primary key.
// Put this as an embedded field on your struct type and list the columns of the primary key in the field's `db` tag,
// as shown on the example for type [TableNameIs].
//
// This marker is required for all UPDATE and DELETE operations that use autogenerated SQL statements.
type PrimaryKeyIs struct{}

// hasPrimaryKeyMarker implements the IsTableWithPrimaryKey interface.
func (PrimaryKeyIs) hasPrimaryKeyMarker(seal) {} //nolint:unused // TODO

// IsTableWithPrimaryKey is implemented by all types that have embedded fields of type [TableNameIs] and [PrimaryKeyIs].
type IsTableWithPrimaryKey interface {
	hasTableMarker(seal)
	hasPrimaryKeyMarker(seal)
}