finishing touches

Author: jadengis

.formatter.exs

@@ -1,6 +1,5 @@
 # Used by "mix format"
 [
-  
   import_deps: [:ecto],
   inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 John Dengis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,11 +1,21 @@
-# EctoIrs
+# EctoIRS
 
-**TODO: Add description**
+[![Hex.pm](https://img.shields.io/hexpm/v/ecto_irs.svg)](https://hex.pm/packages/ecto_irs)
+[![Documentation](https://img.shields.io/badge/docs-hexdocs-blue.svg)](https://hexdocs.pm/ecto_irs)
+
+EctoIRS is an Elixir library that provides easy auditing capabilities for Ecto schemas and migrations. The library allows developers to automatically track who created or modified database records.
+
+## Features
+
+- 🔍 **Automatic Audit Fields**: Automatically add `inserted_by` and `updated_by` fields to your schemas
+- 🗃️ **Migration Helpers**: Easy-to-use migration functions for adding audit columns
+- ⚙️ **Flexible Configuration**: Customize field names, references, and behavior
+- 🚀 **Auto-population**: Support for automatic field population via MFA tuples
+- 📦 **Zero Dependencies**: Built on top of Ecto with minimal external dependencies
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `ecto_irs` to your list of dependencies in `mix.exs`:
+Add `ecto_irs` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -15,7 +25,336 @@ def deps do
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/ecto_irs>.
+## Quick Start
+
+### 1. Add Audit Columns to Your Database
+
+In your migration:
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreatePosts do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    create table(:posts) do
+      add :title, :string
+      add :content, :text
+      
+      # Adds :inserted_by_id and :updated_by_id columns
+      audits :users
+      
+      timestamps()
+    end
+  end
+end
+```
+
+### 2. Add Audit Fields to Your Schema
+
+In your schema:
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    field :content, :text
+    
+    # Generates :inserted_by and :updated_by associations
+    audits MyApp.User
+    
+    timestamps()
+  end
+end
+```
+
+### 3. Query with Audit Information
+
+```elixir
+# Preload audit associations
+post = MyApp.Repo.get(MyApp.Post, 1) |> MyApp.Repo.preload([:inserted_by, :updated_by])
+
+# Access audit information
+IO.puts "Created by: #{post.inserted_by.name}"
+IO.puts "Last updated by: #{post.updated_by.name}"
+```
+
+## Schema Usage
+
+### Basic Usage
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    audits MyApp.User
+    timestamps()
+  end
+end
+```
+
+### Custom Field Names
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    
+    audits MyApp.User,
+      inserted_by: :created_by,
+      updated_by: :modified_by
+  end
+end
+```
+
+### Disable Specific Fields
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    
+    # Only track who created, not who updated
+    audits MyApp.User, updated_by: false
+  end
+end
+```
+
+### Custom References
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    
+    audits MyApp.User, references: :user_id
+  end
+end
+```
+
+### Automatic Field Population
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  schema "posts" do
+    field :title, :string
+    
+    audits MyApp.User, autogenerate: {MyApp.Context, :current_user_id, []}
+  end
+end
+```
+
+### Pre-configuration
+
+```elixir
+defmodule MyApp.Post do
+  use Ecto.Schema
+  use EctoIRS.Schema
+
+  @audits_opts [autogenerate: {MyApp.Context, :current_user_id, []}]
+
+  schema "posts" do
+    field :title, :string
+    audits MyApp.User
+  end
+end
+```
+
+## Migration Usage
+
+### Basic Migration
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreatePosts do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    create table(:posts) do
+      add :title, :string
+      audits :users
+      timestamps()
+    end
+  end
+end
+```
+
+### Custom Column Names
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreatePosts do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    create table(:posts) do
+      add :title, :string
+      
+      audits :users,
+        inserted_by: :created_by,
+        updated_by: :modified_by
+      
+      timestamps()
+    end
+  end
+end
+```
+
+### Nullable Columns
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreatePosts do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    create table(:posts) do
+      add :title, :string
+      audits :users, null: true
+      timestamps()
+    end
+  end
+end
+```
+
+### Adding to Existing Tables
+
+```elixir
+defmodule MyApp.Repo.Migrations.AddAuditsToExistingTable do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    alter table(:existing_posts) do
+      audits :users
+    end
+  end
+end
+```
+
+### Custom Reference Options
+
+```elixir
+defmodule MyApp.Repo.Migrations.CreatePosts do
+  use Ecto.Migration
+  import EctoIRS.Migration
+
+  def change do
+    create table(:posts) do
+      add :title, :string
+      
+      audits :users,
+        column: :user_id,
+        on_delete: :nilify_all,
+        on_update: :update_all
+      
+      timestamps()
+    end
+  end
+end
+```
+
+## Configuration
+
+### Repository Configuration
+
+Configure default audit options at the repository level:
+
+```elixir
+config :my_app, MyApp.Repo,
+  migration_audits: [
+    inserted_by: :created_by,
+    updated_by: :modified_by,
+    null: false
+  ]
+```
+
+### Schema Configuration Options
+
+- `inserted_by`: The field name for insertion audit (default: `:inserted_by`)
+- `updated_by`: The field name for update audit (default: `:updated_by`)
+- `references`: The field on the referenced table (default: `:id`)
+- `autogenerate`: MFA tuple for automatic field population
+
+### Migration Configuration Options
+
+- `inserted_by`: Column name prefix for insertion audit (default: `:inserted_by`)
+- `updated_by`: Column name prefix for update audit (default: `:updated_by`)
+- `null`: Whether columns accept null values (default: `false`)
+
+## Best Practices
+
+### 1. Add Indexes for Performance
+
+```elixir
+create index(:posts, [:inserted_by_id])
+create index(:posts, [:updated_by_id])
+```
+
+### 2. Use Consistent Naming
+
+Stick to either the default names or establish a consistent naming convention across your application.
+
+### 3. Consider Nullable Columns
+
+Decide whether audit fields should be required based on your application's security requirements.
+
+### 4. Preload Associations
+
+Always preload audit associations when you need to access the audit information:
+
+```elixir
+posts = MyApp.Repo.all(MyApp.Post) |> MyApp.Repo.preload([:inserted_by, :updated_by])
+```
+
+## Development
+
+### Running Tests
+
+```bash
+mix test
+```
+
+### Code Quality
+
+```bash
+mix credo          # Run static code analysis
+mix dialyzer       # Run type checking
+```
+
+### Documentation
+
+```bash
+mix docs           # Generate documentation
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.