File Coverage

=head1 NAME

Class::Simple::Readonly::Cached - cache messages to an object

=head1 VERSION

Version 0.13

=cut

=head1 SYNOPSIS

A caching decorator for L<Class::Simple>-based (and arbitrary) objects.

It is up to the caller to maintain the cache if the object comes out of
sync with the cache, for example by changing its state.

    use Class::Simple::Readonly::Cached;

    my $obj = Class::Simple->new();
    $obj->val('foo');
    my $cached = Class::Simple::Readonly::Cached->new(
        object => $obj,
        cache  => {},
    );

    my $val  = $cached->val();   # calls the real object
    my $val2 = $cached->val();   # served from cache

    $val = $cached->val(a => 'b');   # args form part of the cache key

Note that when the object goes out of scope (DESTROY is called), the
cache is cleared automatically.

=head1 DESCRIPTION

Wraps any Perl object in a transparent caching layer.  Every method call
is intercepted via AUTOLOAD; on the first call (a I<miss>) the result is
stored in the cache and returned.  Subsequent identical calls (same method
name, same argument list) are I<hits> and are served directly from the
cache without touching the inner object.

Two cache backends are supported: a plain hash reference (fast, in-process,
no expiry) and any CHI-compatible object (persistent, shared, with expiry).

=head1 SUBROUTINES/METHODS

=head2 new

Construct a caching proxy around any Perl object.

=head3 Arguments

=over 4

=item C<cache> (mandatory)

Either a plain hash reference (C<{}>) or a CHI-compatible object that
implements C<get()>, C<set()>, and C<purge()>.

=item C<object> (optional)

The object to wrap.  Defaults to a bare L<Class::Simple> instance.
Must be a reference; a plain scalar argument causes a C<carp> and an
C<undef> return.  Wrapping an already-wrapped
C<Class::Simple::Readonly::Cached> object returns the existing wrapper
with a warning.

=item C<quiet> (optional, boolean)

Suppress the double-wrap warning when non-zero.

=back

=head3 Returns

A C<Class::Simple::Readonly::Cached> object, or C<undef> on invalid
C<object>.  Croaks on invalid C<cache>.

=head3 EXAMPLE

    use CHI;
    use Class::Simple::Readonly::Cached;

    # --- Hash-ref cache (in-process, no expiry) ---
    my $obj    = My::Expensive->new();
    my $cached = Class::Simple::Readonly::Cached->new(
        object => $obj,
        cache  => {},
    );
    my $result  = $cached->compute();   # calls the real object
    my $result2 = $cached->compute();   # from cache -- object not called

    # --- CHI cache (persistent, file-based) ---
    use File::Temp qw(tempdir);
    my $chi = CHI->new(driver => 'File', root_dir => tempdir(CLEANUP => 1));
    my $cached2 = Class::Simple::Readonly::Cached->new(
        object => $obj,
        cache  => $chi,
    );

    # --- Clone an existing wrapper ---
    my $clone = $cached->new();   # shares the same inner object and cache

=head3 API SPECIFICATION

    # Input
    {
        cache  => { type => ['hashref', 'object'], required => 1  },
        object => { type => 'ref',                 optional => 1  },
        quiet  => { type => 'bool',                optional => 1  },
    }

    # Output
    { type => 'object', class => 'Class::Simple::Readonly::Cached',
      optional => 1 }

=head3 MESSAGES

    Message                                                 Meaning                              Resolution
    -------                                                 -------                              ----------
    Cache must be ref to HASH or object                     cache is not a hashref or blessed    Pass \%hash or a CHI object.
                                                            object
    Cache object must implement get(), set(), and purge()   blessed cache lacks required API      Use a CHI-compatible object.
    $object must be a reference, not a scalar               object is a plain string             Pass a blessed reference.
    warning: $object is already a cached object             wrapping an already-wrapped object   Reuse the returned wrapper.
    $object is already cached at LINE of FILE               double-wrap detected                 Reuse the existing wrapper;
                                                                                                 set quiet => 1 to silence.

=head3 PSEUDOCODE

    1.  If class is undef:           carp and return undef   (::new() misuse)
    2.  If class is blessed:         merge params into a clone and return
    3.  Validate cache:              croak if not a hashref or CHI-compatible object
    4.  Validate object:             carp+return if scalar; return existing
                                     wrapper if already __PACKAGE__
    5.  Create inner object:         Class::Simple->new(non-wrapper params)
                                     unless object was supplied
    6.  Check double-wrap registry:  if object in %cached, carp and return
                                     existing wrapper (unless quiet)
    7.  Bless and register:          bless $params, $class; set _class = $class;
                                     call _build_cache_accessors to install
                                     _get/_set coderefs and _cache_is_hash;
                                     store in %cached with caller file and line
    8.  Return $self

