PhoenixKit.Modules.Entities.Mirror.Importer (phoenix_kit v1.7.71)

Handles import of entities and entity data from JSON files with conflict resolution.

Each JSON file contains both the entity definition and all its data records.

File Format

{
  "export_version": "1.0",
  "exported_at": "2025-12-11T10:30:00Z",
  "definition": { ... entity schema ... },
  "data": [ ... array of data records ... ]
}

Conflict Strategies

:skip - Skip import if record already exists (default)
:overwrite - Replace existing record with imported data
:merge - Merge imported data with existing record (keeps existing values where new is nil)

Conflict Detection

Entity definitions: matched by name field
Entity data records: matched by entity_name + slug

Summary

Types

conflict_strategy()

import_result()

Functions

detect_conflicts()

Detects all conflicts that would occur during import.

import_all(strategy \\ :skip)

Imports all entities from the mirror directory.

import_entity(entity_name, strategy \\ :skip)

Imports an entity (definition + data) from a JSON file.

import_from_data(arg1, strategy)

Imports from parsed JSON data (definition + data).

import_selected(selections)

Imports selected entities and records based on user selections.

preview_import()

Previews what would be imported without making any changes.

Types

conflict_strategy()

@type conflict_strategy() :: :skip | :overwrite | :merge

import_result()

@type import_result() ::
  {:ok, :created, any()}
  | {:ok, :updated, any()}
  | {:ok, :skipped, any()}
  | {:error, term()}

Functions

detect_conflicts()

@spec detect_conflicts() :: map()

Detects all conflicts that would occur during import.

Returns

%{entity_conflicts: [...], data_conflicts: [...]}

import_all(strategy \\ :skip)

@spec import_all(conflict_strategy()) :: {:ok, map()}

Imports all entities from the mirror directory.

Parameters

strategy - Conflict resolution strategy (default: :skip)

Returns

{:ok, %{definitions: [...], data: [...]}}

import_entity(entity_name, strategy \\ :skip)

@spec import_entity(String.t(), conflict_strategy()) ::
  {:ok, map()} | {:error, term()}

Imports an entity (definition + data) from a JSON file.

Parameters

entity_name - The entity name (file name without .json)
strategy - Conflict resolution strategy (default: :skip)

Returns

{:ok, %{definition: result, data: [results]}} on success
{:error, reason} on failure

import_from_data(arg1, strategy)

@spec import_from_data(map(), conflict_strategy()) :: {:ok, map()} | {:error, term()}

Imports from parsed JSON data (definition + data).

import_selected(selections)

@spec import_selected(map()) :: {:ok, map()}

Imports selected entities and records based on user selections.

Parameters

selections - Map of entity_name => %{definition: action, data: %{slug => action}} where action is :skip, :overwrite, or :merge

Example

selections = %{
  "brand" => %{
    definition: :overwrite,
    data: %{
      "acme-corp" => :overwrite,
      "globex" => :skip
    }
  }
}

Returns

{:ok, %{definitions: [...], data: [...]}}

preview_import()

@spec preview_import() :: map()

Previews what would be imported without making any changes.

Returns data grouped by entity for the import UI, with each entity containing its definition preview and all data record previews.

Returns

%{
  entities: [
    %{
      name: "brand",
      definition: %{name: "brand", action: :create | :identical | :conflict},
      data: [%{slug: "acme", action: :create | :identical | :conflict}, ...]
    },
    ...
  ],
  summary: %{
    definitions: %{total: N, new: N, identical: N, conflicts: N},
    data: %{total: N, new: N, identical: N, conflicts: N}
  }
}