Vali-Bucket 1.0.0

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package Vali-Bucket --version 1.0.0
                    


                    

                
NuGet\Install-Package Vali-Bucket -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Vali-Bucket" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Vali-Bucket" Version="1.0.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Vali-Bucket" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Vali-Bucket --version 1.0.0
                    


                    

                
#r "nuget: Vali-Bucket, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Vali-Bucket@1.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Vali-Bucket&version=1.0.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Vali-Bucket&version=1.0.0
                    


                            Install as a Cake Tool

Vali-Bucket

Groups timestamps into fixed-size, aligned time buckets for reporting and analytics.

Features

  • Bucketize — group raw timestamps into fixed-size buckets, counting how many fall in each
  • Aggregate<T> — group (timestamp, value) pairs into buckets, combining values per bucket with Sum/Average/Count/Min/Max
  • GetBucketFor — O(1) lookup of the bucket a single timestamp belongs to, without bucketizing a whole collection — useful in a streaming hot path
  • Alignment anchor — buckets from separate calls with the same size and anchor are always comparable, because bucket boundaries are computed from the anchor, not from the data
  • Reuses Vali-Range's DateRange for each bucket's time span
  • Compiled targets: net8.0 · net9.0 · net10.0 — compatible with .NET 6+ via NuGet backward compatibility

Installation

dotnet add package Vali-Bucket

Compatible with .NET 6, 7, 8, and 9. For new projects, .NET 8 (LTS) or .NET 9 is recommended.

Quick Start

using Vali_Bucket.Core;
using Vali_Bucket.Models;
using Vali_Time.Enums;

IValiBucket bucket = new ValiBucket();

var timestamps = new[]
{
    new DateTime(2025, 1, 1, 9, 2, 0),
    new DateTime(2025, 1, 1, 9, 7, 0),
    new DateTime(2025, 1, 1, 9, 16, 0),
};

var buckets = bucket.Bucketize(timestamps, new BucketSize(15, TimeUnit.Minutes));
// Two 15-minute buckets: [09:00-09:14:59.9999999] with Count=2, [09:15-09:29:59.9999999] with Count=1

Aggregating numeric values

var points = new[]
{
    (new DateTime(2025, 1, 1, 9, 2, 0), 100m),
    (new DateTime(2025, 1, 1, 9, 7, 0), 50m),
    (new DateTime(2025, 1, 1, 9, 16, 0), 30m),
};

var totals = bucket.Aggregate(points, new BucketSize(15, TimeUnit.Minutes), BucketAggregation.Sum);
// [09:00 bucket].Value == 150m, [09:15 bucket].Value == 30m

Single lookup

TimeBucket slot = bucket.GetBucketFor(DateTime.UtcNow, new BucketSize(1, TimeUnit.Hours));

API Reference

Member Signature
Bucketize IReadOnlyList<TimeBucket> Bucketize(IEnumerable<DateTime> timestamps, BucketSize size, DateTime? anchor = null)
Aggregate<T> IReadOnlyList<TimeBucket<T>> Aggregate<T>(IEnumerable<(DateTime, T)> points, BucketSize size, BucketAggregation aggregation, DateTime? anchor = null) where T : INumber<T>
GetBucketFor TimeBucket GetBucketFor(DateTime timestamp, BucketSize size, DateTime? anchor = null)

BucketSize(decimal Amount, TimeUnit Unit) only supports fixed-length units — Milliseconds, Seconds, Minutes, Hours, Days, Weeks. Months/Years have no constant tick length and throw ArgumentOutOfRangeException.

Buckets with zero matching timestamps/points are omitted from Bucketize/Aggregate results (no empty-bucket padding).

v1 Scope

  • No timezone/DST awareness — bucket boundaries are pure tick arithmetic over whatever DateTime.Kind the caller passes in. Convert to a consistent kind/zone before bucketizing if that matters for your data.
  • No windowed/rolling aggregation (sliding windows, overlapping buckets) — buckets are always disjoint and grid-aligned.

Dependency Injection

// Program.cs
using Vali_Bucket.Extensions;

builder.Services.AddValiBucket();

License

Licensed under the MIT License. Copyright © 2025 Felipe Rafael Montenegro Morriberon. All rights reserved.

Donations

If this package is useful to you, consider supporting its development:

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Vali-Bucket:

Package Downloads
Vali-Tempo

Vali-Tempo is the all-in-one meta-package for the Vali-Tempo ecosystem. Installing it gives you every module — Vali-Time, Vali-Range, Vali-Calendar, Vali-CountDown, Vali-Age, Vali-Holiday, Vali-TimeZone, Vali-Schedule, Vali-Duration, Vali-BusinessHours, and Vali-Bucket — with a single NuGet reference and a single DI registration call.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.0.0 128 10/14/2026

Vali-Bucket v1.0.0 — initial release: Bucketize, Aggregate<T>, GetBucketFor.