=cut

=head2 object

Return the inner (wrapped) object.

=head3 Returns

The blessed reference that was passed as C<object> to C<new()>.

=head3 EXAMPLE

    # Bypass the cache to mutate state directly.
    $cached->object()->reset();

=head3 API SPECIFICATION

    # Input  none
    # Output { type => 'object' }

=head3 MESSAGES

    (none)

=cut

=head2 state

Return a snapshot of cache hit and miss counts per cache key.
Primarily useful for performance profiling and white-box tests.

=head3 Returns

A hash reference:

=over 4

=item C<hits>

Hash reference mapping each cache key to the number of times the
result was served from cache.  C<undef> until the first hit.

=item C<misses>

Hash reference mapping each cache key to the number of times the
inner object was actually invoked.  C<undef> until the first miss.

=back

=head3 EXAMPLE

    my $s = $cached->state();
    my $hits   = do { my $n=0; $n += $_ for values %{$s->{hits}   // {}}; $n };
    my $misses = do { my $n=0; $n += $_ for values %{$s->{misses} // {}}; $n };
    printf "Hit rate: %.0f%%\n", 100 * $hits / ($hits + $misses) if $hits + $misses;

=head3 API SPECIFICATION

    # Input  None
    # Output { type => 'hashref',
    #          keys => { hits   => 'hashref|undef',
    #                    misses => 'hashref|undef' } }

=head3 MESSAGES

    (none)

=cut

=head2 can

Report whether the inner object (or this class) can respond to a
given method.  Overrides C<UNIVERSAL::can> to account for the
decorator pattern.

=head3 Returns

A code reference if the method exists, C<undef> otherwise.

=head3 EXAMPLE

    my $code = $cached->can('compute');
    $code->($cached) if $code;

=head3 API SPECIFICATION

    # Input  { self   => { type => 'object|string' },
    #          method => { type => 'string' } }
    # Output { type => 'coderef|undef' }

=head3 MESSAGES

    (none)

=cut

=head2 isa

Test class membership, delegating to the inner object's class
hierarchy when needed.  Overrides C<UNIVERSAL::isa> to support the
transparent decorator pattern.

=head3 Returns

True if the wrapper or its inner object is-a C<$class>.

=head3 EXAMPLE

    $cached->isa('My::Domain::Object');   # true if inner object is

=head3 API SPECIFICATION

    # Input  { self  => { type => 'object|string' },
    #          class => { type => 'string' } }
    # Output { type => 'bool' }

=head3 MESSAGES

    (none)

=cut

=head2 AUTOLOAD

Not called directly.  Intercepts every method call not explicitly
defined in this package, looks up the result in the cache, and on a
miss proxies the call to the inner object and stores the result.

Cache lookup and storage use the pre-built C<_get>/C<_set> coderefs
installed by C<_build_cache_accessors> at construction time, so the
backend-type decision (HASH vs CHI) is made once -- never on each
dispatch.

Three stored-value forms are mutually exclusive and exhaustive:

=over 4

=item ARRAY ref

The wrapped method previously returned a list.  Served as C<@array>
in list context, or C<$array[-1]> in scalar context.

=item C<$UNDEF_SENTINEL>

The wrapped method returned C<undef> or an empty list.  Stored as the
sentinel string so a cache miss (undefined value) can be distinguished
from a cached C<undef>.

=item Any other defined scalar

The wrapped method returned a plain scalar in scalar context.  Served
as-is in scalar context.  If the caller subsequently asks for the
same key in list context, the scalar cannot be adapted -- the call is
treated as a miss and the method is re-invoked so the array form gets
independently cached.

=back

Handles C<DESTROY> specially: removes the wrapper from the double-wrap
registry and clears cache entries whose keys begin with C<$self->{_class}>
(Invariant I3 guarantees this is always set), then returns without
calling the inner object's DESTROY.

=cut

=head1 LIMITATIONS

=over 4

=item B<Not safe for mutable objects>

The cache is never invalidated automatically.  If the inner object's
state changes after caching, the wrapper will return stale data.  The
caller must either reset the cache manually or avoid using this module
with objects that mutate.

=item B<Argument serialisation is naive>

Cache keys are built by joining defined arguments with C<::>.  Two
different argument lists can therefore produce the same key if an
argument itself contains C<::> (e.g. C<foo('a::b', 'c')> vs
C<foo('a', 'b::c')>).  Callers that pass arguments containing C<::>
should use a CHI backend with a custom key serialiser.

=item B<Undefined arguments are collapsed>

Undefined values in the argument list are silently dropped from the
cache key, so C<foo(undef)> and C<foo()> share a cache entry.

=item B<Scalar-then-list context mismatch is a miss>

If a method is first called in scalar context and then in list
context with identical arguments, the second call is a cache miss
and re-invokes the inner object.  Both results are then independently
cached.

=item B<C<can('new')> returns a code reference, not a boolean>

For strict correctness C<can> returns C<\&new> for the C<'new'>
method rather than the boolean C<1>.  The code reference is callable
but callers who compare it with C<==> to C<1> will see a mismatch.

=item B<Does not work with L<Memoize>>

C<Memoize> intercepts at the symbol-table level and conflicts with
the C<AUTOLOAD> dispatch used here.

=back

=head1 AUTHOR

Nigel Horne, C<< <njh at nigelhorne.com> >>

=head1 BUGS

Please report any bugs or feature requests to
L<https://github.com/nigelhorne/Class-Simple-Readonly-Cached/issues>.

=head1 SEE ALSO

=over 4

=item * L<Test Dashboard|https://nigelhorne.github.io/Class-Simple-Readonly-Cached/coverage/>

=item * L<Class::Simple>

=item * L<CHI>

=item * L<Data::Reuse>

Values are shared between C<Class::Simple::Readonly::Cached> objects,
since they are read-only.

=item * L<constant::defer>

=back

=head1 SUPPORT

This module is provided as-is without any warranty.

You can find documentation for this module with the perldoc command.

    perldoc Class::Simple::Readonly::Cached

=over 4

=item * MetaCPAN

L<https://metacpan.org/release/Class-Simple-Readonly-Cached>

=item * Source Repository

L<https://github.com/nigelhorne/Class-Simple-Readonly-Cached>

=item * CPAN Testers

L<http://matrix.cpantesters.org/?dist=Class-Simple-Readonly-Cached>

=back

=encoding UTF-8

=head1 FORMAL SPECIFICATION

=head2 new

    new : (C x P) -> (W | undef)

    C = class name string
    P = { cache : (HashRef | CacheObj), object? : Ref, quiet? : Bool, ... }
    W = blessed P in C

    valid_cache(c) :=
        ref(c) = 'HASH'
        OR ( blessed(c) AND c.can('get') AND c.can('set') AND c.can('purge') )

    Precondition:
        valid_cache(P.cache)

    Post-construction invariants (hold for all W returned by new()):
        W._class         = C
        W._cache_is_hash = (ref(P.cache) = 'HASH')
        W._get           = λk. (W._cache_is_hash ? W.cache[k] : W.cache.get(k))
        W._set           = λ(k,v). (W._cache_is_hash ? W.cache[k]:=v
                                                      : W.cache.set(k,v,'never'))

    Double-wrap invariant:
        forall o in Dom(cached): new(C, {object: o, ...}) = cached[o].object

    Clone (object invocation):
        forall w : W: w.new(P') = bless( merge(w, P'), ref(w) )
        Corollary: if cache in Dom(P'), rebuild _get/_set/_cache_is_hash for P'.cache

=head2 object

    object : W -> Ref

    forall w : W: object(w) = w.object

=head2 state

    state : W -> HashRef

    forall w : W: state(w) = { hits => w._hits, misses => w._misses }

=head2 can

    can : (W|Str x Str) -> (CodeRef | undef)

    forall w : W, m : Str:
      can(w, 'new') = \&new
      can(w, m)     = w.object.can(m)  OR SUPER::can(w, m)

=head2 isa

    isa : (W x Str) -> Bool

    forall w : W, c : Str:
      isa(w, c) = 1  if c in { ref(w), 'Class::Simple::Readonly::Cached' }
               | 1  if SUPER::isa(w, c)
               | w.object.isa(c)  if ref(w)
               | 0  otherwise

=head2 autoload

    autoload : (W x M x A*) -> R

    M  = method name string
    A* = argument tuple (possibly empty)
    R  = scalar | list | undef

    Cache key:
        k(w, m, a) := w._class ++ '::' ++ m ++ '::' ++ defined_args(a)
        (w._class = ref(w), pre-computed once in new() to avoid ref() per dispatch)

    Caching law:
        get(cache(w), k(w,m,a)) = v, v != undef
            => autoload(w, m, a) = v          (cache hit)
        get(cache(w), k(w,m,a)) = undef
            => v = w.object.m(a)
               set(cache(w), k(w,m,a), v)
               autoload(w, m, a) = v          (cache miss)

=head1 LICENSE AND COPYRIGHT

Author Nigel Horne: C<njh@nigelhorne.com>
Copyright (C) 2019-2026 Nigel Horne

Usage is subject to the GPL2 licence terms.
If you use it,
please let me know.

=cut