/ 
Concierge-Users-v0.7.3
/ Concierge::Users::File

NAME

Concierge::Users::File - CSV/TSV flat-file storage backend for Concierge::Users

VERSION

v0.7.3

SYNOPSIS

use Concierge::Users;

# Setup with the file backend (TSV, default)
Concierge::Users->setup({
    storage_dir             => '/var/lib/myapp/users',
    backend                 => 'file',
    include_standard_fields => 'all',
});

# Setup with CSV format
Concierge::Users->setup({
    storage_dir             => '/var/lib/myapp/users',
    backend                 => 'file',
    file_format             => 'csv',
    include_standard_fields => [qw/ email phone /],
});

# Runtime -- the backend is loaded automatically
my $users = Concierge::Users->new('/var/lib/myapp/users/users-config.json');

DESCRIPTION

Concierge::Users::File implements the Concierge::Users storage interface using a single CSV or TSV flat file via Text::CSV. All records are stored in <storage_dir>/users.tsv (or users.csv), with the first row as a header containing field names.

The file format is selected at setup time with the file_format parameter ('csv' or 'tsv'; default 'tsv').

Write behavior: Additions append to the file. Updates and deletes perform a full-file rewrite (read all rows, modify, write back). This is simple and reliable but means write performance is proportional to file size.

Archiving: When setup() is called and the data file already contains user rows, the existing file is renamed to users_YYYYMMDD_HHMMSS.tsv (or .csv) before a new file is created.

Applications interact with this module indirectly through the Concierge::Users API; direct instantiation is not required.

METHODS

configure

my $result = Concierge::Users::File->configure(\%setup_config);

Class method called by Concierge::Users->setup(). Creates (or archives and recreates) the data file with a header row. Returns a hashref with success, message, and config.

new

my $backend = Concierge::Users::File->new(\%runtime_config);

Constructor called by Concierge::Users->new(). Initializes the Text::CSV parser with the saved format. Croaks if the parser cannot be created.

add

my $result = $backend->add($user_id, \%initial_record);

Appends a new row to the data file. Sets created_date and last_mod_date to the current UTC timestamp.

fetch

my $result = $backend->fetch($user_id);

Reads the file sequentially to find the row with the matching user_id. Returns { success => 1, data => \%row } or { success => 0, message => "..." }.

update

my $result = $backend->update($user_id, \%updates);

Rewrites the entire file, applying updates to the matching row. Read-only fields (user_id, created_date, last_mod_date) are stripped automatically; last_mod_date is refreshed.

delete

my $result = $backend->delete($user_id);

Rewrites the file, omitting the row matching user_id.

list

my $result = $backend->list(\%filters, \%options);

Reads all rows and applies the parsed filter structure (see "FILTER DSL" in Concierge::Users::Meta). With no filters, returns all users. Result: { data => \@rows, total_count => $n }.

DEPENDENCIES

Text::CSV

SEE ALSO

Concierge::Users -- main API

Concierge::Users::Meta -- field definitions and validators

Concierge::Users::Database, Concierge::Users::YAML -- alternative backends

AUTHOR

Bruce Van Allen <bva@cruzio.com>

LICENSE

This module is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.