blib/lib/AmberDB/Base/Junk.pm untested

filter: Statementstmt 0.0% 0 / 134 Branchbran 0.0% 0 / 90 Conditioncond 0.0% 0 / 74 MC/DCmcdc 0.0% 0 / 43 Subroutinesub 0.0% 0 / 7 Podpod 0.0% 0 / 4 totaltotal 0.0% 0 / 352 CC 46 SCAR 56.1
CC
46
Cov
0%
junk_transition
420.0
prefetch_junk_rdbm
306.0
junk_rules
56.0
CRAP 272.1
1 package AmberDB::Base::Junk;
2
3 use 5.016;
4 use warnings;
5 use Carp qw(croak cluck);
6
7 our $VERSION = '5.26.6';
8 my $CREATED = '2026-08-28';
9
10 # $rdbm_recs = $adb->prefetch_junk_rdbm($table_info, \@records);
11 # Scans @records for all foreign table keys referenced in junk_rules (e.g. "2->14"),
12 # batch fetches the foreign records via read_list in a single pass,
13 # and stores them in an in-memory map: { $foreign_table => { $id => \@record } }
14 # ---------------------------------------------------------------------
15 sub prefetch_junk_rdbm {
16 my ( $self, $table_info, $records ) = @_;
17
18 return {} unless ref($table_info) eq 'HASH' && $table_info->{use_junk};
19 my $jr = $table_info->{junk_rules} or return {};
20 return {} unless ref($records) eq 'ARRAY' && @$records;
21
22 my @rules = ( ref( $jr->[0] ) eq 'ARRAY' ) ? @$jr : ($jr);
23
24 # 1. junk_rules icindeki foreign iliskisel bloklari tespit et (orn: "2->14")
25 my %rel_blocks; # $b1 => { table => $ref_table, col => $b2 }
26 for my $rule (@rules) {
27 my ($spec) = @$rule;
28 next unless defined $spec;
29 if ( $spec =~ /^(\d+)->(\d+)$/ ) {
30 my ( $b1, $b2 ) = ( $1, $2 );
31 my $blk_info = $table_info->{blocks}->[$b1] if ref( $table_info->{blocks} ) eq 'ARRAY';
32 if ( $blk_info && $blk_info->{rdbm} ) {
33 my $ref_table;
34 if ( ref( $blk_info->{rdbm} ) eq 'HASH' ) {
35 $ref_table = $blk_info->{rdbm}->{table};
36 }
37 elsif ( $blk_info->{rdbm} =~ /^([\w\-]+)[;:,]/ ) {
38 $ref_table = $1;
39 }
40 if ($ref_table) {
41 $rel_blocks{$b1} = { table => $ref_table, col => $b2 };
42 }
43 }
44 }
45 }
46
47 return {} unless %rel_blocks;
48
49 # 2. @records tablosundaki foreign "tableid"leri ve onlara bagli anahtarlari tespit et
50 my %needed_keys; # $ref_table => { $id => 1 }
51 for my $rec (@$records) {
52 next unless ref($rec) eq 'ARRAY';
53 for my $b1 ( keys %rel_blocks ) {
54 my $val = $rec->[$b1];
55 next unless defined $val && $val ne '';
56 my $ref_table = $rel_blocks{$b1}->{table};
57 for my $id ( split /[,;]/, $val ) {
58 $id =~ s/^\s+|\s+$//g;
59 next unless length($id);
60 # Eger cache'de zaten varsa tekrar diskten cekme
61 unless ( $self->get_cache( $ref_table, $id ) ) {
62 $needed_keys{$ref_table}->{$id} = 1;
63 }
64 }
65 }
66 }
67
68 # 3. Cache'de olmayan foreign kayitlari tek seferde (read_list) getir ve cache'e kaydet
69 for my $ref_table ( keys %needed_keys ) {
70 my @ids = keys %{ $needed_keys{$ref_table} };
71 next unless @ids;
72 my @target_recs = $self->read_list( $ref_table, \@ids );
73 for my $trec (@target_recs) {
74 $self->set_cache( $ref_table, $trec->[0], $trec );
75 }
76 }
77
78 # 4. Tum foreign tablolara ait cache haritalarini hazirla
79 my %rdbm_recs; # $ref_table => { $id => \@target_record }
80 for my $b1 ( keys %rel_blocks ) {
81 my $ref_table = $rel_blocks{$b1}->{table};
82 $rdbm_recs{$ref_table} = $self->get_cache($ref_table) || {};
83 }
84
85 return \%rdbm_recs;
86 }
87
88 # $is_junk = $adb->junk_rules($table_info, @record);
89 # $is_junk = $adb->junk_rules($table_info, \@record, \%rdbm_recs);
90 # Returns 1 if record satisfies any junk condition, 0 otherwise.
91 # ------------------------------------------------
92 sub junk_rules {
93
94 my ( $self, $table_info, @args ) = @_;
95
96 return 0 unless ref($table_info) eq 'HASH' && $table_info->{use_junk};
97 my $jr = $table_info->{junk_rules} or return 0;
98
99 my ( $record_ref, $rdbm_recs );
100 if ( @args && ref( $args[0] ) eq 'ARRAY' ) {
101 $record_ref = $args[0];
102 $rdbm_recs = $args[1] if @args > 1 && ref( $args[1] ) eq 'HASH';
103 }
104 elsif ( @args && ref( $args[-1] ) eq 'HASH' ) {
105 $rdbm_recs = pop @args;
106 $record_ref = \@args;
107 }
108 else {
109 $record_ref = \@args;
110 }
111
112 my @rules = ( ref( $jr->[0] ) eq 'ARRAY' ) ? @$jr : ($jr);
113
114 for my $rule (@rules) {
115 my ( $spec, $op, $val ) = @$rule;
116 my $rv = $self->_resolve_field_value( $table_info, $record_ref, $spec, $rdbm_recs );
117 if ( $rv ne '' && $self->_cmp_op( $rv, $op, $val ) ) {
118 return 1; # Herhangi bir kural sağlandıysa JUNK'tır
119 }
120 }
121
122 return 0; # Aktif
123 }
124
125 # $mode = $adb->get_jnktype($table_info, \%opts);
126 # Resolves jnktype mode: 'ALL', 'A', 'AB', 'B', 'BA'
127 # ------------------------------------------------
128 sub get_jnktype {
129
130 my ( $self, $table_info, $opts ) = @_;
131
132 my $mode = ( ref($opts) eq 'HASH' ? ( $opts->{jnktype} // $opts->{use_jnktype} ) : undef )
133 // ( ref($table_info) eq 'HASH' ? ( $table_info->{jnktype} // $table_info->{use_jnktype} ) : undef )
134 // $self->config('jnktype')
135 // 'AB';
136
137 $mode = uc("$mode");
138 if ( $mode eq 'NONE' || $mode eq 'ALL' || $mode eq '0' || $mode eq 'OFF' || $mode eq '' ) {
139 return 'ALL';
140 }
141 return $mode =~ /^(A|AB|B|BA|ALL)$/ ? $mode : 'AB';
142 }
143
144 # =====================================================================
145 # OTOMATİK AKTİF <-> JUNK GEÇİŞİ (State Transitions)
146 # =====================================================================
147
148 # $adb->junk_transition($table_path, $table_info, $tableid, \@pairs);
149 # ------------------------------------------------
150 sub junk_transition {
151
152 my ( $self, $table_path, $table_info, $tableid, $pairs ) = @_;
153
154 return unless ref($table_info) eq 'HASH' && $table_info->{use_junk};
155 return unless ref($pairs) eq 'ARRAY' && @$pairs;
156
157 my ( @became_junk, @became_active, @stayed_active, @stayed_junk );
158
159 for my $pair (@$pairs) {
160 my ( $rid, $old_rec, $new_rec ) = @$pair;
161 next if $self->array_compare( $old_rec, $new_rec );
162
163 my $old_is_junk = $self->junk_rules( $table_info, @$old_rec );
164 my $new_is_junk = $self->junk_rules( $table_info, @$new_rec );
165
166 if ( !$old_is_junk && $new_is_junk ) {
167 push @became_junk, $pair;
168 }
169 elsif ( $old_is_junk && !$new_is_junk ) {
170 push @became_active, $pair;
171 }
172 elsif ( !$old_is_junk && !$new_is_junk ) {
173 push @stayed_active, $pair;
174 }
175 else {
176 push @stayed_junk, $pair;
177 }
178 }
179
180 # 1. Aktif -> Junk Geçişi: A'dan sil, B'ye ekle (Base stream 'keys' değişmez!)
181 if (@became_junk) {
182 my @old_records = map { $_->[1] } @became_junk;
183 my @new_records = map { $_->[2] } @became_junk;
184 my @rids = map { $_->[0] } @became_junk;
185
186 # A akışından sil
187 $self->records_del( $table_path, $table_info, \@rids, $tableid, 'A' );
188 $self->match_del( $table_path, $table_info, \@old_records, 'A' );
189 $self->search_del( $table_path, $table_info, $tableid, \@old_records, 'A' );
190 $self->sort_del( $table_path, $table_info, \@old_records, 'A' ) if $table_info->{sort_block};
191
192 # Facet'ten sil (artık aktif değil)
193 $self->facet_del( $table_path, $table_info, \@old_records )
194 if $table_info->{use_facet};
195
196 # B akışına ekle
197 $self->records_add( $table_path, $table_info, $tableid, \@rids, 'B' );
198 $self->match_add( $table_path, $table_info, \@new_records, 'B' );
199 $self->search_add( $table_path, $table_info, $tableid, \@new_records, 'B' );
200 $self->sort_add( $table_path, $table_info, \@new_records, 'B' ) if $table_info->{sort_block};
201 }
202
203 # 2. Junk -> Aktif Geçişi: B'den sil, A'ya ekle (Base stream 'keys' değişmez!)
204 if (@became_active) {
205 my @old_records = map { $_->[1] } @became_active;
206 my @new_records = map { $_->[2] } @became_active;
207 my @rids = map { $_->[0] } @became_active;
208
209 # B akışından sil
210 $self->records_del( $table_path, $table_info, \@rids, $tableid, 'B' );
211 $self->match_del( $table_path, $table_info, \@old_records, 'B' );
212 $self->search_del( $table_path, $table_info, $tableid, \@old_records, 'B' );
213 $self->sort_del( $table_path, $table_info, \@old_records, 'B' ) if $table_info->{sort_block};
214
215 # A akışına ekle
216 $self->records_add( $table_path, $table_info, $tableid, \@rids, 'A' );
217 $self->match_add( $table_path, $table_info, \@new_records, 'A' );
218 $self->search_add( $table_path, $table_info, $tableid, \@new_records, 'A' );
219 $self->sort_add( $table_path, $table_info, \@new_records, 'A' ) if $table_info->{sort_block};
220
221 # Facet'e ekle (artık aktif)
222 $self->facet_add( $table_path, $table_info, \@new_records )
223 if $table_info->{use_facet};
224 }
225
226 # 3. Zaten Aktif Kalanlar
227 if (@stayed_active) {
228 $self->match_modify( $table_path, $table_info, \@stayed_active, 'A' );
229 $self->search_modify( $table_path, $table_info, $tableid, \@stayed_active, 'A' );
230 $self->sort_modify( $table_path, $table_info, \@stayed_active, 'A' ) if $table_info->{sort_block};
231
232 # Facet güncelle (değişen alanlar varsa)
233 $self->facet_modify( $table_path, $table_info, \@stayed_active )
234 if $table_info->{use_facet};
235 }
236
237 # 4. Zaten Junk Kalanlar
238 if (@stayed_junk) {
239 $self->match_modify( $table_path, $table_info, \@stayed_junk, 'B' );
240 $self->search_modify( $table_path, $table_info, $tableid, \@stayed_junk, 'B' );
241 $self->sort_modify( $table_path, $table_info, \@stayed_junk, 'B' ) if $table_info->{sort_block};
242 }
243
244 return 1;
245 }
246
247 =head1 NAME
248
249 AmberDB::Index::Junk - Schema-driven Tiered (Hot/Cold) Indexing and Lifecycle Management for AmberDB
250
251 =head1 SYNOPSIS
252
253 # In table schema definition (.table):
254 {
255 name => "Products",
256 record_index => 1,
257 use_junk => 1,
258 junk_rules => [
259 [ 20, "ne", 1 ], # Direct block rule (e.g. sales_status != 1)
260 [ "2->14", "ne", 1 ], # Relational RDBM rule (producer block 2 -> status block 14)
261 [ "6->0", "eq", "out_of_stock" ], # Nested array / composite rule
262 ],
263 jnktype => "AB", # Default table query tier mode (A, AB, B, BA)
264 search_block => [ 4, 5 ],
265 match_block => [ 1, 2, 3 ],
266 }
267
268 # Querying from AmberDB ($adb inherits AmberDB::Index::Junk):
269
270 # 1. Search with explicit tier mode:
271 my ($cnt, @recs) = $adb->search_table("catalog_product", "roman", offset => 0, limit => 20, jnktype => 'A');
272
273 # 2. Field filter with tier mode:
274 my $filter_res = $adb->field_filter("catalog_product", { filter => { 1 => 45 }, jnktype => 'AB' });
275
276 # 3. Read all records with tier mode:
277 my @active_ids = $adb->read_all("catalog_product", jnktype => 'A', keys_only => 1);
278 my @junk_ids = $adb->read_all("catalog_product", jnktype => 'B', keys_only => 1);
279 my @combined_ids = $adb->read_all("catalog_product", jnktype => 'AB', keys_only => 1);
280
281 =head1 DESCRIPTION
282
283 C<AmberDB::Index::Junk> provides a schema-driven, fully automated three-stream dual-tier indexing architecture:
284
285 =over 4
286
287 =item * B<Base Stream (All Records - no prefix):>
288
289 Contains ALL records (active and junk) in chronological/numerical sequence.
290 Keys: C<keys>, C<count>, C<$blk:$val>, C<$blk:$word>, C<$blk:keys>.
291 Queried when C<jnktype =E<gt> 'none'>, C<'ALL'>, or when C<use_junk> is not enabled.
292
293 =item * B<Hot / Active Tier (Tier A - C<A:> prefix):>
294
295 Contains high-priority, currently active, in-sale records.
296 Keys: C<A:keys>, C<A:count>, C<A:$blk:$val>, C<A:$blk:$word>, C<A:$blk:keys>.
297
298 =item * B<Cold / Junk Tier (Tier B - C<B:> prefix):>
299
300 Contains passive, expired, or out-of-sale records.
301 Keys: C<B:keys>, C<B:count>, C<B:$blk:$val>, C<B:$blk:$word>, C<B:$blk:keys>.
302
303 =back
304
305 This partitioning ensures high performance on storefront search, filtering, and indexing operations while keeping legacy and inactive catalog data searchable and accessible on demand without degrading active traffic.
306
307 =head1 SCHEMA CONFIGURATION
308
309 =head2 use_junk => 1
310
311 Enables dual-tier indexing on the table. If absent or set to 0, standard single-tier indexing is used.
312
313 =head2 junk_rules => [ [ $spec, $operator, $value ], ... ]
314
315 Defines the conditions under which a record is classified as Junk (Tier B). If any rule matches (logical OR), the record is routed to Tier B. If no rules match, the record is routed to Tier A.
316
317 =over 4
318
319 =item * B<Direct Block Index:> C<[ 20, "ne", 1 ]>
320
321 Evaluates block 20 of the current record.
322
323 =item * B<Relational RDBM Reference:> C<[ "2->14", "ne", 1 ]>
324
325 Looks up block 2's target table (via C<rdbm> schema configuration) and evaluates block 14 of the referenced record. For example, if a product is manufactured by a publisher whose status in C<catalog_producer> is passive, the product is automatically classified as Junk.
326
327 =item * B<Nested Array / Composite:> C<[ "6->0", "eq", "archived" ]>
328
329 Evaluates nested array elements or comma/tab separated fields within the record.
330
331 =back
332
333 =head1 QUERY MODES (jnktype)
334
335 The query tier mode is resolved with the following priority hierarchy:
336
337 1. Query Parameter: $opts->{jnktype} (e.g. in search_table, field_filter, field_fetch, read_all)
338 2. Table Schema: $table_info->{jnktype} or $table_info->{use_jnktype}
339 3. Instance Config: $adb->config('jnktype')
340 4. Global Default: 'AB'
341
342 =head2 Available Modes:
343
344 =over 4
345
346 =item * B<ALL / NONE:>
347
348 Bypasses junk partitioning and queries the Base stream directly (C<keys>, C<$blk:$val>, C<$blk:$word>, C<$blk:keys>). Guaranteed continuous numerical sequence with zero page-skip anomalies.
349
350 =item * B<A (Active Only):>
351
352 Queries only active indexes (C<A:keys>, C<A:$blk:$val>, C<A:$blk:$word>, C<A:$blk:keys>). Ideal for customer-facing category listings, checkout, stock verification, and order processing.
353
354 =item * B<AB (Active First, Junk Appended):>
355
356 Queries active indexes first, then appends results from junk indexes. Ideal for general storefront search where active products appear at the top, followed by out-of-print items.
357
358 =item * B<B (Junk Only):>
359
360 Queries only junk keys (C<B:keys>, C<B:$blk:$val>, C<B:$blk:$word>, C<B:$blk:keys>). Ideal for administrative archives, inventory reconciliation, and discontinued item reports.
361
362 =item * B<BA (Junk First, Active Appended):>
363
364 Queries junk indexes first, followed by active records.
365
366 =back
367
368 =head1 LIFECYCLE & AUTOMATIC STATE TRANSITIONS
369
370 During C<modify_id> and C<modify_list> calls, C<junk_transition> calculates state changes:
371
372 =over 4
373
374 =item * B<Active -E<gt> Junk:>
375
376 Record is removed from C<A:> tier indexes and added to C<B:> tier indexes. The Base stream (C<keys>) remains unaffected.
377
378 =item * B<Junk -E<gt> Active:>
379
380 Record is removed from C<B:> tier indexes and added to C<A:> tier indexes. The Base stream (C<keys>) remains unaffected.
381
382 =item * B<Unchanged:>
383
384 Record is modified in-place within its existing tier and updated in Base indexes.
385
386 =back
387
388 =head1 METHODS
389
390 =head2 junk_rules($table_info, @record)
391
392 Evaluates schema rules (C<junk_rules>) against a given record. Resolves direct fields, nested arrays, and relational foreign keys (RDBM) dynamically. Returns C<1> if the record satisfies any junk condition (Tier B), C<0> if active (Tier A).
393
394 my $is_junk = $adb->junk_rules($table_schema, @record_fields);
395
396 =head2 get_jnktype($table_info, \%opts)
397
398 Resolves the effective query mode (C<'ALL'>, C<'A'>, C<'AB'>, C<'B'>, C<'BA'>) using the 4-level priority hierarchy (query options -E<gt> table schema -E<gt> instance config -E<gt> default C<'AB'>).
399
400 my $mode = $adb->get_jnktype($table_schema, { jnktype => 'A' }); # "A"
401
402 =head2 junk_transition($table_path, $table_info, $tableid, \@pairs)
403
404 Calculates state changes between Active and Junk tiers during update operations, and coordinates atomic migration between C<A:> and C<B:> tier indexes via unified C<Index> methods.
405
406
407 =head1 AUTHOR
408
409 Maruf Cetin <marufcetin@gmail.com>
410
411 =head1 LICENSE AND COPYRIGHT
412
413 Copyright (C) 2012-2026 Maruf Cetin.
414
415 This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.
416
417 =cut
418
419 1;