Add reset functionality to running numbers with configurable periods

- Introduced 'reset_period' and 'last_reset_at' fields in the RunningNumber model.
- Implemented logic to reset running numbers based on specified periods (never, daily, monthly, yearly).
- Updated Generator to handle reset conditions during number generation.
- Added tests to validate reset functionality and behavior under different reset periods.
- Created migration for adding reset functionality to the running_numbers table.

Author: nasrulhazim

config/running-number.php

@@ -1,6 +1,7 @@
 <?php
 
 use CleaniqueCoders\RunningNumber\Enums\Organization;
+use CleaniqueCoders\RunningNumber\Enums\ResetPeriod;
 
 return [
     /*
@@ -56,4 +57,32 @@
     */
 
     'padding' => 3,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Reset Period Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configure when running numbers should automatically reset. You can set
+    | a global default reset period, or configure specific periods per type.
+    |
+    | Available periods: 'never', 'daily', 'monthly', 'yearly'
+    | - never: Running numbers never reset (default)
+    | - daily: Reset at midnight every day
+    | - monthly: Reset on the 1st of each month
+    | - yearly: Reset on January 1st each year
+    |
+    */
+
+    'reset_period' => [
+        'default' => ResetPeriod::NEVER->value,
+
+        // Per-type reset periods (optional)
+        // Uncomment and configure specific types as needed
+        // 'types' => [
+        //     'invoice' => ResetPeriod::YEARLY->value,
+        //     'receipt' => ResetPeriod::MONTHLY->value,
+        //     'ticket' => ResetPeriod::DAILY->value,
+        // ],
+    ],
 ];

database/migrations/add_reset_functionality_to_running_numbers_table.php.stub

@@ -0,0 +1,23 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up()
+    {
+        Schema::table('running_numbers', function (Blueprint $table) {
+            $table->string('reset_period')->default('never')->after('type');
+            $table->timestamp('last_reset_at')->nullable()->after('reset_period');
+        });
+    }
+
+    public function down()
+    {
+        Schema::table('running_numbers', function (Blueprint $table) {
+            $table->dropColumn(['reset_period', 'last_reset_at']);
+        });
+    }
+};

src/Enums/ResetPeriod.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace CleaniqueCoders\RunningNumber\Enums;
+
+use CleaniqueCoders\Traitify\Concerns\InteractsWithEnum;
+
+enum ResetPeriod: string
+{
+    use InteractsWithEnum;
+
+    case NEVER = 'never';
+    case DAILY = 'daily';
+    case MONTHLY = 'monthly';
+    case YEARLY = 'yearly';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::NEVER => 'Never Reset',
+            self::DAILY => 'Daily Reset',
+            self::MONTHLY => 'Monthly Reset',
+            self::YEARLY => 'Yearly Reset',
+        };
+    }
+
+    public function description(): string
+    {
+        return match ($this) {
+            self::NEVER => 'Running number never resets',
+            self::DAILY => 'Running number resets every day at midnight',
+            self::MONTHLY => 'Running number resets on the first day of each month',
+            self::YEARLY => 'Running number resets on January 1st each year',
+        };
+    }
+
+    /**
+     * Check if reset is needed based on the period and last reset date
+     */
+    public function needsReset(?\DateTime $lastResetAt): bool
+    {
+        if ($lastResetAt === null) {
+            return false;
+        }
+
+        $now = new \DateTime();
+
+        return match ($this) {
+            self::NEVER => false,
+            self::DAILY => $lastResetAt->format('Y-m-d') !== $now->format('Y-m-d'),
+            self::MONTHLY => $lastResetAt->format('Y-m') !== $now->format('Y-m'),
+            self::YEARLY => $lastResetAt->format('Y') !== $now->format('Y'),
+        };
+    }
+}

src/Generator.php

@@ -63,6 +63,11 @@ public function generate(): string
                 ->lockForUpdate()
                 ->first();
 
+            // Check if reset is needed based on reset period
+            if ($running_number->needsReset()) {
+                $running_number->reset();
+            }
+
             // Increment and save atomically within the transaction
             $running_number->increment('number');
             $running_number->refresh();
