view release on metacpan or  search on metacpan

lib/DBIx/Class/Async/Storage/DBI/Cursor.pm  view on Meta::CPAN

package DBIx::Class::Async::Storage::DBI::Cursor;

$DBIx::Class::Async::Storage::DBI::Cursor::VERSION   = '0.65';
$DBIx::Class::Async::Storage::DBI::Cursor::AUTHORITY = 'cpan:MANWAR';

use strict;
use warnings;
use Future;

=head1 NAME

DBIx::Class::Async::Storage::DBI::Cursor - Asynchronous cursor for DBIx::Class ResultSets using Futures

=head1 VERSION

Version 0.65

=cut

=head1 SYNOPSIS

    # Typically obtained from the storage or resultset
    my $cursor = $rs->cursor;

    # Standard Async Iteration Pattern
    my $process_next;
    $process_next = sub {
        return $cursor->next->then(sub {
            my ($row_data) = @_;

            # If no data, we've reached the end of the ResultSet
            return Future->done unless $row_data;

            # Process the raw row data (hashref)
            say "Processing: " . $row_data->{email};

            # Recurse to fetch the next record
            return $process_next->();
        });
    };

    # Start the stream
    $process_next->()->on_fail(sub { warn "Streaming failed: @_" });

    # Reset the cursor to the beginning if needed
    $cursor->reset;

=head1 DESCRIPTION

This module implements an asynchronous cursor abstraction for
L<DBIx::Class> ResultSets backed by DBI storage.

It fetches rows from a ResultSet incrementally in fixed-size batches
(pages) and exposes a C<next> method that returns a L<Future>.
Each call to C<next> resolves to a single row object or C<undef>
when the result set has been exhausted.

The cursor maintains an internal buffer and transparently issues
paginated queries using the ResultSet's C<page> and C<rows>
attributes.

This class is primarily intended for use by asynchronous storage
layers or consumers that wish to process large result sets without
loading all rows into memory at once.

=cut

=head1 CONSTRUCTOR

=head2 new

  my $cursor = DBIx::Class::Async::Storage::DBI::Cursor->new(%args);

Creates a new asynchronous cursor.

B<Arguments>

=over 4

=item * C<storage>

The storage object associated with the ResultSet.
This value is currently stored but not actively used by the cursor.

=item * C<rs>

A L<DBIx::Class::ResultSet> to iterate over.
If the ResultSet has a C<rows> attribute set, it will be used
as the batch size for pagination.

=back

B<Batch Size>

The cursor fetches rows in batches. The batch size is determined as follows:

=over 4

=item * If the ResultSet has C<< $rs->{_attrs}{rows} >> defined, that value is used

=item * Otherwise, a default batch size of 20 rows is used

=back

=cut

sub new {
    my ($class, %args) = @_;

    my $rs         = $args{rs};
    my $batch_size = 20;         # default

    # Try to get rows attribute from ResultSet
    if ($rs && $rs->{_attrs} && defined $rs->{_attrs}{rows}) {
        $batch_size = $rs->{_attrs}{rows};
    }

    return bless {