blib/lib/PAGI/Stash.pm

filter: Statementstmt 100% 55 / 55 Branchbran 95.8% 23 / 24 Conditioncond 90.0% 9 / 10 MC/DCmcdc 83.3% 5 / 6 Subroutinesub 100% 12 / 12 Podpod 100% 9 / 9 totaltotal 97.4% 113 / 116 CC 19 SCAR 14.0
CC
19
Cov
98%
new
7.0
get
6.0
set
4.0
CRAP 4.1
« blib/lib/PAGI/WebSocket.pm ↑ Summary blib/lib/PAGI/Middleware/Session/State/Cookie.pm »
1 package PAGI::Stash;
2 18 $PAGI::Stash::VERSION = '0.002002';
3 18 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 18 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 18 ▶use Scalar::Util 'blessed';
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 PAGI::Stash - Standalone helper for per-request shared state
10  
11 =head1 SYNOPSIS
12  
13 use PAGI::Stash;
14  
15 # Middleware sets shared state for downstream handlers
16 my $auth_middleware = sub ($app) {
17 async sub ($scope, $receive, $send) {
18 my $stash = PAGI::Stash->new($scope);
19 $stash->set(user => authenticate($scope));
20 await $app->($scope, $receive, $send);
21 };
22 };
23  
24 # Handler reads what middleware stored
25 async sub ($scope, $receive, $send) {
26 my $stash = PAGI::Stash->new($scope);
27 my $user = $stash->get('user'); # dies if missing
28 my $theme = $stash->get('theme', 'dark'); # default if missing
29 ...
30 };
31  
32 =head1 DESCRIPTION
33  
34 PAGI::Stash wraps C<< $scope->{'pagi.stash'} >> and provides a clean
35 accessor interface with strict key checking. It is a standalone helper
36 not attached to any protocol object.
37  
38 The strict C<get()> method dies when a key does not exist, catching
39 typos at runtime. Use the two-argument form C<get($key, $default)>
40 for keys that may or may not be present.
41  
42 The stash lives in the PAGI scope hashref and is shared across all
43 middleware, handlers, and protocol objects processing the same request.
44  
45 =head1 CONSTRUCTOR
46  
47 =head2 new
48  
49 my $stash = PAGI::Stash->new($scope);
50 my $stash = PAGI::Stash->new($request); # any object with ->scope
51 my $stash = PAGI::Stash->new(@_); # extra args ignored
52  
53 Scope-based constructor. Resolves to the C<< $scope->{'pagi.stash'} >>
54 hashref, creating it lazily if it does not exist. Accepts a scope hashref
55 directly, or any blessed object with a C<scope()> method. Extra positional
56 arguments are silently ignored.
57  
58 =head2 from_data
59  
60 my $stash = PAGI::Stash->from_data({ user => 'alice' });
61  
62 Test convenience constructor. Wraps a raw hashref directly as the
63 backing data, bypassing scope resolution.
64  
65 =cut
66  
67 50 ▶sub new {
Subroutine new: called CC=7 SCAR=19.5
Pod documented
68 50 my ($class, @args) = @_;
69  
70 50 my $arg = $args[0];
71  
72 # Object with ->scope method (e.g., PAGI::Request, PAGI::SSE)
73 50 ▶ if (blessed($arg) && $arg->can('scope')) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($arg) and $arg->can("scope")) 21 29 50
Condition66%2/3
builtin::blessed($arg) and $arg->can("scope")
!ll&&!rl&&r
29021
MC/DC50%1/2
builtin::blessed($arg) and $arg->can("scope")
builtin::blessed($arg) $arg->can("scope")
Truth table66%2/3
A and B
A= builtin::blessed($arg)B= $arg->can("scope")
ABresult
0X0
100
111
74 21 my $scope = $arg->scope;
75 21 ▶ die "PAGI::Stash requires scope hashref from ->scope method\n"
Branch: 1 branch
BranchTrueFalseTotal
unless ref $scope eq "HASH" 0 21 21
76 unless ref $scope eq 'HASH';
77 21 ▶ $scope->{'pagi.stash'} //= {};
Condition100%2/2
$scope->{"pagi.stash"} //= {}
l!l
615
MC/DC100%1/1
$scope->{"pagi.stash"} //= {}
$scope->{"pagi.stash"}
Truth table100%2/2
A
A= $scope->{"pagi.stash"}
Aresult
11
00
78 21 return bless { _data => $scope->{'pagi.stash'} }, $class;
79 }
80  
81 # Unblessed hashref — treat as scope
82 29 ▶ if (ref $arg eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $arg eq "HASH") 26 3 29
83 26 ▶ $arg->{'pagi.stash'} //= {};
Condition100%2/2
$arg->{"pagi.stash"} //= {}
l!l
422
MC/DC100%1/1
$arg->{"pagi.stash"} //= {}
$arg->{"pagi.stash"}
Truth table100%2/2
A
A= $arg->{"pagi.stash"}
Aresult
11
00
84 26 return bless { _data => $arg->{'pagi.stash'} }, $class;
85 }
86  
87 3 die "PAGI::Stash requires a scope hashref or object with ->scope method\n";
88 }
89  
90 27 ▶sub from_data {
Subroutine from_data: called CC=2 SCAR=6.9
Pod documented
91 27 my ($class, $data) = @_;
92 27 ▶ die "from_data() requires a hashref\n" unless ref $data eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $data eq "HASH" 2 25 27
93 25 return bless { _data => $data }, $class;
94 }
95  
96 =head1 METHODS
97  
98 =head2 get
99  
100 my $val = $stash->get('user'); # strict: dies if missing
101 my $val = $stash->get('theme', 'dark'); # permissive: returns default
102  
103 With one argument, dies if the key does not exist. The error message
104 lists available keys (10 or fewer) or reports the count.
105  
106 With two arguments, returns the default if the key is missing.
107  
108 =cut
109  
110 57 ▶sub get {
Subroutine get: called CC=6 SCAR=17.9
Pod documented
111 57 my ($self, @args) = @_;
112 57 ▶ die "get() requires 1 or 2 arguments\n" if @args == 0 || @args > 2;
Branch: 1 branch
BranchTrueFalseTotal
if @args == 0 or @args > 2 2 55 57
Condition100%3/3
@args == 0 or @args > 2
l!l&&r!l&&!r
1155
MC/DC100%2/2
@args == 0 or @args > 2
@args == 0 @args > 2
Truth table100%3/3
A or B
A= @args == 0B= @args > 2
ABresult
1X1
011
000
113 55 my ($key, @rest) = @args;
114 55 ▶ if (!exists $self->{_data}{$key}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"_data"}{$key}) 7 48 55
115 7 ▶ return $rest[0] if @rest;
Branch: 1 branch
BranchTrueFalseTotal
if @rest 4 3 7
116 3 my @all_keys = sort keys %{$self->{_data}};
117 3 ▶ if (@all_keys <= 10) {
Branch: 1 branch
BranchTrueFalseTotal
if (@all_keys <= 10) { } 2 1 3
118 2 die "Stash key '$key' does not exist. Available keys: "
119 . join(', ', @all_keys) . "\n";
120 }
121 else {
122 1 die "Stash key '$key' does not exist (stash has "
123 . scalar(@all_keys) . " keys)\n";
124 }
125 }
126 48 return $self->{_data}{$key};
127 }
128  
129 =head2 set
130  
131 $stash->set(user => $u);
132 $stash->set(user => $u, role => 'admin');
133 $stash->set(user => $u)->set(role => 'admin');
134  
135 Sets key-value pairs. Returns C<$self> for chaining. No-ops on zero
136 args. Dies on odd number of args.
137  
138 =cut
139  
140 46 ▶sub set {
Subroutine set: called CC=4 SCAR=13.9
Pod documented
141 46 my ($self, @args) = @_;
142 46 ▶ return $self unless @args;
Branch: 1 branch
BranchTrueFalseTotal
unless @args 1 45 46
143 45 ▶ die "set() requires key => value pairs\n" if @args % 2;
Branch: 1 branch
BranchTrueFalseTotal
if @args % 2 2 43 45
144 43 my %pairs = @args;
145 43 $self->{_data}{$_} = $pairs{$_} for CORE::keys %pairs;
146 43 return $self;
147 }
148  
149 =head2 exists
150  
151 if ($stash->exists('user')) { ... }
152  
153 Returns true (1) if the key exists, false (0) otherwise.
154  
155 =cut
156  
157 10 ▶sub exists {
Subroutine exists: called CC=2 SCAR=6.9
Pod documented
158 10 my ($self, $key) = @_;
159 10 ▶ return exists $self->{_data}{$key} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'_data'}{$key} ? : 3 7 10
160 }
161  
162 =head2 delete
163  
164 $stash->delete('user');
165 $stash->delete('user', 'role', 'debug');
166  
167 Removes one or more keys. Returns C<$self> for chaining.
168  
169 =cut
170  
171 4 ▶sub delete {
Subroutine delete: called CC=2 SCAR=6.9
Pod documented
172 4 my ($self, @keys) = @_;
173 4 delete $self->{_data}{$_} for @keys;
174 4 return $self;
175 }
176  
177 =head2 keys
178  
179 my @keys = $stash->keys;
180  
181 Returns all keys in the stash.
182  
183 =cut
184  
185 2 ▶sub keys {
Subroutine keys: called CC=1 SCAR=0.0
Pod documented
186 2 my ($self) = @_;
187 2 return keys %{$self->{_data}};
188 }
189  
190 =head2 slice
191  
192 my %subset = $stash->slice('user', 'role', 'theme');
193  
194 Returns a hash of key-value pairs for the requested keys. Missing keys
195 are silently skipped.
196  
197 =cut
198  
199 3 ▶sub slice {
Subroutine slice: called CC=2 SCAR=6.9
Pod documented
200 3 my ($self, @keys) = @_;
201 3 ▶ return map { CORE::exists($self->{_data}{$_}) ? ($_ => $self->{_data}{$_}) : () } @keys;
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'_data'}{$_} ? : 3 4 7
202 }
203  
204 =head2 data
205  
206 my $href = $stash->data;
207 $href->{user} = $val;
208  
209 Returns the raw backing hashref. Mutations are visible through
210 C<get()>/C<set()> since they operate on the same reference.
211  
212 =cut
213  
214 15 ▶sub data {
Subroutine data: called CC=1 SCAR=0.0
Pod documented
215 15 my ($self) = @_;
216 15 return $self->{_data};
217 }
218  
219 18 1;
220  
221 __END__
« blib/lib/PAGI/WebSocket.pm ↑ Summary blib/lib/PAGI/Middleware/Session/State/Cookie.pm »