@@ -80,9 +85,29 @@ private function createRunningNumberTypeIfNotExists()
     {
         // Use firstOrCreate() which is atomic and prevents race conditions
         // Multiple concurrent requests will not create duplicate types
+        $resetPeriod = $this->getResetPeriod();
+
         config('running-number.model')::firstOrCreate(
             ['type' => $this->getType()],
-            ['number' => 0]
+            [
+                'number' => 0,
+                'reset_period' => $resetPeriod,
+                'last_reset_at' => now(),
+            ]
         );
     }
+
+    private function getResetPeriod(): string
+    {
+        // Check if there's a specific reset period for this type
+        $typeResetPeriods = config('running-number.reset_period.types', []);
+        $type = strtolower($this->type);
+
+        if (isset($typeResetPeriods[$type])) {
+            return $typeResetPeriods[$type];
+        }
+
+        // Fall back to default reset period
+        return config('running-number.reset_period.default', 'never');
+    }
 }

src/Models/RunningNumber.php

@@ -2,12 +2,44 @@
 
 namespace CleaniqueCoders\RunningNumber\Models;
 
+use CleaniqueCoders\RunningNumber\Enums\ResetPeriod;
 use CleaniqueCoders\Traitify\Concerns\InteractsWithUuid;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * @property int $number
+ * @property string $type
+ * @property ResetPeriod $reset_period
+ * @property \Illuminate\Support\Carbon|null $last_reset_at
+ * @property \Illuminate\Support\Carbon $created_at
+ * @property \Illuminate\Support\Carbon $updated_at
+ */
 class RunningNumber extends Model
 {
     use InteractsWithUuid;
 
     protected $guarded = [];
+
+    protected $casts = [
+        'reset_period' => ResetPeriod::class,
+        'last_reset_at' => 'datetime',
+    ];
+
+    /**
+     * Check if this running number needs to be reset
+     */
+    public function needsReset(): bool
+    {
+        return $this->reset_period->needsReset($this->last_reset_at);
+    }
+
+    /**
+     * Reset the running number to zero
+     */
+    public function reset(): void
+    {
+        $this->number = 0;
+        $this->last_reset_at = now();
+        $this->save();
+    }
 }

src/RunningNumberServiceProvider.php

@@ -18,6 +18,7 @@ public function configurePackage(Package $package): void
             ->name('running-number')
             ->hasConfigFile('running-number')
             ->hasMigration('create_running_number_table')
-            ->hasMigration('add_uuid_to_running_numbers_table');
+            ->hasMigration('add_uuid_to_running_numbers_table')
+            ->hasMigration('add_reset_functionality_to_running_numbers_table');
     }
 }

tests/RunningNumberTest.php

@@ -10,6 +10,7 @@
 beforeEach(function () {
     include_once __DIR__.'/../database/migrations/create_running_number_table.php.stub';
     include_once __DIR__.'/../database/migrations/add_uuid_to_running_numbers_table.php.stub';
+    include_once __DIR__.'/../database/migrations/add_reset_functionality_to_running_numbers_table.php.stub';
 
     (new \CreateRunningNumberTable)->up();
 
@@ -24,6 +25,25 @@ public function up()
         }
     };
     $uuidMigration->up();
+
+    // Run the reset functionality migration
+    $resetMigration = new class extends \Illuminate\Database\Migrations\Migration
+    {
+        public function up()
+        {
+            Schema::table('running_numbers', function (\Illuminate\Database\Schema\Blueprint $table) {
+                $table->string('reset_period')->default('never')->after('type');
+                $table->timestamp('last_reset_at')->nullable()->after('reset_period');
+            });
+        }
+    };
+    $resetMigration->up();
+
+    // Add test-specific types to config
+    config(['running-number.types' => array_merge(
+        config('running-number.types'),
+        ['invoice', 'receipt', 'ticket', 'order', 'monthly']
+    )]);
 });
 
 it('can has running number helper', function () {
@@ -219,3 +239,148 @@ public function up()
     $record = config('running-number.model')::where('type', 'DIVISION')->first();
     expect($record->number)->toBe(3);
 });
