importexport

README

togo-framework/import-export

CSV & Excel data import/export for togo — mapping, validation, resources.

Install

togo install togo-framework/import-export

The togo answer to Laravel Excel / django-import-export: export any rows or a registered resource to CSV/XLSX, and import from CSV/XLSX with column mapping, header detection, and per-row validation that reports row/column errors instead of failing the whole file.

Usage

Export

ie, _ := importexport.FromKernel(k)

rows := []map[string]any{{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}}
csvBytes,  _ := ie.Export(ctx, rows, importexport.ExportOpts{Format: "csv",  Columns: []string{"id", "name"}})
xlsxBytes, _ := ie.Export(ctx, rows, importexport.ExportOpts{Format: "xlsx", Sheet: "People"})

Import (mapping + validation)

data := []byte("Identifier,Full Name\n1,Alice\n,Missing\n")
rows, rowErrors, err := ie.Import(ctx, data, importexport.ImportOpts{
    Format:  "csv",
    Mapping: map[string]string{"Identifier": "id", "Full Name": "name"},
    Validate: func(row map[string]any) error {
        if row["id"] == "" { return errors.New("id is required") }
        return nil
    },
})
// rows = valid rows (mapped to id/name); rowErrors = []RowError{ {Row:2, Message:"id is required"} }

Registered resources

importexport.Register(importexport.Resource{
    Name:    "people",
    Columns: []string{"id", "name"},
    Fetch:   func(ctx context.Context) ([]map[string]any, error) { return loadPeople(ctx) },
    Insert:  func(ctx context.Context, row map[string]any) error { return savePerson(ctx, row) },
})
// then export/import by name via the Go API or REST.

REST API

Method	Path	Description
GET	/api/export/{resource}?format=csv|xlsx	Download a registered resource
POST	/api/import/{resource}?format=csv|xlsx	Upload + insert; returns {inserted, errors}

Configuration

No required env. XLSX uses excelize; CSV uses the stdlib.

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package importexport adds CSV & Excel (XLSX) data import/export to togo — the togo answer to Laravel Excel / django-import-export.

Export any rows ([]map[string]any) or a registered Resource to CSV/XLSX, and import from CSV/XLSX with column mapping, header detection, and per-row validation that reports row/column errors instead of failing the whole file.

ie, _ := importexport.FromKernel(k)
csv, _ := ie.Export(ctx, rows, importexport.ExportOpts{Format: "csv", Columns: []string{"id","name"}})
out, errs, _ := ie.Import(ctx, data, importexport.ImportOpts{Format: "xlsx"})

Index

• func Register(r Resource)
• type ExportOpts
• type ImportOpts
• type Resource
• type RowError
  • func (e RowError) Error() string
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) Export(ctx context.Context, rows []map[string]any, opts ExportOpts) ([]byte, error)
  • func (s *Service) ExportResource(ctx context.Context, name string, opts ExportOpts) ([]byte, error)
  • func (s *Service) Import(ctx context.Context, data []byte, opts ImportOpts) ([]map[string]any, []RowError, error)
  • func (s *Service) ImportResource(ctx context.Context, name string, data []byte, opts ImportOpts) (int, []RowError, error)

Functions

func Register

func Register(r Resource)

Register registers a named resource (call from a plugin init()/Boot).

Types

type ExportOpts

type ExportOpts struct {
	Format  string   // "csv" (default) or "xlsx"
	Columns []string // column order; inferred (sorted) from the rows when empty
	Sheet   string   // XLSX sheet name (default "Sheet1")
}

ExportOpts controls an export.

type ImportOpts

type ImportOpts struct {
	Format   string            // "csv" (default) or "xlsx"
	Sheet    string            // XLSX sheet to read (default first)
	Mapping  map[string]string // source header -> target field; identity when empty
	Validate func(row map[string]any) error
}

ImportOpts controls an import.

type Resource

type Resource struct {
	Name    string
	Columns []string
	Fetch   func(ctx context.Context) ([]map[string]any, error) // for export
	Insert  func(ctx context.Context, row map[string]any) error // for import
}

Resource is a named, importable/exportable dataset.

type RowError

type RowError struct {
	Row     int    `json:"row"` // 1-based data row (excludes header)
	Column  string `json:"column,omitempty"`
	Message string `json:"message"`
}

RowError reports a problem with one imported row.

func (RowError) Error

func (e RowError) Error() string

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is the import/export runtime stored on the kernel.

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel returns the import-export Service.

func (*Service) Export

func (s *Service) Export(ctx context.Context, rows []map[string]any, opts ExportOpts) ([]byte, error)

Export renders rows to CSV or XLSX bytes.

func (*Service) ExportResource

func (s *Service) ExportResource(ctx context.Context, name string, opts ExportOpts) ([]byte, error)

ExportResource fetches a registered resource and exports it.

func (*Service) Import

func (s *Service) Import(ctx context.Context, data []byte, opts ImportOpts) ([]map[string]any, []RowError, error)

Import parses CSV/XLSX into rows, applying mapping + validation. It returns the valid rows, a list of per-row errors, and a fatal parse error (if any).

func (*Service) ImportResource

func (s *Service) ImportResource(ctx context.Context, name string, data []byte, opts ImportOpts) (int, []RowError, error)

ImportResource imports + inserts rows into a registered resource. Rows that fail validation or insert are reported; the rest are inserted.