HawkEx.CSV (hawk_ex v0.1.0)

Copy Markdown View Source

CSV export tools for Phoenix SaaS applications.

HawkEx.CSV can generate CSV content immediately for small datasets or create an asynchronous export record for background processing through Oban. Built-in formatters cover subscriptions and audit logs, and applications can add their own formatters by implementing HawkEx.CSV.Formatter.

Synchronous export

Returns a CSV string directly. Suitable for small datasets.

case HawkEx.CSV.export(account, :subscriptions) do
  {:ok, csv, row_count} ->
    conn
    |> put_resp_content_type("text/csv")
    |> put_resp_header("content-disposition", ~s(attachment; filename="subscriptions.csv"))
    |> send_resp(200, csv)

  {:error, reason} ->
    # handle error
end

Async export (requires Oban)

Creates an export record and enqueues a background job. The CSV is generated by HawkEx.CSV.ExportWorker and written through the configured storage adapter.

{:ok, export} = HawkEx.CSV.export_async(account, :subscriptions)
# export.status == "pending"

# Listen for completion:
# HawkEx.Events will emit "csv.export.completed" when done

Built-in export types

  • :subscriptions - all subscriptions for the account.
  • :audit_logs - all audit log entries for the account.

Custom formatters

HawkEx.CSV.export(account, MyApp.CSV.Formatters.Users)

Summary

Functions

export(account, formatter)

Generates a CSV synchronously and returns the content.

export_async(account, formatter)

Creates an export record and enqueues an Oban job.

get_export(id)

Returns a single export by id.

list_exports(account)

Returns all CSV export records for an account, newest first.

read_export(export)

Reads the generated CSV content for a completed export.

recent_exports(opts \\ [])

Returns a page of CSV exports across all accounts, newest first.

search_exports(query, opts \\ [])

Fast typeahead search across CSV exports by type.

Functions

export(account, formatter)

Generates a CSV synchronously and returns the content.

formatter may be a built-in atom (:subscriptions or :audit_logs) or a module that implements HawkEx.CSV.Formatter.

Returns {:ok, csv_string, row_count} or {:error, reason}.

export_async(account, formatter)

Creates an export record and enqueues an Oban job.

Returns {:ok, export} after the export record has been updated with the Oban job id. The CSV is generated in the background.

Requires Oban to be installed and configured:

config :my_app, Oban,
  repo: MyApp.Repo,
  queues: [hawk_ex_exports: 2]

Returns {:error, :oban_not_available} if Oban is not installed or no Oban instance has been configured through config :hawk_ex, oban: ....

get_export(id)

Returns a single export by id.

Returns {:ok, export} when found or {:error, :not_found} otherwise.

list_exports(account)

Returns all CSV export records for an account, newest first.

read_export(export)

Reads the generated CSV content for a completed export.

Returns {:ok, content} from the configured storage adapter. For exports that are not completed, returns {:error, {:export_not_ready, status}}.

recent_exports(opts \\ [])

Returns a page of CSV exports across all accounts, newest first.

Options

  • :page - 1-indexed page number. Defaults to 1.
  • :per_page - rows per page. Defaults to 50.
  • :search - optional search term matching export_type.

Returns %{entries:, page:, per_page:, total_count:, total_pages:}.

Example

HawkEx.CSV.recent_exports(page: 1, per_page: 50)
# => %{entries: [...], page: 1, per_page: 50, total_count: 45, total_pages: 1}

HawkEx.CSV.recent_exports(search: "subscriptions")
# => only exports where export_type matches "subscriptions"

search_exports(query, opts \\ [])

Fast typeahead search across CSV exports by type.

Accepts :limit in opts, defaulting to 5.