+
+// Reset Functionality Tests
+it('creates running number with default reset period', function () {
+    RunningNumberGenerator::make()->type(Organization::UNIT->value)->generate();
+
+    $record = config('running-number.model')::where('type', 'UNIT')->first();
+
+    expect($record->reset_period->value)->toBe('never')
+        ->and($record->last_reset_at)->not->toBeNull();
+});
+
+it('can manually reset a running number', function () {
+    // Generate some numbers
+    for ($i = 0; $i < 5; $i++) {
+        RunningNumberGenerator::make()->type(Organization::SECTION->value)->generate();
+    }
+
+    $record = config('running-number.model')::where('type', 'SECTION')->first();
+    expect($record->number)->toBe(5);
+
+    // Manually reset
+    $record->reset();
+
+    expect($record->number)->toBe(0)
+        ->and($record->last_reset_at)->not->toBeNull();
+
+    // Next generation should be 1
+    $next = RunningNumberGenerator::make()->type(Organization::SECTION->value)->generate();
+    expect($next)->toBe('SECTION001');
+});
+
+it('does not reset when reset_period is never', function () {
+    // Generate numbers over time
+    RunningNumberGenerator::make()->type(Organization::ORGANIZATION->value)->generate();
+    RunningNumberGenerator::make()->type(Organization::ORGANIZATION->value)->generate();
+
+    $record = config('running-number.model')::where('type', 'ORGANIZATION')->first();
+
+    // Simulate time passing
+    $record->update(['last_reset_at' => now()->subYear()]);
+
+    // Should not reset since period is 'never'
+    RunningNumberGenerator::make()->type(Organization::ORGANIZATION->value)->generate();
+
+    $record->refresh();
+    expect($record->number)->toBe(3); // Should continue from 2 to 3
+});
+
+it('resets correctly with yearly period', function () {
+    $model = config('running-number.model');
+
+    // Create a record with yearly reset period
+    $record = $model::create([
+        'type' => 'INVOICE',
+        'number' => 100,
+        'reset_period' => 'yearly',
+        'last_reset_at' => now()->subYear(), // Last year
+    ]);
+
+    expect($record->needsReset())->toBeTrue();
+
+    // Generate - should reset to 1
+    $number = RunningNumberGenerator::make()->type('invoice')->generate();
+
+    expect($number)->toBe('INVOICE001');
+});
+
+it('resets correctly with monthly period', function () {
+    $model = config('running-number.model');
+
+    // Create a record with monthly reset period
+    $record = $model::create([
+        'type' => 'RECEIPT',
+        'number' => 50,
+        'reset_period' => 'monthly',
+        'last_reset_at' => now()->subMonth(), // Last month
+    ]);
+
+    expect($record->needsReset())->toBeTrue();
+
+    // Generate - should reset to 1
+    $number = RunningNumberGenerator::make()->type('receipt')->generate();
+
+    expect($number)->toBe('RECEIPT001');
+});
+
+it('resets correctly with daily period', function () {
+    $model = config('running-number.model');
+
+    // Create a record with daily reset period
+    $record = $model::create([
+        'type' => 'TICKET',
+        'number' => 25,
+        'reset_period' => 'daily',
+        'last_reset_at' => now()->subDay(), // Yesterday
+    ]);
+
+    expect($record->needsReset())->toBeTrue();
+
+    // Generate - should reset to 1
+    $number = RunningNumberGenerator::make()->type('ticket')->generate();
+
+    expect($number)->toBe('TICKET001');
+});
+
+it('does not reset if same period has not passed', function () {
+    $model = config('running-number.model');
+
+    // Create a record with daily reset, but last reset was today
+    $record = $model::create([
+        'type' => 'ORDER',
+        'number' => 10,
+        'reset_period' => 'daily',
+        'last_reset_at' => now(), // Today
+    ]);
+
+    expect($record->needsReset())->toBeFalse();
+
+    // Generate - should continue from 10
+    $number = RunningNumberGenerator::make()->type('order')->generate();
+
+    expect($number)->toBe('ORDER011');
+});
+
+it('updates last_reset_at when reset occurs', function () {
+    $model = config('running-number.model');
+
+    // Create record with monthly reset from last month
+    $record = $model::create([
+        'type' => 'MONTHLY',
+        'number' => 99,
+        'reset_period' => 'monthly',
+        'last_reset_at' => now()->subMonth(),
+    ]);
+
+    $originalResetDate = $record->last_reset_at;
+
+    // Generate - should trigger reset
+    RunningNumberGenerator::make()->type('monthly')->generate();
+
+    $record->refresh();
+
+    expect($record->number)->toBe(1)
+        ->and($record->last_reset_at->isAfter($originalResetDate))->toBeTrue();
+});