fsdb

defmodule Fsdb do
  @moduledoc """
    API module.

    ```elixir
    #run with: mix sample

    {:ok, db} = Fsdb.start_link(Path.expand("_build/dev/.fsdb"))

    #drop to start over
    :ok = Fsdb.drop(db, "table1")

    #creates table at dev default _build/dev/.fsdb
    #configure path with: config :fsdb, path: <NEW_PATH>
    :ok = Fsdb.create(db, "table1")

    #insert generates and returns an autoincrementing id
    {:ok, 1} = Fsdb.insert(db, "table1", "row1")
    {:ok, "row1"} = Fsdb.fetch(db, "table1", 1)

    #operation on unexisting ids return not found
    :nf = Fsdb.delete(db, "table1", 5)
    :nf = Fsdb.update(db, "table1", 5, "row5+")

    #save overrides and updates id generator
    :ok = Fsdb.save(db, "table1", 5, "row5")
    :ok = Fsdb.save(db, "table1", 3, "row3")
    #continue +1 of largest id used/generated before
    {:ok, 6} = Fsdb.insert(db, "table1", "row6")

    #operations that get back previous value
    {:ok, "row5"} = Fsdb.update(db, "table1", 5, "row5+")
    {:ok, "row5+"} = Fsdb.save(db, "table1", 5, "row5++")
    {:ok, "row5++"} = Fsdb.delete(db, "table1", 5)

    #tuples may not be id ordered
    [{1, "row1"}, {3, "row3"}, {6, "row6"}] = Fsdb.list(db, "table1")
    ```
  """

  ##########################################
  # App API
  ##########################################

  @doc """
  Starts the GenServer.

  `state` *must* contain a valid path in the `:path` key.

  `opts` is optional and is passed verbatim to GenServer.

  Returns `{:ok, pid}`.

  ## Example

    ```
    Fsdb.Server.start_link([path: ".fsdb"], [name: Fsdb.Server])
    ```
  """
  def start_link(state, opts \\ []) do
    Fsdb.Server.start_link(state, opts)
  end

  @doc """
  Stops the server.

  Returns `:ok`.
  """
  def stop(pid) do
    Fsdb.Server.stop(pid)
  end

  @doc """
  Creates a table with name `table`.

  Returns `:ok`.
  """
  def create(pid, table) do
    GenServer.call(pid, {:create, table})
  end

  @doc """
  Drops the table named `table`.

  Returns `:ok`.
  """
  def drop(pid, table) do
    GenServer.call(pid, {:drop, table})
  end

  @doc """
  Returns all rows in table `table`.

  Returns `[{id, row}, ...]`.
  """
  def list(pid, table) do
    GenServer.call(pid, {:list, table})
  end

  @doc """
  Inserts row `row` in table `table` with auto generated id.

  Returns `{:ok, id}`.
  """
  def insert(pid, table, row) do
    GenServer.call(pid, {:insert, table, row})
  end

  @doc """
  Inserts or updates row `row` in table `table` with specific id `id`.
  If the provided id is greater than the last autogenerated id then
  the autogenerated id is updated to the provided one.

  Returns `:ok | {:ok, previous_row}`.
  """
  def save(pid, table, id, row) when is_integer(id) do
    GenServer.call(pid, {:save, table, id, row})
  end

  @doc """
  Fetches the row in table `table` having the id `id`.

  Returns `{:ok, row} | :nf`.
  """
  def fetch(pid, table, id) do
    GenServer.call(pid, {:fetch, table, id})
  end

  @doc """
  Updates the row in table `table` having the id `id`.

  Returns `{:ok, previous_row} | :nf`.
  """
  def update(pid, table, id, row) do
    GenServer.call(pid, {:update, table, id, row})
  end

  @doc """
  Deletes the row in table `table` having the id `id`.

  Returns `{:ok, previous_row} | :nf`.
  """
  def delete(pid, table, id) do
    GenServer.call(pid, {:delete, table, id})
  end

end