Terrestrial

  # 1. Define some domain objects, structs will surfice for the example

  User = Struct.new(:id, :first_name, :last_name, :email, :posts)
  Post = Struct.new(:id, :author, :subject, :body, :created_at, :categories)
  Category = Struct.new(:id, :name, :posts)

  ## Also assume that a conventional database schema (think Rails) is in place,
  ## a column for each of the struct's attributes will be present. The posts
  ## table will have `author_id` as a foreign key to the users table. There is
  ## a join table named `categories_to_posts` which facilitates the many to
  ## many relationship.

  # 2. Configure a Sequel database connection

  ## Terrestrial does not manage your connection for you.
  ## Example assumes Postgres however Sequel supports many other databases.

  DB = Sequel.postgres(
    host: ENV.fetch("PGHOST"),
    user: ENV.fetch("PGUSER"),
    database: ENV.fetch("PGDATABASE"),
  )

  # 3. Configure mappings and associations

  ## This is kept separate from your domain models as knowledge of the schema
  ## is required to wire them up.

  CONFIG = Terrestrial.config(DB)
    .setup_mapping(:users) { |users|
      users.class(User) # Specify a class and the constructor will be used
      users.has_many(:posts, foreign_key: :author_id)
    }
    .setup_mapping(:posts) { |posts|
      # To avoid directly specifiying a class, a factory function can be used instead
      posts.factory(->(attrs) { Post.new(attrs) })
      posts.belongs_to(:author, mapping_name: :users)
      posts.has_many_through(:categories)
    }
    .setup_mapping(:categories) { |categories|
      categories.class(Category)
      categories.has_many_through(:posts)
    }

  # 4. Create an object store by combining a connection and a configuration

  OBJECT_STORE = Terrestrial.object_store(config: CONFIG)

  ## You are not limited to one object store configuration or one database
  ## connection. To handle complex situations you may create several segregated
  ## mappings and object stores for your separate aggregate roots, potentially
  ## utilising multiple databases and different domain object
  ## classes/compositions.

  # 5. Create some objects

  user = User.new(
    "2f0f791c-47cf-4a00-8676-e582075bcd65",
    "Hansel",
    "Trickett",
    "hansel@tricketts.org",
    [],
  )

  user.posts << Post.new(
    "9b75fe2b-d694-4b90-9137-6201d426dda2",
    user,
    "Things that I like",
    "I like fish and scratching",
    Time.parse("2015-10-03 21:00:00 UTC"),
    [],
  )

  # 6. Save them

  OBJECT_STORE[:users].save(user)

  ## Only the (aggregate) root object needs to be passed to the mapper.

  # 7. Query

  user = OBJECT_STORE[:users].where(id: "2f0f791c-47cf-4a00-8676-e582075bcd65").first

  # => #<struct User
  #  id="2f0f791c-47cf-4a00-8676-e582075bcd65",
  #  first_name="Stephen",
  #  last_name="Best",
  #  email="bestie@gmail.com",
  #  posts=#<Terrestrial::CollectionMutabilityProxy:7ff57192d510 >,