replify

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 30, 2026 License: GPL-3.0 Imports: 26 Imported by: 0

README

replify

replify is a Go library designed to simplify and standardize API response wrapping for RESTful services. It leverages the Decorator Pattern to dynamically add error handling, metadata, pagination, and other response features in a clean and human-readable format.

Go Version License

Overview

Building RESTful APIs often requires repetitive boilerplate code for standardizing responses. replify eliminates this by providing a fluent, chainable API that ensures consistent response formats across all your endpoints.

What Problems Does It Solve?
  • ❌ Inconsistent response formats across different endpoints
  • ❌ Repetitive error handling boilerplate in every handler
  • ❌ Manual metadata management (request IDs, timestamps, versions)
  • ❌ Complex pagination logic scattered throughout the codebase
  • ❌ Debugging difficulties in production vs development environments
The Solution

✅ Standardized response structure - One format for all endpoints
✅ Fluent API - Chainable methods for building responses
✅ Built-in pagination - Complete pagination support out of the box
✅ Metadata management - Request IDs, timestamps, API versions, locales
✅ Conditional debugging - Development-only debug information
✅ Error handling - Stack traces, error wrapping, contextual messages
✅ Type safety - Full type safety with Go generics
✅ Zero dependencies - Only uses Go standard library

Features

Core Capabilities
  • 🎯 Standardized JSON Format - Consistent structure across all API responses
  • 🔗 Fluent Builder Pattern - Chain methods to construct complex responses
  • 📄 Pagination Support - Built-in page, per_page, total_items, total_pages, is_last
  • 🔍 Request Tracing - Track requests with unique IDs across microservices
  • 🌍 Internationalization - Locale support for multi-language APIs
  • 🐛 Debug Mode - Conditional debugging information for development
  • ⚡ Error Handling - Rich error information with stack traces
  • 📊 Metadata - API version, custom fields, timestamps
  • ✅ Status Helpers - IsSuccess(), IsClientError(), IsServerError()
  • 🔄 JSON Parsing - Parse JSON strings back to wrapper objects

Requirements

  • Go version 1.23 or higher

Installation

Install Package
# Latest version
go get -u github.com/sivaosorg/replify@latest

# Specific version
go get github.com/sivaosorg/[email protected]
Import in Code
import "github.com/sivaosorg/replify"

With Go's module support, go [build|run|test] automatically fetches the necessary dependencies when you add the import.

Quick Start

Basic Example
package main

import (
    "fmt"
    "github.com/sivaosorg/replify"
)

func main() {
    // Create a simple success response
    response := replify.New().
        WithStatusCode(200).
        WithMessage("User retrieved successfully").
        WithBody(map[string]string{
            "id":   "123",
            "name": "John Doe",
        })
    
    fmt.Println(response.JSONPretty())
}

Output:

{
    "data": {
        "id": "123",
        "name": "John Doe"
    },
    "headers": {
        "code": 200,
        "text": "OK"
    },
    "message": "User retrieved successfully",
    "meta": {
        "api_version": "v0.0.1",
        "locale": "en_US",
        "request_id": "d7e5ce24b796da94770911db36565bf9",
        "requested_time": "2026-01-29T10:07:05.751501+07:00"
    },
    "status_code": 200,
    "total": 0
}

Standard Response Format

The library produces responses in this standardized format:

{
  "status_code": 200,
  "message": "Resource retrieved successfully",
  "path": "/api/v1/users",
  "data": [ // abstract data (can be array or object)
    {
      "id": "user_01J6G7W9K2M4X7V5P8B3Q2Z1NS",
      "username": "jdoe_dev",
      "email": "[email protected]",
      "role": "administrator",
      "status": "active",
      "created_at": "2025-01-15T08:30:00Z",
      "last_login": "2026-02-26T14:15:22Z"
    },
    {
      "id": "user_01J6G7W9K2M4X7V5P8B3Q2Z1NT",
      "username": "s_smith",
      "email": "[email protected]",
      "role": "editor",
      "status": "active",
      "created_at": "2025-02-01T10:15:00Z",
      "last_login": "2026-02-25T09:45:10Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total_items": 120,
    "total_pages": 60,
    "is_last": false
  },
  "meta": {
    "request_id": "req_80eafc6a1655ec5a06595d155f1e6951",
    "api_version": "v1.0.4",
    "locale": "en_US",
    "requested_time": "2026-02-26T17:30:28.983Z",
    "custom_fields": { // custom fields
      "trace_id": "80eafc6a1655ec5a06595d155f1e6951",
      "origin_region": "us-east-1"
    }
  },
  "debug": { // custom fields
    "trace_session_id": "4919e84fc26881e9fe790f5d07465db4",
    "execution_time_ms": 42
  }
}
Field Descriptions
Field Type Description
data interface{} The primary data payload of the response
status_code int HTTP status code for the response
message string Human-readable message providing context
total int Total number of items (used in non-paginated responses)
path string Request path for which the response is generated
meta object Metadata about the API response
meta.request_id string Unique identifier for the request, useful for debugging
meta.api_version string API version used for the request
meta.locale string Locale used for the request (e.g., "en_US")
meta.requested_time string Timestamp when the request was made (ISO 8601)
meta.custom_fields object Additional custom metadata fields
pagination object Pagination details, if applicable
pagination.page int Current page number
pagination.per_page int Number of items per page
pagination.total_items int Total number of items available
pagination.total_pages int Total number of pages
pagination.is_last bool Indicates whether this is the last page
debug object Debugging information (useful for development)

Usage

1. Creating Basic Responses
Success Response
response := replify.New().
    WithStatusCode(200).
    WithMessage("Operation successful").
    WithBody(data)
Error Response
response := replify.New().
    WithStatusCode(400).
    WithError("Invalid input: email is required").
    WithMessage("Validation failed")
Response with Metadata
response := replify.New().
    WithStatusCode(200).
    WithBody(users).
    WithRequestID("req-123-456").
    WithApiVersion("v1.0.0").
    WithLocale("en_US").
    WithPath("/api/v1/users")
2. Pagination
Creating Pagination
pagination := replify.Pages().
    WithPage(1).
    WithPerPage(20).
    WithTotalItems(150).
    WithTotalPages(8).
    WithIsLast(false)

response := replify.New().
    WithStatusCode(200).
    WithBody(users).
    WithPagination(pagination).
    WithTotal(20)
3. Debugging Information
response := replify.New().
    WithStatusCode(500).
    WithError("Database connection failed").
    WithDebuggingKV("query", "SELECT * FROM users").
    WithDebuggingKV("error_code", "CONN_TIMEOUT").
    WithDebuggingKV("retry_count", 3)
4. Complete Example
package main

import (
    "fmt"
    "github.com/sivaosorg/replify"
    "github.com/sivaosorg/replify/pkg/randn"
)

func main() {
    // Create pagination
    p := replify.Pages().
        WithIsLast(true).
        WithPage(1000).
        WithTotalItems(120).
        WithTotalPages(34).
        WithPerPage(2)
    
    // Create response
    w := replify.New().
        WithStatusCode(200).
        WithTotal(1).
        WithMessagef("How are you? %v", "I'm good").
        WithDebuggingKV("refer", 1234).
        WithDebuggingKVf("___abc", "trace sessions_id: %v", randn.CryptoID()).
        WithBody("response body here").
        WithPath("/api/v1/users").
        WithCustomFieldKVf("fields", "userID: %v", 103).
        WithPagination(p)
    
    if !w.Available() {
        return
    }
    
    // Access response properties
    fmt.Println(w.JSON())
    fmt.Println(w.StatusCode())
    fmt.Println(w.StatusText())
    fmt.Println(w.Message())
    fmt.Println(w.Body())
    fmt.Println(w.IsSuccess())
    fmt.Println(w.Respond())
    
    // Check metadata
    fmt.Println(w.Meta().IsCustomPresent())
    fmt.Println(w.Meta().IsApiVersionPresent())
    fmt.Println(w.Meta().IsRequestIDPresent())
    fmt.Println(w.Meta().IsRequestedTimePresent())
}
5. Parsing JSON to Response
package main

import (
    "fmt"
    "log"
    "time"
    "github.com/sivaosorg/replify"
)

func main() {
    jsonStr := `{
        "data": "response body here",
        "debug": {
          "___abc": "trace sessions_id: 4919e84fc26881e9fe790f5d07465db4",
          "refer": 1234
        },
        "message": "How do you do? I'm good",
        "meta": {
          "api_version": "v0.0.1",
          "custom_fields": {
            "fields": "userID: 103"
          },
          "locale": "en_US",
          "request_id": "80eafc6a1655ec5a06595d155f1e6951",
          "requested_time": "2024-12-14T20:24:23.983839+07:00"
        },
        "pagination": {
          "is_last": true,
          "page": 1000,
          "per_page": 2,
          "total_items": 120,
          "total_pages": 34
        },
        "path": "/api/v1/users",
        "status_code": 200,
        "total": 1
    }`
    
    t := time.Now()
    w, err := replify.UnwrapJSON(jsonStr)
    diff := time.Since(t)
    
    if err != nil {
        log.Fatalf("Error parsing JSON: %v", err)
    }
    
    fmt.Printf("Exe time: %+v\n", diff.String())
    fmt.Printf("%+v\n", w.OnDebugging("___abc"))
    fmt.Printf("%+v\n", w.JSONPretty())
}

Practical Examples

Example 1: RESTful CRUD API
package main

import (
    "encoding/json"
    "net/http"
    "github.com/sivaosorg/replify"
)

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

// GET /users/:id
func GetUser(w http.ResponseWriter, r *http.Request) {
    id := getIDFromPath(r)
    user, err := findUserByID(id)
    
    var response *replify.R
    if err != nil {
        response = replify.New().
            WithStatusCode(404).
            WithError(err.Error()).
            WithMessage("User not found").
            WithRequestID(r.Header.Get("X-Request-ID"))
    } else {
        response = replify.New().
            WithStatusCode(200).
            WithBody(user).
            WithMessage("User retrieved successfully").
            WithRequestID(r.Header.Get("X-Request-ID"))
    }
    
    respondJSON(w, response)
}

// POST /users
func CreateUser(w http.ResponseWriter, r *http.Request) {
    var user User
    if err := json.NewDecoder(r.Body).Decode(&user); err != nil {
        response := replify.New().
            WithStatusCode(400).
            WithError(err.Error()).
            WithMessage("Invalid request body")
        respondJSON(w, response)
        return
    }
    
    if err := validateUser(user); err != nil {
        response := replify.New().
            WithStatusCode(422).
            WithError(err.Error()).
            WithMessage("Validation failed")
        respondJSON(w, response)
        return
    }
    
    createdUser, err := createUser(user)
    if err != nil {
        response := replify.New().
            WithStatusCode(500).
            WithErrorAck(err).
            WithMessage("Failed to create user")
        respondJSON(w, response)
        return
    }
    
    response := replify.New().
        WithStatusCode(201).
        WithBody(createdUser).
        WithMessage("User created successfully")
    respondJSON(w, response)
}

func respondJSON(w http.ResponseWriter, response *replify.R) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(response.StatusCode())
    w.Write([]byte(response.JSON()))
}
Example 2: Paginated List API
func ListUsers(w http.ResponseWriter, r *http.Request) {
    // Parse query parameters
    page := getQueryInt(r, "page", 1)
    perPage := getQueryInt(r, "per_page", 10)
    search := r.URL.Query().Get("search")
    
    // Fetch users with pagination
    users, total, err := db.FindUsers(search, page, perPage)
    if err != nil {
        response := replify.New().
            WithStatusCode(500).
            WithErrorAck(err).
            WithMessage("Failed to fetch users").
            WithDebuggingKV("search", search).
            WithDebuggingKV("page", page)
        respondJSON(w, response)
        return
    }
    
    // Calculate pagination metadata
    totalPages := (total + perPage - 1) / perPage
    isLast := page >= totalPages
    
    pagination := replify.Pages().
        WithPage(page).
        WithPerPage(perPage).
        WithTotalItems(total).
        WithTotalPages(totalPages).
        WithIsLast(isLast)
    
    response := replify.New().
        WithStatusCode(200).
        WithBody(users).
        WithPagination(pagination).
        WithTotal(len(users)).
        WithMessage("Users retrieved successfully").
        WithPath(r.URL.Path).
        WithRequestID(r.Header.Get("X-Request-ID"))
    
    respondJSON(w, response)
}
Example 3: Error Handling with Stack Traces
func ProcessOrder(w http.ResponseWriter, r *http.Request) {
    order, err := processOrderLogic(r)
    
    response := replify.New()
    
    if err != nil {
        response.
            WithStatusCode(500).
            WithErrorAck(err).
            WithMessage("Order processing failed")
        
        // Add debug info in development
        if os.Getenv("ENV") == "development" {
            response.
                WithDebuggingKV("timestamp", time.Now()).
                WithDebuggingKV("stack_trace", err.Error()).
                WithDebuggingKV("order_data", order)
        }
    } else {
        response.
            WithStatusCode(200).
            WithBody(order).
            WithMessage("Order processed successfully")
    }
    
    respondJSON(w, response)
}

API Reference

Wrapper Type (R)
type R struct {
    *wrapper
}

The R type is a high-level abstraction providing a simplified interface for handling API responses.

Core Functions
Function Description
New() *wrapper Creates a new response wrapper
Pages() *pagination Creates a new pagination object
UnwrapJSON(jsonStr string) (*wrapper, error) Parses JSON string to wrapper
Configuration Methods
Response Configuration
Method Description
WithStatusCode(code int) Sets HTTP status code
WithBody(v interface{}) Sets response body/data
WithMessage(message string) Sets response message
WithMessagef(format string, args...) Sets formatted message
WithError(message string) Sets error message
WithErrorf(format string, args...) Sets formatted error
WithErrorAck(err error) Sets error with stack trace
AppendError(err error, message string) Wraps error with context
AppendErrorf(err error, format string, args...) Wraps error with formatted context
WithPath(v string) Sets request path
WithPathf(v string, args...) Sets formatted request path
WithTotal(total int) Sets total items count
Metadata Methods
Method Description
WithRequestID(v string) Sets request ID
WithRequestIDf(format string, args...) Sets formatted request ID
WithApiVersion(v string) Sets API version
WithApiVersionf(format string, args...) Sets formatted API version
WithLocale(v string) Sets locale (e.g., "en_US")
WithRequestedTime(v time.Time) Sets request timestamp
WithCustomFieldKV(key string, value interface{}) Adds custom metadata field
WithCustomFieldKVf(key, format string, args...) Adds formatted custom field
WithCustomFields(values map[string]interface{}) Sets multiple custom fields
WithMeta(v *meta) Sets entire metadata object
WithHeader(v *header) Sets the header
Pagination Methods
Method Description
WithPagination(v *pagination) Sets pagination object
WithPage(v int) Sets current page number
WithPerPage(v int) Sets items per page
WithTotalItems(v int) Sets total items count
WithTotalPages(v int) Sets total pages count
WithIsLast(v bool) Sets if current page is last
Debugging Methods
Method Description
WithDebugging(v map[string]interface{}) Sets debug information map
WithDebuggingKV(key string, value interface{}) Adds single debug key-value
WithDebuggingKVf(key, format string, args...) Adds formatted debug value
Query Methods
Method Returns Description
Available() bool Checks if wrapper is non-nil
StatusCode() int Gets HTTP status code
StatusText() string Gets status text (e.g., "OK")
Body() interface{} Gets response body
Message() string Gets response message
Error() string Gets error message
Cause() error Gets underlying error cause
Total() int Gets total items
Meta() *meta Gets metadata object
Header() *header Gets header object
Pagination() *pagination Gets pagination object
Debugging() map[string]interface{} Gets debug information
OnDebugging(key string) interface{} Gets specific debug value
Conditional Check Methods
Method Returns Description
IsSuccess() bool Checks if status is 2xx
IsClientError() bool Checks if status is 4xx
IsServerError() bool Checks if status is 5xx
IsRedirection() bool Checks if status is 3xx
IsError() bool Checks if error exists or status is 4xx/5xx
IsErrorPresent() bool Checks if error field exists
IsBodyPresent() bool Checks if body exists
IsPagingPresent() bool Checks if pagination exists
IsMetaPresent() bool Checks if metadata exists
IsHeaderPresent() bool Checks if header exists
IsDebuggingPresent() bool Checks if debug info exists
IsDebuggingKeyPresent(key string) bool Checks if specific debug key exists
IsLastPage() bool Checks if current page is last
IsStatusCodePresent() bool Checks if valid status code exists
IsTotalPresent() bool Checks if total count exists
Serialization Methods
Method Returns Description
JSON() string Returns compact JSON string
JSONPretty() string Returns pretty-printed JSON
Respond() map[string]interface{} Returns map representation
Reply() R Returns R wrapper

HTTP Status Codes Reference

Common API Scenarios
Scenario HTTP Status Codes Example
Successful Resource Retrieval 200 OK, 304 Not Modified GET /users/123 - Returns user data
Resource Creation 201 Created POST /users - Creates a new user
Asynchronous Processing 202 Accepted POST /large-file - File upload starts
Validation Errors 400 Bad Request POST /users - Missing required field
Authentication Issues 401 Unauthorized, 403 Forbidden Invalid credentials or permissions
Rate Limiting 429 Too Many Requests Exceeded API request limits
Missing Resource 404 Not Found GET /users/999 - User not found
Server Failures 500 Internal Server Error, 503 Service Unavailable Database failure or maintenance
Version Conflicts 409 Conflict Outdated version causing conflict
Detailed Status Codes
Success (2xx)
Code Status Use Case
200 OK Successful GET, PUT, PATCH
201 Created Successful POST (resource created)
202 Accepted Async processing started
204 No Content Successful DELETE
206 Partial Content Video streaming, range requests
Redirection (3xx)
Code Status Use Case
301 Moved Permanently Resource permanently moved
302 Found Temporary redirect
304 Not Modified Cached content still valid
307 Temporary Redirect POST redirect maintaining method
308 Permanent Redirect Permanent redirect maintaining method
Client Errors (4xx)
Code Status Use Case
400 Bad Request Invalid request format/data
401 Unauthorized Missing/invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
409 Conflict Resource conflict (duplicate)
413 Payload Too Large Request body too large
415 Unsupported Media Type Invalid content type
422 Unprocessable Entity Validation errors
429 Too Many Requests Rate limiting
Server Errors (5xx)
Code Status Use Case
500 Internal Server Error Unexpected server error
501 Not Implemented Feature not implemented
502 Bad Gateway Upstream service error
503 Service Unavailable Service down/maintenance
504 Gateway Timeout Upstream timeout

Best Practices

✅ Do's

  1. Always set status codes

    response := replify.New().
    WithStatusCode(200).
    WithBody(data)

  2. Use request IDs for tracing

    response := replify.New().
    WithRequestID(r.Header.Get("X-Request-ID")).
    WithBody(data)

  3. Include API version

    response := replify.New().
    WithApiVersion("v1.0.0").
    WithBody(data)

  4. Use WithErrorAck for stack traces

    response := replify.New().
    WithStatusCode(500).
    WithErrorAck(err)

  5. Check response status before processing

    if response.IsSuccess() {
    processData(response.Body())
}

  6. Use pagination for list endpoints

    pagination := replify.Pages().
    WithPage(page).
    WithPerPage(perPage).
    WithTotalItems(total)
❌ Don'ts

  1. Don't forget to set status codes

    // ❌ Bad
response := replify.New().WithBody(data)

// ✅ Good
response := replify.New().WithStatusCode(200).WithBody(data)

  2. Don't expose sensitive debug info in production

    // ❌ Bad
response := replify.New().
    WithDebuggingKV("database_password", dbPass)

// ✅ Good
if os.Getenv("ENV") == "development" {
    response.WithDebuggingKV("query", sqlQuery)
}

  3. Don't use generic error messages

    // ❌ Bad
WithError("Error occurred")

// ✅ Good
WithError("Failed to create user: email already exists")

  4. Don't ignore error checking

    // ❌ Bad
wrapper, _ := replify.UnwrapJSON(jsonStr)

// ✅ Good
wrapper, err := replify.UnwrapJSON(jsonStr)
if err != nil {
    log.Printf("Failed to parse JSON: %v", err)
}

Use Cases

✅ When to Use
  • RESTful API Development - Standardizing API responses
  • Microservices - Consistent responses across services
  • API Versioning - Including version metadata
  • Error Standardization - Consistent error formats
  • Pagination - APIs returning paginated results
  • Multi-tenant APIs - Including tenant/locale information
  • Request Tracing - Tracking requests across services
  • Development Debugging - Conditional debug information
❌ When Not to Use
  • GraphQL APIs - GraphQL has its own response format
  • gRPC Services - Protocol Buffers define the structure
  • WebSocket APIs - Real-time bidirectional communication
  • Simple CLIs - Overkill for command-line tools
  • Internal Services - Where custom formats are required
  • High-Performance - Direct JSON encoding may be faster

fj Usage Guide

fj (Fast JSON) is the JSON path-extraction engine embedded in replify. It lets you read, query, and transform values from a JSON document without unmarshalling the entire structure into Go types. It lives in pkg/fj and is exposed through the wrapper type in parser.go.

Purpose in the replify Architecture

When a wrapper carries a JSON body, fj powers every field-level query on that body. Instead of decoding the whole payload into a map[string]any or a concrete struct, fj walks the raw string just far enough to locate the requested path. This keeps allocations low and throughput high on hot request paths.

HTTP Request → wrapper.WithBody(data) → wrapper.QueryJSONBody("user.name")
                                                 ↓
                                    fj.Get(jsonString, "user.name")
                                                 ↓
                                          fj.Context  ← single value, no full decode
When to Use fj Instead of encoding/json
Scenario Recommended approach
Extract one or a few fields from a large response body fj / QueryJSONBody
Validate that the body is well-formed JSON fj.IsValidJSON / ValidJSONBody
Search leaf values or keys across an unknown schema fj.Search / SearchJSONBody*
Apply streaming transforms (pretty-print, minify, etc.) fj transformers
Bind the full payload into a typed struct encoding/json or json-iterator
Write or modify JSON encoding/json
JSON schema validation a dedicated schema library
Path Syntax Quick Reference
user.name              field access
roles.0                array index
roles.#                array length
roles.#.name           collect field from every element
roles.#(role=="admin") first element where role == "admin"
roles.#(role=="admin")# all elements where role == "admin"
{id,name}              multi-selector → new object
[id,name]              multi-selector → new array
name.@uppercase        built-in transformer
name.@word:upper       transformer with argument
..title                recursive descent (JSON Lines / deep scan)

Dots and wildcards in key names can be escaped with a backslash (\).

Core API
Direct fj usage
import "github.com/sivaosorg/replify/pkg/fj"

json := `{
    "user": {"name": "Alice", "age": 30, "active": true},
    "roles": ["admin", "editor"],
    "scores": [95, 87, 92]
}`

// Single path
name := fj.Get(json, "user.name").String()    // "Alice"
age  := fj.Get(json, "user.age").Int64()      // 30
ok   := fj.Get(json, "user.active").Bool()    // true
n    := fj.Get(json, "roles.#").Int()         // 2 (array length)

// Multiple paths in one pass
results := fj.GetMulti(json, "user.name", "user.age", "roles.#")
// results[0].String() == "Alice", results[1].Int64() == 30, results[2].Int() == 2

// Check presence before use
if ctx := fj.Get(json, "user.email"); ctx.Exists() {
    fmt.Println(ctx.String())
}

// Parse a document once, query multiple times (avoids re-parsing)
doc := fj.Parse(json)
fmt.Println(doc.Get("user.name").String())
fmt.Println(doc.Get("roles.0").String())
Zero-copy byte-slice access

GetBytes is preferred when you already hold a []byte. It uses unsafe pointer operations internally to avoid an extra string allocation:

rawBytes := []byte(`{"id":42,"status":"active"}`)

id     := fj.GetBytes(rawBytes, "id").Int()        // 42
status := fj.GetBytes(rawBytes, "status").String() // "active"

// Multiple paths from bytes
res := fj.GetBytesMulti(rawBytes, "id", "status")

Memory note: fj.Context.Raw() returns a substring view of the original string without copying. Do not hold a reference to the Context after the source string has been released; the backing memory will be reclaimed.

Wrapper Integration (parser.go)

The wrapper type exposes all fj operations without requiring you to import pkg/fj directly in most cases:

	response := replify.New().
		WithStatusCode(200).
		WithBody(map[string]any{
			"user": map[string]any{"name": "Alice", "role": "admin"},
			"items": []map[string]any{
				{"id": 1, "price": 9.99},
				{"id": 2, "price": 4.50},
			},
		})

	// Single path query
	name := response.QueryJSONBody("user.name").String() // "Alice"

	// Multiple paths in one call (one JSON serialization)
	fields := response.QueryJSONBodyMulti("user.name", "user.role")
	fmt.Println(fields[0].String(), fields[1].String()) // Alice admin

	// Parse the body once and chain subsequent queries
	ctx := response.JSONBodyParser()
	fmt.Println(ctx.Get("user.name").String())
	fmt.Println(ctx.Get("items.#").Int()) // array length

	// Validate the body
	if !response.ValidJSONBody() {
		log.Println("body is not valid JSON")
		return
	}

	// Aggregate helpers
	total := response.SumJSONBody("items.#.price")  // 14.49
	min, _ := response.MinJSONBody("items.#.price") // 4.50
	max, _ := response.MaxJSONBody("items.#.price") // 9.99
	avg, _ := response.AvgJSONBody("items.#.price") // 7.245

	fmt.Println(name)
	fmt.Println(fields[0].String(), fields[1].String())
	fmt.Println(ctx.Get("user.name").String())
	fmt.Println(ctx.Get("items.#").Int())
	fmt.Println(total)
	fmt.Println(min)
	fmt.Println(max)
	fmt.Println(avg)

Performance tip: QueryJSONBody serializes the body on every call. For repeated queries on the same body, call JSONBodyParser() once and reuse the returned fj.Context.

Context Value Extraction

A fj.Context is returned by every query. Always call .Exists() before using the value if the path might be absent.

ctx := fj.Get(json, "optional.field")

ctx.Exists()   // false when path is missing
ctx.Kind()     // fj.Null | fj.String | fj.Number | fj.True | fj.False | fj.JSON
ctx.String()   // string representation
ctx.Bool()     // bool
ctx.Int()      // int
ctx.Int64()    // int64
ctx.Float64()  // float64
ctx.Raw()      // raw JSON token (no allocation)
ctx.IsArray()  // true when kind == JSON and raw starts with '['
ctx.IsObject() // true when kind == JSON and raw starts with '{'
ctx.IsError()  // true if parsing produced an error
ctx.Cause()    // error string, or "" if no error

// Iterate array values
ctx.Foreach(func(key, val fj.Context) bool {
    fmt.Println(val.String())
    return true // return false to stop
})
Transformers

Transformers are applied with the @ prefix inside a path expression and receive the current JSON value as input. An optional argument is passed after a : separator.

path.@transformerName
path.@transformerName:argument
path.@transformerName:{"key":"value"}
Core transformers
Transformer Alias(es) Input Description
@pretty — any Pretty-print (indented) JSON. Accepts optional {"sort_keys":true,"indent":"\t","prefix":"","width":80}.
@minify @ugly any Compact single-line JSON (all whitespace removed).
@valid — any Returns "true" / "false" — whether the input is valid JSON.
@this — any Identity — returns the input unchanged.
@reverse — array | object Reverses element order (array) or key order (object).
@flatten — array Shallow-flatten nested arrays. Pass {"deep":true} to recurse.
@join — array of objects Merge an array of objects into one object. Pass {"preserve":true} to keep duplicate keys.
@keys — object Return a JSON array of the object's keys.
@values — object Return a JSON array of the object's values.
@group — object of arrays Zip object-of-arrays into an array-of-objects.
@search — any @search:path — collect all values reachable at path anywhere in the tree.
@json — string Parse the string as JSON and return the value.
@string — any Encode the value as a JSON string literal.
String transformers
Transformer Alias(es) Description
@uppercase @upper Convert all characters to upper-case.
@lowercase @lower Convert all characters to lower-case.
@flip — Reverse the characters of the string.
@trim — Strip leading/trailing whitespace.
@snakecase @snake, @snakeCase Convert to snake_case.
@camelcase @camel, @camelCase Convert to camelCase.
@kebabcase @kebab, @kebabCase Convert to kebab-case.
@replace — @replace:{"target":"old","replacement":"new"} — replace first occurrence.
@replaceAll — @replaceAll:{"target":"old","replacement":"new"} — replace all occurrences.
@hex — Hex-encode the value.
@bin — Binary-encode the value.
@insertAt — @insertAt:{"index":5,"insert":"XYZ"} — insert a substring at position.
@wc — Return the word-count of a string as an integer.
@padLeft — @padLeft:{"padding":"*","length":10} — left-pad to a fixed width.
@padRight — @padRight:{"padding":"*","length":10} — right-pad to a fixed width.
Object transformers
Transformer Description
@project Pick and/or rename fields from an object. Arg: {"pick":["f1","f2"],"rename":{"f1":"newName"}}. Omit pick to keep all fields; omit rename for no renaming.
@default Inject fallback values for fields that are absent or null. Arg: {"field":"defaultValue",...}. Existing non-null fields are never overwritten.
Array transformers
Transformer Description
@filter Keep only elements matching a condition. Arg: {"key":"field","op":"eq","value":val}. Operators: eq (default), ne, gt, gte, lt, lte, contains.
@pluck Extract a named field (supports dot-notation paths) from every element. Arg: field path string, e.g. @pluck:name or @pluck:addr.city.
@first Return the first element of the array, or null if empty.
@last Return the last element of the array, or null if empty.
@count Return the number of elements (array) or key-value pairs (object) as an integer. Scalars return 0.
@sum Sum all numeric values in the array; non-numeric elements are skipped. Returns 0 for empty arrays.
@min Return the minimum numeric value in the array. Returns null when no numbers are present.
@max Return the maximum numeric value in the array. Returns null when no numbers are present.
Value normalization transformers
Transformer Description
@coerce Convert a scalar to a target type. Arg: {"to":"string"}, {"to":"number"}, or {"to":"bool"}. Objects and arrays are returned unchanged.
Examples
json := `{
    "user": {"name": "Alice", "role": null, "age": 30, "city": "NY"},
    "scores": [95, 87, 92, 78],
    "users": [
        {"name": "Alice", "active": true,  "addr": {"city": "NY"}},
        {"name": "Bob",   "active": false, "addr": {"city": "LA"}},
        {"name": "Carol", "active": true,  "addr": {"city": "NY"}}
    ]
}`

// ── Core ─────────────────────────────────────────────────────────────────────
fj.Get(json, "@pretty").String()             // indented JSON
fj.Get(json, "@minify").String()             // compact JSON
fj.Get(json, "user.@keys").String()          // ["name","role","age","city"]
fj.Get(json, "user.@values").String()        // ["Alice",null,30,"NY"]
fj.Get(json, "user.@valid").String()         // "true"

// ── String ───────────────────────────────────────────────────────────────────
fj.Get(json, "user.name.@uppercase").String()   // "ALICE"
fj.Get(json, "user.name.@reverse").String()     // "ecilA"
fj.Get(json, "user.name.@snakecase").String()   // "alice"
fj.Get(json, "user.city.@padLeft:{\"padding\":\"0\",\"length\":6}").String() // "000 NY"

// ── Object ───────────────────────────────────────────────────────────────────

// Project: keep only name and age, rename age → years
fj.Get(json, `user.@project:{"pick":["name","age"],"rename":{"age":"years"}}`).Raw()
// → {"name":"Alice","years":30}

// Default: fill in missing / null fields
fj.Get(json, `user.@default:{"role":"viewer","active":true}`).Raw()
// → {"name":"Alice","role":"viewer","age":30,"city":"NY","active":true}

// ── Array ────────────────────────────────────────────────────────────────────

// Filter: keep only active users
fj.Get(json, `users.@filter:{"key":"active","value":true}`).Raw()
// → [{"name":"Alice","active":true,...},{"name":"Carol","active":true,...}]

// Pluck: extract the city from every user's address
fj.Get(json, `users.@pluck:addr.city`).Raw()
// → ["NY","LA","NY"]

// Aggregation helpers
fj.Get(json, "scores.@first").Raw()    // 95
fj.Get(json, "scores.@last").Raw()     // 78
fj.Get(json, "scores.@count").Raw()    // 4
fj.Get(json, "scores.@sum").Raw()      // 352
fj.Get(json, "scores.@min").Raw()      // 78
fj.Get(json, "scores.@max").Raw()      // 95

// ── Coerce ───────────────────────────────────────────────────────────────────
fj.Get(`42`,   `@coerce:{"to":"string"}`).Raw()  // "42"
fj.Get(`"99"`, `@coerce:{"to":"number"}`).Raw()  // 99
fj.Get(`1`,    `@coerce:{"to":"bool"}`).Raw()    // true
Composing transformers

Transformers can be chained using the | pipe operator or dot notation:

// First filter the array, then count the remaining elements
fj.Get(json, `users.@filter:{"key":"active","value":true}|@count`).Raw()
// → 2

// Pluck names, then reverse the resulting array
fj.Get(json, `users.@pluck:name|@reverse`).Raw()
// → ["Carol","Bob","Alice"]
Complex real-world examples

The following scenarios demonstrate how to combine multiple transformers into a single expression to process realistic JSON payloads.

Example 1 — E-commerce product catalog: filter, aggregate, and shape

catalog := `{
    "products": [
        {"id":"p1","name":"Laptop Pro",    "category":"electronics","price":1299.99,"stock":5},
        {"id":"p2","name":"USB-C Hub",     "category":"electronics","price":49.99,  "stock":120},
        {"id":"p3","name":"Desk Chair",    "category":"furniture",  "price":349.00, "stock":0},
        {"id":"p4","name":"Standing Desk", "category":"furniture",  "price":699.00, "stock":3},
        {"id":"p5","name":"Webcam HD",     "category":"electronics","price":89.99,  "stock":45}
    ]
}`

// All in-stock electronics names
fj.Get(catalog, `products.@filter:{"key":"category","value":"electronics"}|@filter:{"key":"stock","op":"gt","value":0}|@pluck:name`).Raw()
// → ["Laptop Pro","USB-C Hub","Webcam HD"]

// Count of in-stock products
fj.Get(catalog, `products.@filter:{"key":"stock","op":"gt","value":0}|@count`).Raw()
// → 4

// Price range of in-stock products
fj.Get(catalog, `products.@filter:{"key":"stock","op":"gt","value":0}|@pluck:price|@min`).Raw()
// → 49.99
fj.Get(catalog, `products.@filter:{"key":"stock","op":"gt","value":0}|@pluck:price|@max`).Raw()
// → 1299.99

// Project the first in-stock product as a display card (pick and rename fields)
first := fj.Get(catalog, `products.@filter:{"key":"stock","op":"gt","value":0}|@first`).Raw()
fj.Get(first, `@project:{"pick":["name","price"],"rename":{"name":"title","price":"cost"}}`).Raw()
// → {"title":"Laptop Pro","cost":1299.99}

Example 2 — API response normalization: fill defaults then project and rename

// Raw user record from an external API with null / absent fields
rawUser := `{"id":"u1","name":"Alice","role":null,"verified":null}`

// One-shot normalization: fill nulls → keep only safe fields → rename id for the frontend
fj.Get(rawUser, `@default:{"role":"viewer","verified":false}|@project:{"pick":["id","name","role","verified"],"rename":{"id":"userId"}}`).Raw()
// → {"userId":"u1","name":"Alice","role":"viewer","verified":false}

Example 3 — Log processing: filter, count, and retrieve the latest entry

logs := `[
    {"level":"error","msg":"Connection refused","ts":1700001},
    {"level":"info", "msg":"Server started",    "ts":1700002},
    {"level":"error","msg":"Timeout exceeded",  "ts":1700003},
    {"level":"warn", "msg":"High memory",       "ts":1700004}
]`

// How many errors?
fj.Get(logs, `@filter:{"key":"level","value":"error"}|@count`).Raw()
// → 2

// All error messages
fj.Get(logs, `@filter:{"key":"level","value":"error"}|@pluck:msg`).Raw()
// → ["Connection refused","Timeout exceeded"]

// Most recent error entry (last in the filtered array)
fj.Get(logs, `@filter:{"key":"level","value":"error"}|@last`).Raw()
// → {"level":"error","msg":"Timeout exceeded","ts":1700003}

Example 4 — Nested data aggregation: filter → pluck → flatten → sum

teamData := `{
    "teams": [
        {"name":"Alpha","active":true, "monthly_revenue":[10000,12000,11000]},
        {"name":"Beta", "active":false,"monthly_revenue":[8000,9000,8500]},
        {"name":"Gamma","active":true, "monthly_revenue":[15000,16000,14000]}
    ]
}`

// Total revenue across all active teams, flattening the per-team monthly arrays first
fj.Get(teamData, `teams.@filter:{"key":"active","value":true}|@pluck:monthly_revenue|@flatten|@sum`).Raw()
// → 78000   (Alpha: 33000 + Gamma: 45000)

Example 5 — URL-slug generation from a display name

// Multi-word title with duplicate internal spaces → URL-safe kebab-case slug
fj.Get(`"My   Blog Post Title"`, `@trim|@lowercase|@kebabcase`).Raw()
// → "my-blog-post-title"

// Author name to lowercase slug
fj.Get(`"John Doe"`, `@lowercase|@replace:{"target":" ","replacement":"-"}`).Raw()
// → "john-doe"

Example 6 — Config merging and introspection

// Merge two partial config objects; later values overwrite earlier ones for duplicate keys
overrides := `[{"host":"localhost","port":5432},{"port":5433,"ssl":true}]`

merged := fj.Get(overrides, `@join`).Raw()
// → {"host":"localhost","port":5433,"ssl":true}

// Inspect which keys are present after the merge
fj.Get(merged, `@keys`).Raw()
// → ["host","port","ssl"]

// Count the merged keys
fj.Get(merged, `@count`).Raw()
// → 3

// Project only the connection-relevant subset and rename for the driver
fj.Get(merged, `@project:{"pick":["host","port"],"rename":{"port":"dbPort"}}`).Raw()
// → {"host":"localhost","dbPort":5433}

Example 7 — Leaderboard: zip parallel arrays, filter, and pluck

// Two parallel arrays zipped via @group into an array-of-objects, then filtered and plucked
leaderboard := `{"player":["Alice","Bob","Carol","Dave"],"score":[98,72,85,91]}`

// Zip the parallel arrays into objects
grouped := fj.Get(leaderboard, `@group`).Raw()
// → [{"player":"Alice","score":98},{"player":"Bob","score":72},
//    {"player":"Carol","score":85},{"player":"Dave","score":91}]

// Players with a score of 85 or above
fj.Get(grouped, `@filter:{"key":"score","op":"gte","value":85}|@pluck:player`).Raw()
// → ["Alice","Carol","Dave"]

// Top player's full record
fj.Get(grouped, `@filter:{"key":"score","op":"gte","value":95}|@first`).Raw()
// → {"player":"Alice","score":98}
Registering custom transformers
func init() {
    fj.AddTransformer("redact", fj.TransformerFunc(func(json, arg string) string {
        return `"[REDACTED]"`
    }))
}

// Usage in path
fj.Get(json, "user.password.@redact").String() // "[REDACTED]"

Transformers can be disabled globally with fj.DisableTransformers = true.

Search and Scan Helpers
// Full-tree substring search across all leaf values
hits := response.SearchJSONBody("admin")

// Wildcard scan of leaf values
hits = response.SearchJSONBodyMatch("err*")

// Find all values stored under specific key names
emails := response.SearchJSONBodyByKey("email")

// Find all values under keys matching a wildcard
hits = response.SearchJSONBodyByKeyPattern("user*")

// Substring / wildcard check at a specific path
response.JSONBodyContains("user.role", "admin")
response.JSONBodyContainsMatch("user.email", "*@example.com")

// Return the dot-notation path where a value first appears
path := response.FindJSONBodyPath("[email protected]")

// All paths where value matches a pattern
paths := response.FindJSONBodyPathsMatch("err*")
Data Manipulation Helpers
import "github.com/sivaosorg/replify/pkg/fj"

// Count elements at a path
n := response.CountJSONBody("items")

// Filter array elements by predicate
active := response.FilterJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("active").Bool()
})

// First match
admin := response.FirstJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("role").String() == "admin"
})

// Deduplicate (first-occurrence order preserved)
tags := response.DistinctJSONBody("tags")

// Project fields from an array of objects
rows := response.PluckJSONBody("users", "id", "email")

// Group by a key field
byRole := response.GroupByJSONBody("users", "role")

// Sort array by a field (numeric or string comparison)
sorted := response.SortJSONBody("products", "price", true)
Limitations
  • Read-only: fj cannot write or modify JSON. Use encoding/json for serialization.
  • No schema validation: For strict schema enforcement use a dedicated library.
  • No struct binding: fj returns Context values, not typed Go structs. Use encoding/json when binding is required.
  • Raw() lifetime: The raw string returned by Context.Raw() is a zero-copy view into the source JSON string. It must not outlive the original string.
  • UnsafeBytes: The byte slice returned by fj.UnsafeBytes shares memory with the source string. Never mutate it, as this violates Go's string immutability guarantees and can cause undefined behavior.
  • Malformed input: fj does not validate JSON before parsing. Pass untrusted input through fj.IsValidJSON or ValidJSONBody() first.
  • Transformers are global: AddTransformer writes to a package-level registry. Register all transformers during program initialization (e.g., in init() functions) before concurrent access begins to avoid data races.
Best Practices

  1. Check existence before use

    if ctx := response.QueryJSONBody("optional.key"); ctx.Exists() {
    process(ctx.String())
}

  2. Parse once, query many times

    doc := response.JSONBodyParser()
id    := doc.Get("user.id").String()
email := doc.Get("user.email").String()
role  := doc.Get("user.role").String()

  3. Prefer GetBytes for byte-slice payloads

    // ✅ avoids string conversion allocation
ctx := fj.GetBytes(rawBytes, "user.name")

// ❌ unnecessary allocation
ctx = fj.Get(string(rawBytes), "user.name")

  4. Validate untrusted input first

    if !response.ValidJSONBody() {
    return errors.New("invalid JSON body")
}

  5. Register custom transformers in init()

    func init() {
    fj.AddTransformer("mask", func(json, arg string) string {
        return `"***"`
    })
}

  6. Never mutate UnsafeBytes output

    b := fj.UnsafeBytes(someString)
// ✅ read-only access
_ = b[0]
// ❌ mutating b corrupts the original string

Contributing

To contribute to this project, follow these steps:

  1. Clone the repository

    git clone --depth 1 https://github.com/sivaosorg/replify.git

  2. Navigate to the project directory

    cd replify

  3. Prepare the project environment

    go mod tidy

  4. Make your changes

    • Follow Go best practices
    • Add tests for new features
    • Update documentation

  5. Run tests

    go test ./...

  6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Part of the replify ecosystem:

  • replify - API response wrapping library (this package)
  • conv - Type conversion utilities
  • coll - Type-safe collection utilities
  • common - Reflection-based utilities
  • encoding - JSON encoding utilities
  • hashy - Deterministic hashing
  • match - Wildcard pattern matching
  • msort - Map sorting utilities
  • randn - Random data generation
  • ref - Pointer utilities
  • strutil - String utilities
  • truncate - String truncation utilities

Support

Acknowledgments

Built with ❤️ for the Go community.

Documentation

Overview

Package replify provides a structured, high-level toolkit for building and consuming HTTP API responses in Go. It ships with:

  • A fluent [wrapper] / R type for constructing and inspecting API responses
  • First-class JSON parsing, normalisation, and field-level access
  • Pre-built response helpers for every standard HTTP status code
  • Pagination, metadata, and header sub-structures
  • Chunked / buffered / direct data streaming with progress tracking and compression
  • Stack-aware error wrapping compatible with the standard errors package
  • A rich constants catalogue (HTTP headers, media types, locales)

Installation 

go get github.com/sivaosorg/replify

Getting Started

The quickest way to create a successful response: 

w := replify.WrapOk("Users retrieved", users)
json.NewEncoder(rw).Encode(w.JSON())

Response Construction

Use New plus the fluent With* methods to build fully-featured responses: 

w := replify.New().
    WithStatusCode(http.StatusOK).
    WithMessage("Resource retrieved").
    WithBody(payload).
    WithPagination(replify.FromPages(120, 10).WithPage(1)).
    WithMeta(replify.Meta().
        WithApiVersion("v1.0.0").
        WithLocale("en_US").
        WithRequestID("req_abc123"),
    ).
    WithHeader(replify.OK)

Render the result: 

fmt.Println(w.JSON())         // compact JSON string
fmt.Println(w.JSONPretty())   // indented JSON string
fmt.Println(w.StatusCode())   // 200
fmt.Println(w.Message())      // "Resource retrieved"

Pre-built HTTP Status Helpers

Every standard HTTP status has a dedicated constructor that sets the correct status code and header automatically: 

replify.WrapOk("OK", data)                     // 200
replify.WrapCreated("Created", data)           // 201
replify.WrapAccepted("Accepted", data)         // 202
replify.WrapNoContent("No Content", nil)       // 204
replify.WrapBadRequest("Bad Request", nil)     // 400
replify.WrapUnauthorized("Unauthorized", nil)  // 401
replify.WrapForbidden("Forbidden", nil)        // 403
replify.WrapNotFound("Not Found", nil)         // 404
replify.WrapConflict("Conflict", nil)          // 409
replify.WrapUnprocessableEntity("Invalid", errs) // 422
replify.WrapTooManyRequest("Rate limited", nil)  // 429
replify.WrapInternalServerError("Error", nil)    // 500
replify.WrapServiceUnavailable("Down", nil)      // 503
replify.WrapGatewayTimeout("Timeout", nil)       // 504

Parsing a JSON API Response

UnwrapJSON normalises (strips comments, trailing commas) and parses a raw JSON string into a [wrapper], giving typed access to every standard field: 

jsonStr := `{
    "status_code": 200,
    "message":     "OK",
    "path":        "/api/v1/users",
    "data": [
        {"id": "u1", "username": "alice"},
        {"id": "u2", "username": "bob"}
    ],
    "pagination": {
        "page": 1, "per_page": 2,
        "total_items": 100, "total_pages": 50,
        "is_last": false
    },
    "meta": {
        "request_id":     "req_abc",
        "api_version":    "v1.0.0",
        "locale":         "en_US",
        "requested_time": "2026-03-09T07:00:00Z"
    }
}`

w, err := replify.UnwrapJSON(jsonStr)
if err != nil {
    log.Fatal(err)
}
fmt.Println(w.StatusCode())                                        // 200
fmt.Println(w.Pagination().TotalItems())                           // 100
fmt.Println(w.JSONBodyParser().Get("0").Get("username").String())  // "alice"

For map-based input use WrapFrom: 

m := map[string]any{
    "status_code": 201,
    "message":     "Created",
    "data":        map[string]any{"id": "new_001"},
}
w, err := replify.WrapFrom(m)

Pagination

Create and attach pagination using Pages or the convenience constructor FromPages: 

p := replify.FromPages(500, 20). // 500 total items, 20 per page
    WithPage(3)

w := replify.WrapOk("Users", users).WithPagination(p)
fmt.Println(w.Pagination().TotalPages()) // 25
fmt.Println(w.Pagination().IsLast())     // false

Metadata

Attach API metadata to any response: 

m := replify.Meta().
    WithApiVersion("v2.1.0").
    WithLocale("vi_VN").
    WithRequestID("req_xyz").
    WithCustomField("trace_id", "abc123").
    WithCustomField("region",   "us-east-1")

w := replify.WrapOk("OK", data).WithMeta(m)
fmt.Println(w.Meta().ApiVersion())  // "v2.1.0"

HTTP Headers and Status Codes

Pre-built header singletons cover all standard HTTP/1.1 and WebDAV codes: 

replify.OK                    // 200 Successful
replify.Created               // 201 Successful
replify.NotFound              // 404 Client Error
replify.InternalServerError   // 500 Server Error
replify.TooManyRequests       // 429 Client Error

Inspect a pre-built header: 

h := replify.NotFound
fmt.Println(h.Code())        // 404
fmt.Println(h.Text())        // "Not Found"
fmt.Println(h.Type())        // "Client Error"

Build a custom header with the fluent API: 

h := replify.Header().
    WithCode(422).
    WithText("Validation Error").
    WithType("Client Error").
    WithDescription("One or more fields failed validation.")

HTTP Header Name Constants

All standard HTTP header names are available as typed constants: 

replify.HeaderAuthorization   // "Authorization"
replify.HeaderContentType     // "Content-Type"
replify.HeaderAccept          // "Accept"
replify.HeaderCacheControl    // "Cache-Control"
replify.HeaderXRequestedWith  // "X-Requested-With"

Media Type Constants

Common MIME types are available as constants: 

replify.MediaTypeApplicationJSON     // "application/json"
replify.MediaTypeApplicationJSONUTF8 // "application/json; charset=utf-8"
replify.MediaTypeTextPlain           // "text/plain"
replify.MediaTypeMultipartFormData   // "multipart/form-data"

Locale Constants

IETF-style locale identifiers for content localisation: 

replify.LocaleEnUS  // "en_US"
replify.LocaleViVN  // "vi_VN"
replify.LocaleZhCN  // "zh_CN"
replify.LocaleJaJP  // "ja_JP"

Streaming

NewStreaming creates a StreamingWrapper that streams data from any io.Reader with configurable chunking, compression, progress hooks, and context-aware cancellation: 

cfg := replify.NewStreamConfig()
cfg.Strategy    = replify.StrategyChunked
cfg.Compression = replify.CompressGzip
cfg.ChunkSize   = 128 * 1024 // 128 KB

sw := replify.NewStreaming(reader, cfg)
sw.WithStreamingCallback(func(p *replify.StreamProgress, err error) {
    fmt.Printf("%.0f%%  %d B/s\n", float64(p.Percentage), p.TransferRate)
})

if err := sw.Stream(writer); err != nil {
    log.Fatal(err)
}
fmt.Println(sw.Stats().CompressionRatio) // e.g. 0.12 (88% reduction)

Streaming strategies: 

replify.StrategyDirect    // write bytes immediately as they arrive
replify.StrategyBuffered  // collect in an internal buffer (default)
replify.StrategyChunked   // split into fixed-size chunks

Supported compression algorithms: 

replify.CompressNone     // no compression (default)
replify.CompressGzip     // gzip
replify.CompressDeflate  // deflate
replify.CompressFlate    // flate

Error Handling

replify provides stack-trace-aware error construction compatible with the standard errors package: 

// Create a new error with a stack trace.
err := replify.NewError("something went wrong")

// Format an error with printf-style args.
err = replify.NewErrorf("user %q not found", userID)

// Wrap an existing error, preserving its message and adding a stack trace.
err = replify.NewErrorAck(originalErr)

// Inspect the stack trace.
var st replify.StackTrace
if errors.As(err, &st) {
    fmt.Printf("%+v\n", st)
}

R — High-Level Wrapper Alias

R is a thin alias over [wrapper]. It is returned by streaming hooks and can be used wherever a [wrapper] is accepted: 

sw.WithStreamingHook(func(p *replify.StreamProgress, r *replify.R) {
    fmt.Println(r.StatusCode(), p.Percentage)
})

Buffer Pool

NewBufferPool provides a reusable byte-buffer pool to reduce GC pressure during high-throughput streaming: 

pool := replify.NewBufferPool(64*1024, 8) // 8 × 64 KB buffers
cfg  := replify.NewStreamConfig()
cfg.UseBufferPool = true

Toolbox

The package also exposes a Toolbox variable for utility operations that do not fit the fluent response API: 

replify.Toolbox // tools{}

Index

Constants

View Source 
const (
	// Accept specifies the media types that are acceptable for the response.
	// 	Example: "application/json, text/html"
	HeaderAccept = "Accept"

	// AcceptCharset specifies the character sets that are acceptable.
	// 	Example: "utf-8, iso-8859-1"
	HeaderAcceptCharset = "Accept-Charset"

	// AcceptEncoding specifies the content encodings that are acceptable.
	//	Example: "gzip, deflate, br"
	HeaderAcceptEncoding = "Accept-Encoding"

	// AcceptLanguage specifies the acceptable languages for the response.
	// 	Example: "en-US, en;q=0.9, fr;q=0.8"
	HeaderAcceptLanguage = "Accept-Language"

	// Authorization contains the credentials for authenticating the client with the server.
	// 	Example: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6..."
	HeaderAuthorization = "Authorization"

	// CacheControl specifies directives for caching mechanisms in both requests and responses.
	// 	Example: "no-cache, no-store, must-revalidate"
	HeaderCacheControl = "Cache-Control"

	// ContentDisposition specifies if the content should be displayed inline or treated as an attachment.
	// 	Example: "attachment; filename=\"document.pdf\""
	HeaderContentDisposition = "Content-Disposition"

	// ContentEncoding specifies the encoding transformations that have been applied to the body of the response.
	// 	Example: "gzip"
	HeaderContentEncoding = "Content-Encoding"

	// ContentLength specifies the size of the response body in octets.
	// 	Example: "1024"
	HeaderContentLength = "Content-Length"

	// ContentType specifies the media type of the resource.
	// 	Example: "application/json; charset=utf-8"
	HeaderContentType = "Content-Type"

	// Cookie contains stored HTTP cookies sent to the server by the client.
	// 	Example: "sessionId=abc123; userId=456"
	HeaderCookie = "Cookie"

	// Host specifies the domain name of the server (for virtual hosting) and the TCP port number.
	// 	Example: "www.example.com:8080"
	HeaderHost = "Host"

	// Origin specifies the origin of the cross-origin request or preflight request.
	// 	Example: "https://www.example.com"
	HeaderOrigin = "Origin"

	// Referer contains the address of the previous web page from which a link to the currently requested page was followed.
	// 	Example: "https://www.example.com/page1.html"
	HeaderReferer = "Referer"

	// UserAgent contains information about the user agent (browser or client) making the request.
	// 	Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
	HeaderUserAgent = "User-Agent"

	// IfMatch makes the request conditional on the target resource having the same entity tag as the one provided.
	// 	Example: "\"686897696a7c876b7e\""
	HeaderIfMatch = "If-Match"

	// IfNoneMatch makes the request conditional on the target resource not having the same entity tag as the one provided.
	// 	Example: "\"686897696a7c876b7e\""
	HeaderIfNoneMatch = "If-None-Match"

	// ETag provides the entity tag for the resource.
	// 	Example: "\"33a64df551425fcc55e4d42a148795d9f25f89d4\""
	HeaderETag = "ETag"

	// LastModified specifies the last modified date of the resource.
	// 	Example: "Wed, 21 Oct 2015 07:28:00 GMT"
	HeaderLastModified = "Last-Modified"

	// Location specifies the URL to redirect a client to.
	// 	Example: "https://www.example.com/new-location"
	HeaderLocation = "Location"

	// Pragma specifies implementation-specific directives that might affect caching.
	// 	Example: "no-cache"
	HeaderPragma = "Pragma"

	// RetryAfter specifies the time after which the client should retry the request after receiving a 503 Service Unavailable status code.
	// 	Example: "120" or "Fri, 07 Nov 2014 23:59:59 GMT"
	HeaderRetryAfter = "Retry-After"

	// Server contains information about the software used by the origin server to handle the request.
	// 	Example: "Apache/2.4.41 (Ubuntu)"
	HeaderServer = "Server"

	// WWWAuthenticate indicates that the client must authenticate to access the requested resource.
	// 	Example: "Basic realm=\"Access to staging site\""
	HeaderWWWAuthenticate = "WWW-Authenticate"

	// Date specifies the date and time at which the message was sent.
	// 	Example: "Tue, 15 Nov 1994 08:12:31 GMT"
	HeaderDate = "Date"

	// Expires specifies the date/time after which the response is considered stale.
	// 	Example: "Thu, 01 Dec 1994 16:00:00 GMT"
	HeaderExpires = "Expires"

	// Age specifies the age of the response in seconds.
	// 	Example: "3600"
	HeaderAge = "Age"

	// Connection specifies control options for the current connection (e.g., keep-alive or close).
	// 	Example: "keep-alive"
	HeaderConnection = "Connection"

	// ContentLanguage specifies the language of the content.
	// 	Example: "en-US"
	HeaderContentLanguage = "Content-Language"

	// Forwarded contains information about intermediate proxies or gateways that have forwarded the request.
	// 	Example: "for=192.0.2.60;proto=http;by=203.0.113.43"
	HeaderForwarded = "Forwarded"

	// IfModifiedSince makes the request conditional on the target resource being modified since the specified date.
	// 	Example: "Wed, 21 Oct 2015 07:28:00 GMT"
	HeaderIfModifiedSince = "If-Modified-Since"

	// Upgrade requests the server to switch to a different protocol.
	// 	Example: "websocket"
	HeaderUpgrade = "Upgrade"

	// Via provides information about intermediate protocols and recipients between the user agent and the server.
	// 	Example: "1.1 proxy1.example.com, 1.0 proxy2.example.org"
	HeaderVia = "Via"

	// Warning carries additional information about the status or transformation of a message.
	// 	Example: "110 anderson/1.3.37 \"Response is stale\""
	HeaderWarning = "Warning"

	// XForwardedFor contains the originating IP address of a client connecting to a web server through an HTTP proxy or load balancer.
	// 	Example: "203.0.113.195, 70.41.3.18, 150.172.238.178"
	HeaderXForwardedFor = "X-Forwarded-For"

	// XForwardedHost contains the original host requested by the client in the Host HTTP request header.
	// 	Example: "example.com"
	HeaderXForwardedHost = "X-Forwarded-Host"

	// XForwardedProto specifies the protocol (HTTP or HTTPS) used by the client.
	// 	Example: "https"
	HeaderXForwardedProto = "X-Forwarded-Proto"

	// XRequestedWith identifies the type of request being made (e.g., Ajax requests).
	// 	Example: "XMLHttpRequest"
	HeaderXRequestedWith = "X-Requested-With"

	// XFrameOptions specifies whether the browser should be allowed to render the page in a <frame>, <iframe>, <object>, <embed>, or <applet>.
	// 	Example: "DENY" or "SAMEORIGIN"
	HeaderXFrameOptions = "X-Frame-Options"

	// XXSSProtection controls browser's built-in XSS (Cross-Site Scripting) filter.
	// 	Example: "1; mode=block"
	HeaderXXSSProtection = "X-XSS-Protection"

	// XContentTypeOpts prevents browsers from interpreting files as a different MIME type than what is specified.
	// 	Example: "nosniff"
	HeaderXContentTypeOpts = "X-Content-Type-Options"

	// ContentSecurity specifies security policy for web applications, helping to prevent certain types of attacks.
	// 	Example: "default-src 'self'; script-src 'self' 'unsafe-inline'"
	HeaderContentSecurity = "Content-Security-Policy"

	// StrictTransport enforces the use of HTTPS for the website to reduce security risks.
	// 	Example: "max-age=31536000; includeSubDomains"
	HeaderStrictTransport = "Strict-Transport-Security"

	// PublicKeyPins specifies public key pins to prevent man-in-the-middle attacks.
	// 	Example: "pin-sha256=\"base64+primary==\"; pin-sha256=\"base64+backup==\"; max-age=5184000"
	HeaderPublicKeyPins = "Public-Key-Pins"

	// ExpectCT allows websites to specify a Certificate Transparency policy.
	// 	Example: "max-age=86400, enforce"
	HeaderExpectCT = "Expect-CT"

	// AccessControlAllowOrigin specifies which domains are allowed to access the resources.
	// 	Example: "*" or "https://example.com"
	HeaderAccessControlAllowOrigin = "Access-Control-Allow-Origin"

	// AccessControlAllowMethods specifies which HTTP methods are allowed when accessing the resource.
	// 	Example: "GET, POST, PUT, DELETE"
	HeaderAccessControlAllowMethods = "Access-Control-Allow-Methods"

	// AccessControlAllowHeaders specifies which HTTP headers can be used during the actual request.
	// 	Example: "Content-Type, Authorization"
	HeaderAccessControlAllowHeaders = "Access-Control-Allow-Headers"

	// AccessControlMaxAge specifies how long the results of a preflight request can be cached.
	// 	Example: "86400"
	HeaderAccessControlMaxAge = "Access-Control-Max-Age"

	// AccessControlExposeHeaders specifies which headers can be exposed as part of the response.
	// 	Example: "Content-Length, X-JSON"
	HeaderAccessControlExposeHeaders = "Access-Control-Expose-Headers"

	// AccessControlRequestMethod indicates which HTTP method will be used during the actual request.
	// 	Example: "POST"
	HeaderAccessControlRequestMethod = "Access-Control-Request-Method"

	// AccessControlRequestHeaders specifies which headers can be sent with the actual request.
	// 	Example: "Content-Type, X-Custom-Header"
	HeaderAccessControlRequestHeaders = "Access-Control-Request-Headers"

	// AcceptPatch specifies which patch document formats are acceptable in the response.
	// 	Example: "application/json-patch+json"
	HeaderAcceptPatch = "Accept-Patch"

	// DeltaBase specifies the URI of the delta information.
	// 	Example: "\"abc123\""
	HeaderDeltaBase = "Delta-Base"

	// IfUnmodifiedSince makes the request conditional on the resource not being modified since the specified date.
	// 	Example: "Wed, 21 Oct 2015 07:28:00 GMT"
	HeaderIfUnmodifiedSince = "If-Unmodified-Since"

	// AcceptRanges specifies the range of the resource that the client is requesting.
	// 	Example: "bytes"
	HeaderAcceptRanges = "Accept-Ranges"

	// ContentRange specifies the range of the resource being sent in the response.
	// 	Example: "bytes 200-1000/5000"
	HeaderContentRange = "Content-Range"

	// Allow specifies the allowed methods for a resource.
	// 	Example: "GET, HEAD, PUT"
	HeaderAllow = "Allow"

	// AccessControlAllowCredentials indicates whether the response to the request can expose credentials.
	// 	Example: "true"
	HeaderAccessControlAllowCredentials = "Access-Control-Allow-Credentials"

	// XCSRFToken is used to prevent Cross-Site Request Forgery (CSRF) attacks.
	// 	Example: "i8XNjC4b8KVok4uw5RftR38Wgp2BF"
	HeaderXCSRFToken = "X-CSRF-Token"

	// XRealIP contains the real IP address of the client, often used in proxies or load balancers.
	// 	Example: "203.0.113.195"
	HeaderXRealIP = "X-Real-IP"

	// ContentSecurityPolicy specifies content security policies to prevent certain attacks.
	// 	Example: "default-src 'self'; img-src *; media-src media1.com media2.com"
	HeaderContentSecurityPolicy = "Content-Security-Policy"

	// ReferrerPolicy controls how much information about the referring page is sent.
	// 	Example: "no-referrer-when-downgrade"
	HeaderReferrerPolicy = "Referrer-Policy"

	// ExpectCt specifies a Certificate Transparency policy for the web server.
	// 	Example: "max-age=86400, enforce, report-uri=\"https://example.com/report\""
	HeaderExpectCt = "Expect-CT"

	// StrictTransportSecurity enforces HTTPS to reduce the chance of security breaches.
	// 	Example: "max-age=63072000; includeSubDomains; preload"
	HeaderStrictTransportSecurity = "Strict-Transport-Security"

	// UpgradeInsecureRequests requests the browser to upgrade any insecure requests to secure HTTPS requests.
	// 	Example: "1"
	HeaderUpgradeInsecureRequests = "Upgrade-Insecure-Requests"
)

Standard HTTP headers related to content negotiation and encoding.

View Source 
const (
	// ApplicationJSON specifies that the content is JSON-formatted data.
	//  Example: "application/json"
	MediaTypeApplicationJSON = "application/json"

	// ApplicationJSONUTF8 specifies that the content is JSON-formatted data with UTF-8 character encoding.
	//  Example: "application/json; charset=utf-8"
	MediaTypeApplicationJSONUTF8 = "application/json; charset=utf-8"

	// ApplicationXML specifies that the content is XML-formatted data.
	//  Example: "application/xml"
	MediaTypeApplicationXML = "application/xml"

	// ApplicationForm specifies that the content is URL-encoded form data.
	//  Example: "application/x-www-form-urlencoded"
	MediaTypeApplicationForm = "application/x-www-form-urlencoded"

	// ApplicationOctetStream specifies that the content is binary data (not interpreted by the browser).
	//  Example: "application/octet-stream"
	MediaTypeApplicationOctetStream = "application/octet-stream"

	// TextPlain specifies that the content is plain text.
	//  Example: "text/plain"
	MediaTypeTextPlain = "text/plain"

	// TextHTML specifies that the content is HTML-formatted data.
	//  Example: "text/html"
	MediaTypeTextHTML = "text/html"

	// ImageJPEG specifies that the content is a JPEG image.
	//  Example: "image/jpeg"
	MediaTypeImageJPEG = "image/jpeg"

	// ImagePNG specifies that the content is a PNG image.
	//  Example: "image/png"
	MediaTypeImagePNG = "image/png"

	// ImageGIF specifies that the content is a GIF image.
	//  Example: "image/gif"
	MediaTypeImageGIF = "image/gif"

	// AudioMP3 specifies that the content is an MP3 audio file.
	//  Example: "audio/mpeg"
	MediaTypeAudioMP3 = "audio/mpeg"

	// AudioWAV specifies that the content is a WAV audio file.
	//  Example: "audio/wav"
	MediaTypeAudioWAV = "audio/wav"

	// VideoMP4 specifies that the content is an MP4 video file.
	//  Example: "video/mp4"
	MediaTypeVideoMP4 = "video/mp4"

	// VideoAVI specifies that the content is an AVI video file.
	//  Example: "video/x-msvideo"
	MediaTypeVideoAVI = "video/x-msvideo"

	// ApplicationPDF specifies that the content is a PDF file.
	//  Example: "application/pdf"
	MediaTypeApplicationPDF = "application/pdf"

	// ApplicationMSWord specifies that the content is a Microsoft Word document (.doc).
	//  Example: "application/msword"
	MediaTypeApplicationMSWord = "application/msword"

	// ApplicationMSPowerPoint specifies that the content is a Microsoft PowerPoint presentation (.ppt).
	//  Example: "application/vnd.ms-powerpoint"
	MediaTypeApplicationMSPowerPoint = "application/vnd.ms-powerpoint"

	// ApplicationExcel specifies that the content is a Microsoft Excel spreadsheet (.xls).
	//  Example: "application/vnd.ms-excel"
	MediaTypeApplicationExcel = "application/vnd.ms-excel"

	// ApplicationZip specifies that the content is a ZIP archive.
	//  Example: "application/zip"
	MediaTypeApplicationZip = "application/zip"

	// ApplicationGzip specifies that the content is a GZIP-compressed file.
	//  Example: "application/gzip"
	MediaTypeApplicationGzip = "application/gzip"

	// MultipartFormData specifies that the content is a multipart form, typically used for file uploads.
	//  Example: "multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW"
	MediaTypeMultipartFormData = "multipart/form-data"

	// ImageBMP specifies that the content is a BMP image.
	//  Example: "image/bmp"
	MediaTypeImageBMP = "image/bmp"

	// ImageTIFF specifies that the content is a TIFF image.
	//  Example: "image/tiff"
	MediaTypeImageTIFF = "image/tiff"

	// TextCSS specifies that the content is CSS (Cascading Style Sheets).
	//  Example: "text/css"
	MediaTypeTextCSS = "text/css"

	// TextJavaScript specifies that the content is JavaScript code.
	//  Example: "text/javascript"
	MediaTypeTextJavaScript = "text/javascript"

	// ApplicationJSONLD specifies that the content is a JSON-LD (JSON for Linked Data) document.
	//  Example: "application/ld+json"
	MediaTypeApplicationJSONLD = "application/ld+json"

	// ApplicationRDFXML specifies that the content is in RDF (Resource Description Framework) XML format.
	//  Example: "application/rdf+xml"
	MediaTypeApplicationRDFXML = "application/rdf+xml"

	// ApplicationGeoJSON specifies that the content is a GeoJSON (geospatial data) document.
	//  Example: "application/geo+json"
	MediaTypeApplicationGeoJSON = "application/geo+json"

	// ApplicationMsgpack specifies that the content is in MessagePack format (binary JSON).
	//  Example: "application/msgpack"
	MediaTypeApplicationMsgpack = "application/msgpack"

	// ApplicationOgg specifies that the content is an Ogg multimedia container format.
	//  Example: "application/ogg"
	MediaTypeApplicationOgg = "application/ogg"

	// ApplicationGraphQL specifies that the content is in GraphQL format.
	//  Example: "application/graphql"
	MediaTypeApplicationGraphQL = "application/graphql"

	// ApplicationProtobuf specifies that the content is in Protocol Buffers format (binary serialization).
	//  Example: "application/protobuf"
	MediaTypeApplicationProtobuf = "application/protobuf"

	// ImageWebP specifies that the content is a WebP image.
	//  Example: "image/webp"
	MediaTypeImageWebP = "image/webp"

	// FontWOFF specifies that the content is a WOFF (Web Open Font Format) font.
	//  Example: "font/woff"
	MediaTypeFontWOFF = "font/woff"

	// FontWOFF2 specifies that the content is a WOFF2 (Web Open Font Format 2) font.
	//  Example: "font/woff2"
	MediaTypeFontWOFF2 = "font/woff2"

	// AudioFLAC specifies that the content is a FLAC audio file (Free Lossless Audio Codec).
	//  Example: "audio/flac"
	MediaTypeAudioFLAC = "audio/flac"

	// VideoWebM specifies that the content is a WebM video file.
	//  Example: "video/webm"
	MediaTypeVideoWebM = "video/webm"

	// ApplicationDart specifies that the content is a Dart programming language file.
	//  Example: "application/dart"
	MediaTypeApplicationDart = "application/dart"

	// ApplicationXLSX specifies that the content is an Excel file in XLSX format.
	//  Example: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
	MediaTypeApplicationXLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

	// ApplicationPPTX specifies that the content is a PowerPoint file in PPTX format.
	//  Example: "application/vnd.openxmlformats-officedocument.presentationml.presentation"
	MediaTypeApplicationPPTX = "application/vnd.openxmlformats-officedocument.presentationml.presentation"

	// ApplicationGRPC specifies that the content is in gRPC format (a high-performance RPC framework).
	//  Example: "application/grpc"
	MediaTypeApplicationGRPC = "application/grpc"
)

Media Type constants define commonly used MIME types for different content types in HTTP requests and responses.

View Source 
const (
	// ErrUnknown is a constant string used to represent an unknown or unspecified value in the context of XC (cross-cutting) concerns.
	// It is typically used as a placeholder when the actual value is not available or not applicable.
	ErrUnknown string = "replify: error unknown"
)

Common constants used across the package.

Variables

View Source 
var (
	// 1xx Informational responses
	// Continue indicates that the initial part of the request has been received and has not yet been rejected by the server.
	Continue = Header().WithCode(100).WithText("Continue").WithType("Informational")
	// SwitchingProtocols indicates that the server will switch protocols as requested by the client.
	SwitchingProtocols = Header().WithCode(101).WithText("Switching Protocols").WithType("Informational")
	// Processing indicates that the server has received and is processing the request but no response is available yet.
	Processing = Header().WithCode(102).WithText("Processing").WithType("Informational")

	// 2xx Successful responses
	// OK indicates that the request has succeeded.
	OK = Header().WithCode(200).WithText("OK").WithType("Successful")
	// Created indicates that the request has been fulfilled and has resulted in a new resource being created.
	Created = Header().WithCode(201).WithText("Created").WithType("Successful")
	// Accepted indicates that the request has been accepted for processing, but the processing has not been completed.
	Accepted = Header().WithCode(202).WithText("Accepted").WithType("Successful")
	// NonAuthoritativeInformation indicates that the request was successful, but the enclosed metadata may be from a different source.
	NonAuthoritativeInformation = Header().WithCode(203).WithText("Non-Authoritative Information").WithType("Successful")
	// NoContent indicates that the server successfully processed the request, but is not returning any content.
	NoContent = Header().WithCode(204).WithText("No Content").WithType("Successful")
	// ResetContent indicates that the server successfully processed the request and requests the client to reset the document view.
	ResetContent = Header().WithCode(205).WithText("Reset Content").WithType("Successful")
	// PartialContent indicates that the server is delivering only part of the resource due to a range request.
	PartialContent = Header().WithCode(206).WithText("Partial Content").WithType("Successful")
	// MultiStatus provides status for multiple independent operations.
	MultiStatus = Header().WithCode(207).WithText("Multi-Status").WithType("Successful")
	// AlreadyReported indicates that the members of a DAV binding have already been enumerated in a previous reply.
	AlreadyReported = Header().WithCode(208).WithText("Already Reported").WithType("Successful")
	// IMUsed indicates that the server has fulfilled a GET request for the resource and the response is a representation of the result.
	IMUsed = Header().WithCode(226).WithText("IM Used").WithType("Successful")

	// 3xx Redirection responses
	// MultipleChoices indicates multiple options for the resource are available.
	MultipleChoices = Header().WithCode(300).WithText("Multiple Choices").WithType("Redirection")
	// MovedPermanently indicates that the resource has been permanently moved to a new URI.
	MovedPermanently = Header().WithCode(301).WithText("Moved Permanently").WithType("Redirection")
	// Found indicates that the resource has been temporarily moved to a different URI.
	Found = Header().WithCode(302).WithText("Found").WithType("Redirection")
	// SeeOther indicates that the response to the request can be found under another URI.
	SeeOther = Header().WithCode(303).WithText("See Other").WithType("Redirection")
	// NotModified indicates that the resource has not been modified since the last request.
	NotModified = Header().WithCode(304).WithText("Not Modified").WithType("Redirection")
	// UseProxy indicates that the requested resource must be accessed through the proxy given by the location field.
	UseProxy = Header().WithCode(305).WithText("Use Proxy").WithType("Redirection")
	// Reserved is a deprecated status code reserved for future use.
	Reserved = Header().WithCode(306).WithText("Reserved").WithType("Redirection")
	// TemporaryRedirect indicates that the resource has been temporarily moved to a different URI and will return to the original URI later.
	TemporaryRedirect = Header().WithCode(307).WithText("Temporary Redirect").WithType("Redirection")
	// PermanentRedirect indicates that the resource has been permanently moved to a new URI and future requests should use this URI.
	PermanentRedirect = Header().WithCode(308).WithText("Permanent Redirect").WithType("Redirection")

	// 4xx Client error responses
	// BadRequest indicates that the server could not understand the request due to invalid syntax.
	BadRequest = Header().WithCode(400).WithText("Bad Request").WithType("Client Error")
	// Unauthorized indicates that the client must authenticate itself to get the requested response.
	Unauthorized = Header().WithCode(401).WithText("Unauthorized").WithType("Client Error")
	// PaymentRequired is reserved for future use, indicating payment is required to access the resource.
	PaymentRequired = Header().WithCode(402).WithText("Payment Required").WithType("Client Error")
	// Forbidden indicates that the server understands the request but refuses to authorize it.
	Forbidden = Header().WithCode(403).WithText("Forbidden").WithType("Client Error")
	// NotFound indicates that the server can't find the requested resource.
	NotFound = Header().WithCode(404).WithText("Not Found").WithType("Client Error")
	// MethodNotAllowed indicates that the server knows the request method but the target resource doesn't support this method.
	MethodNotAllowed = Header().WithCode(405).WithText("Method Not Allowed").WithType("Client Error")
	// NotAcceptable indicates that the server cannot produce a response matching the list of acceptable values defined in the request's headers.
	NotAcceptable = Header().WithCode(406).WithText("Not Acceptable").WithType("Client Error")
	// ProxyAuthenticationRequired indicates that the client must first authenticate itself with the proxy.
	ProxyAuthenticationRequired = Header().WithCode(407).WithText("Proxy Authentication Required").WithType("Client Error")
	// RequestTimeout indicates that the server timed out waiting for the request.
	RequestTimeout = Header().WithCode(408).WithText("Request Timeout").WithType("Client Error")
	// Conflict indicates that the request conflicts with the current state of the server.
	Conflict = Header().WithCode(409).WithText("Conflict").WithType("Client Error")
	// Gone indicates that the requested resource is no longer available and will not be available again.
	Gone = Header().WithCode(410).WithText("Gone").WithType("Client Error")
	// LengthRequired indicates that the server requires the request to be sent with a Content-Length header.
	LengthRequired = Header().WithCode(411).WithText("Length Required").WithType("Client Error")
	// PreconditionFailed indicates that the server does not meet one of the preconditions set by the client.
	PreconditionFailed = Header().WithCode(412).WithText("Precondition Failed").WithType("Client Error")
	// RequestEntityTooLarge indicates that the request entity is larger than what the server is willing or able to process.
	RequestEntityTooLarge = Header().WithCode(413).WithText("Request Entity Too Large").WithType("Client Error")
	// RequestURITooLong indicates that the URI provided was too long for the server to process.
	RequestURITooLong = Header().WithCode(414).WithText("Request-URI Too Long").WithType("Client Error")
	// UnsupportedMediaType indicates that the media format of the requested data is not supported by the server.
	UnsupportedMediaType = Header().WithCode(415).WithText("Unsupported Media Type").WithType("Client Error")
	// RequestedRangeNotSatisfiable indicates that the range specified by the Range header cannot be satisfied.
	RequestedRangeNotSatisfiable = Header().WithCode(416).WithText("Requested Range Not Satisfiable").WithType("Client Error")
	// ExpectationFailed indicates that the server cannot meet the requirements of the Expect request-header field.
	ExpectationFailed = Header().WithCode(417).WithText("Expectation Failed").WithType("Client Error")
	// ImATeapot is a humorous response code indicating that the server is a teapot and refuses to brew coffee.
	ImATeapot = Header().WithCode(418).WithText("I’m a teapot").WithType("Client Error")
	// EnhanceYourCalm is a non-standard response code used to ask the client to reduce its request rate.
	EnhanceYourCalm = Header().WithCode(420).WithText("Enhance Your Calm").WithType("Client Error")
	// UnprocessableEntity indicates that the request was well-formed but could not be followed due to semantic errors.
	UnprocessableEntity = Header().WithCode(422).WithText("Unprocessable Entity").WithType("Client Error")
	// Locked indicates that the resource being accessed is locked.
	Locked = Header().WithCode(423).WithText("Locked").WithType("Client Error")
	// FailedDependency indicates that the request failed due to failure of a previous request.
	FailedDependency = Header().WithCode(424).WithText("Failed Dependency").WithType("Client Error")
	// UnorderedCollection is a non-standard response code indicating an unordered collection.
	UnorderedCollection = Header().WithCode(425).WithText("Unordered Collection").WithType("Client Error")
	// UpgradeRequired indicates that the client should switch to a different protocol.
	UpgradeRequired = Header().WithCode(426).WithText("Upgrade Required").WithType("Client Error")
	// PreconditionRequired indicates that the origin server requires the request to be conditional.
	PreconditionRequired = Header().WithCode(428).WithText("Precondition Required").WithType("Client Error")
	// TooManyRequests indicates that the user has sent too many requests in a given time.
	TooManyRequests = Header().WithCode(429).WithText("Too Many Requests").WithType("Client Error")
	// RequestHeaderFieldsTooLarge indicates that one or more header fields in the request are too large.
	RequestHeaderFieldsTooLarge = Header().WithCode(431).WithText("Request Header Fields Too Large").WithType("Client Error")
	// NoResponse is a non-standard code indicating that the server has no response to provide.
	NoResponse = Header().WithCode(444).WithText("No Response").WithType("Client Error")
	// RetryWith is a non-standard code indicating that the client should retry with different parameters.
	RetryWith = Header().WithCode(449).WithText("Retry With").WithType("Client Error")
	// BlockedByWindowsParentalControls is a non-standard code indicating that the request was blocked by parental controls.
	BlockedByWindowsParentalControls = Header().WithCode(450).WithText("Blocked by Windows Parental Controls").WithType("Client Error")
	// UnavailableForLegalReasons indicates that the server is denying access to the resource for legal reasons.
	UnavailableForLegalReasons = Header().WithCode(451).WithText("Unavailable For Legal Reasons").WithType("Client Error")
	// ClientClosedRequest is a non-standard code indicating that the client closed the connection before the server's response.
	ClientClosedRequest = Header().WithCode(499).WithText("Client Closed Request").WithType("Client Error")

	// 5xx Server error responses
	// InternalServerError indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
	InternalServerError = Header().WithCode(500).WithText("Internal Server Error").WithType("Server Error")
	// NotImplemented indicates that the server does not support the functionality required to fulfill the request.
	NotImplemented = Header().WithCode(501).WithText("Not Implemented").WithType("Server Error")
	// BadGateway indicates that the server received an invalid response from an upstream server.
	BadGateway = Header().WithCode(502).WithText("Bad Gateway").WithType("Server Error")
	// ServiceUnavailable indicates that the server is currently unavailable (e.g., overloaded or under maintenance).
	ServiceUnavailable = Header().WithCode(503).WithText("Service Unavailable").WithType("Server Error")
	// GatewayTimeout indicates that the server did not receive a timely response from an upstream server.
	GatewayTimeout = Header().WithCode(504).WithText("Gateway Timeout").WithType("Server Error")
	// HTTPVersionNotSupported indicates that the server does not support the HTTP protocol version used in the request.
	HTTPVersionNotSupported = Header().WithCode(505).WithText("HTTP Version Not Supported").WithType("Server Error")
	// VariantAlsoNegotiates indicates an internal server configuration error leading to circular references.
	VariantAlsoNegotiates = Header().WithCode(506).WithText("Variant Also Negotiates").WithType("Server Error")
	// InsufficientStorage indicates that the server is unable to store the representation needed to complete the request.
	InsufficientStorage = Header().WithCode(507).WithText("Insufficient Storage").WithType("Server Error")
	// LoopDetected indicates that the server detected an infinite loop while processing the request.
	LoopDetected = Header().WithCode(508).WithText("Loop Detected").WithType("Server Error")
	// BandwidthLimitExceeded is a non-standard code indicating that the server's bandwidth limit has been exceeded.
	BandwidthLimitExceeded = Header().WithCode(509).WithText("Bandwidth Limit Exceeded").WithType("Server Error")
	// NotExtended indicates that further extensions to the request are required for the server to fulfill it.
	NotExtended = Header().WithCode(510).WithText("Not Extended").WithType("Server Error")
	// NetworkAuthenticationRequired indicates that the client needs to authenticate to gain network access.
	NetworkAuthenticationRequired = Header().WithCode(511).WithText("Network Authentication Required").WithType("Server Error")
	// NetworkReadTimeoutError is a non-standard code indicating a network read timeout error.
	NetworkReadTimeoutError = Header().WithCode(598).WithText("Network Read Timeout Error").WithType("Server Error")
	// NetworkConnectTimeoutError is a non-standard code indicating a network connection timeout error.
	NetworkConnectTimeoutError = Header().WithCode(599).WithText("Network Connect Timeout Error").WithType("Server Error")
)
View Source 
var Toolbox tools = tools{}

Functions

func AppendError 

func AppendError(err error, message string) error

AppendError annotates an existing error with a new message. If the error is nil, it returns nil.

Usage example: 

err := errors.New("original error")
errWithMessage := AppendError(err, "Additional context")
fmt.Println(errWithMessage) // "Additional context: original error"

func AppendErrorAck 

func AppendErrorAck(err error, message string) error

AppendErrorAck returns an error that annotates the provided error with a new message and a stack trace at the point AppendErrorAck was called. If the provided error is nil, AppendErrorAck returns nil.

Usage example: 

err := errors.New("file not found")
wrappedErr := AppendErrorAck(err, "Failed to read the file")
fmt.Println(wrappedErr) // "Failed to read the file: file not found" with stack trace

func AppendErrorAckf 

func AppendErrorAckf(err error, format string, args ...any) error

AppendErrorAckf returns an error that annotates the provided error with a formatted message and a stack trace at the point AppendErrorAckf was called. If the provided error is nil, AppendErrorAckf returns nil.

Usage example: 

err := errors.New("file not found")
wrappedErr := AppendErrorAckf(err, "Failed to read file %s", filename)
fmt.Println(wrappedErr) // "Failed to read file <filename>: file not found" with stack trace

func AppendErrorf 

func AppendErrorf(err error, format string, args ...any) error

AppendErrorf annotates an existing error with a formatted message. If the error is nil, it returns nil.

Usage example: 

err := errors.New("original error")
errWithMessage := AppendErrorf(err, "Context: %s", "something went wrong")
fmt.Println(errWithMessage) // "Context: something went wrong: original error"

func Callers 

func Callers() *stack

Callers captures the current call stack as a stack of program counters.

Usage: Use this function to capture the stack trace of the current execution context.

Example: 

st := Callers()
trace := st.StackTrace()
fmt.Printf("%+v", trace)

func Cause 

func Cause(err error) error

Cause traverses the error chain and returns the underlying cause of the error if it implements the `Cause()` method. If the error doesn't implement `Cause()`, it simply returns the original error. If the error is nil, nil is returned.

Usage example: 

err := Wrap(errors.New("file not found"), "Failed to open file")
causeErr := Cause(err)
fmt.Println(causeErr) // "file not found"

An error value has a cause if it implements the following interface: 

type causer interface {
       Cause() error
}

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

func FromPages 

func FromPages(totalItems int, perPage int) *pagination

FromPages creates a new instance of the `pagination` struct with specified total items and items per page.

This function initializes a `pagination` struct and sets the total number of items and items per page using the provided parameters.

Parameters:

  • totalItems: The total number of items to be paginated.
  • perPage: The number of items to be displayed per page.

Returns:

  • A pointer to a newly created `pagination` instance with the specified settings.
func Header() *header

Header creates a new instance of the `header` struct.

This function initializes a `header` struct with its default values.

Returns:

  • A pointer to a newly created `header` instance.

func Meta 

func Meta() *meta

Meta creates a new instance of the `meta` struct.

This function initializes a `meta` struct with its default values, including an empty `CustomFields` map.

Returns:

  • A pointer to a newly created `meta` instance with initialized fields.

func New 

func New() *wrapper

New creates a new instance of the `wrapper` struct.

This function initializes a `wrapper` struct with its default values, including an empty map for the `Debug` field.

Returns:

  • A pointer to a newly created `wrapper` instance with initialized fields.

func NewError 

func NewError(message string) error

NewError returns an error with the supplied message and records the stack trace at the point it was called. The error contains the message and the stack trace which can be used for debugging or logging the error along with the call stack.

Usage example: 

err := NewError("Something went wrong")
fmt.Println(err) // "Something went wrong" along with stack trace

func NewErrorAck 

func NewErrorAck(err error) error

NewErrorAck annotates an existing error with a stack trace at the point NewErrorAck was called. If the provided error is nil, it simply returns nil.

Usage example: 

err := errors.New("original error")
errWithStack := NewErrorAck(err)
fmt.Println(errWithStack) // original error with stack trace

func NewErrorAckf 

func NewErrorAckf(err error, format string, args ...any) error

NewErrorAckf returns an error that annotates the provided error with a formatted message and a stack trace at the point NewErrorAckf was called. If the provided error is nil, NewErrorAckf returns nil.

Usage example: 

err := errors.New("file not found")
wrappedErr := NewErrorAckf(err, "Failed to load file %s", filename)
fmt.Println(wrappedErr) // "Failed to load file <filename>: file not found" with stack trace

func NewErrorf 

func NewErrorf(format string, args ...any) error

NewErrorf formats the given arguments according to the format specifier and returns the formatted string as an error. It also records the stack trace at the point it was called.

Usage example: 

err := NewErrorf("Failed to load file %s", filename)
fmt.Println(err) // "Failed to load file <filename>" along with stack trace

func Pages 

func Pages() *pagination

Pages creates a new instance of the `pagination` struct.

This function initializes a `pagination` struct with its default values.

Returns:

  • A pointer to a newly created `pagination` instance.

func UnwrapJSON 

func UnwrapJSON(jsonStr string) (w *wrapper, err error)

UnwrapJSON parses a raw JSON string and maps it into a [wrapper] struct.

The input is first normalised (comments stripped, whitespace compacted) and validated before unmarshaling. The following top-level JSON keys are recognised and mapped to the corresponding wrapper field: 

JSON key       wrapper field   Notes
──────────────────────────────────────────────────────────────────────────
"status_code"  statusCode      float64 → int
"total"        total           float64 → int
"message"      message         string
"path"         path            string
"data"         data            string/[]byte → json.RawMessage when valid
                                JSON; any other type stored as-is
"debug"        debug           map[string]any
"header"       header          object → *header (code, text, type,
                                description)
"meta"         meta            object → *meta (api_version, locale,
                                request_id, requested_time,
                                custom_fields)
"pagination"   pagination      object → *pagination (page, per_page,
                                total_pages, total_items, is_last)

Unknown top-level keys are silently ignored. Missing keys leave the corresponding field at its zero value—no error is returned.

Parameters:

  • `jsonStr`: the raw JSON string to parse; may contain JS-style comments or trailing commas, which are stripped during normalisation.

Returns:

a non-nil *wrapper and a nil error on success. Returns nil, err when jsonStr is empty, fails normalisation, or is not valid JSON after normalisation.

Example: 

jsonStr := `{
    "status_code": 200,
    "message":     "OK",
    "path":        "/api/v1/users",
    "data": [
        {"id": "u1", "username": "alice"},
        {"id": "u2", "username": "bob"}
    ],
    "pagination": {
        "page": 1, "per_page": 2,
        "total_items": 42, "total_pages": 21,
        "is_last": false
    },
    "meta": {
        "request_id":     "req_abc123",
        "api_version":    "v1.0.0",
        "locale":         "en_US",
        "requested_time": "2026-03-09T07:00:00Z"
    }
}`

w, err := replify.UnwrapJSON(jsonStr)
if err != nil {
    log.Fatalf("parse error: %v", err)
}
fmt.Println(w.JSONBodyParser().Get("0").Get("username").String()) // "alice"
fmt.Println(w.StatusCode())                                       // 200
fmt.Println(w.Pagination().TotalItems())                          // 42

func WrapAccepted 

func WrapAccepted(message string, data any) *wrapper

WrapAccepted creates a wrapper for a response indicating the request has been accepted for processing (202 WrapAccepted).

This function sets the HTTP status code to 202 (WrapAccepted) and includes a message and data payload in the response body. It is typically used when the request has been received but processing is not yet complete.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapBadGateway 

func WrapBadGateway(message string, data any) *wrapper

WrapBadGateway creates a wrapper for a response indicating a bad gateway (502 Bad Gateway).

This function sets the HTTP status code to 502 (Bad Gateway) and includes a message and data payload in the response body. It is typically used when the server, while acting as a gateway or proxy, received an invalid response from an upstream server.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapBadRequest 

func WrapBadRequest(message string, data any) *wrapper

WrapBadRequest creates a wrapper for a client error response (400 Bad Request).

This function sets the HTTP status code to 400 (Bad Request) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapConflict 

func WrapConflict(message string, data any) *wrapper

WrapConflict creates a wrapper for a response indicating a conflict (409 Conflict).

This function sets the HTTP status code to 409 (Conflict) and includes a message and data payload in the response body. It is typically used when the request conflicts with the current state of the server.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapCreated 

func WrapCreated(message string, data any) *wrapper

WrapCreated creates a wrapper for a resource creation response (201 WrapCreated).

This function sets the HTTP status code to 201 (WrapCreated) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapForbidden 

func WrapForbidden(message string, data any) *wrapper

WrapForbidden creates a wrapper for a response indicating access to the resource is forbidden (403 WrapForbidden).

This function sets the HTTP status code to 403 (WrapForbidden) and includes a message and data payload in the response body. It is typically used when the server understands the request but refuses to authorize it.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapFrom 

func WrapFrom(data map[string]any) (w *wrapper, err error)

WrapFrom converts a map containing API response data into a `wrapper` struct by serializing the map into JSON format and then parsing it.

The function is a helper that bridges between raw map data (e.g., deserialized JSON or other dynamic input) and the strongly-typed `wrapper` struct used in the codebase. It first converts the input map into a JSON string using `encoding.Json`, then calls the `Parse` function to handle the deserialization and field mapping to the `wrapper`.

Parameters:

  • data: A map[string]interface{} containing the API response data. The map should include keys like "status_code", "message", "meta", etc., that conform to the expected structure of a `wrapper`.

Returns:

  • A pointer to a `wrapper` struct populated with data from the map.
  • An error if the map is empty or if the JSON serialization/parsing fails.

Error Handling:

  • If the input map is empty or nil, the function returns an error indicating that the data is invalid.
  • If serialization or parsing fails, the error from `Parse` or `encoding.Json` is propagated, providing context about the failure.

Usage: This function is particularly useful when working with raw data maps (e.g., from dynamic inputs or unmarshaled data) that need to be converted into the `wrapper` struct for further processing.

Example: 

rawData := map[string]interface{}{
    "status_code": 200,
    "message": "Success",
    "data": "response body",
}
wrapper, err := replify.WrapFrom(rawData)
if err != nil {
    log.Println("Error extracting wrapper:", err)
} else {
    log.Println("Wrapper:", wrapper)
}

func WrapGatewayTimeout 

func WrapGatewayTimeout(message string, data any) *wrapper

WrapGatewayTimeout creates a wrapper for a response indicating a gateway timeout (504 Gateway Timeout).

This function sets the HTTP status code to 504 (Gateway Timeout) and includes a message and data payload in the response body. It is typically used when the server did not receive a timely response from an upstream server.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapGone 

func WrapGone(message string, data any) *wrapper

WrapGone creates a wrapper for a response indicating the resource is gone (410 Gone).

This function sets the HTTP status code to 410 (Gone) and includes a message and data payload in the response body. It is typically used when the requested resource is no longer available.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapHTTPVersionNotSupported 

func WrapHTTPVersionNotSupported(message string, data any) *wrapper

WrapHTTPVersionNotSupported creates a wrapper for a response indicating the HTTP version is not supported (505 HTTP Version Not Supported).

This function sets the HTTP status code to 505 (HTTP Version Not Supported) and includes a message and data payload in the response body. It is typically used when the server does not support the HTTP protocol version used in the request.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapInternalServerError 

func WrapInternalServerError(message string, data any) *wrapper

WrapInternalServerError creates a wrapper for a server error response (500 Internal Server Error).

This function sets the HTTP status code to 500 (Internal Server Error) and includes a message and data payload in the response body. It is typically used when the server encounters an unexpected condition that prevents it from fulfilling the request.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapLocked 

func WrapLocked(message string, data any) *wrapper

WrapLocked creates a wrapper for a locked resource response (423 WrapLocked).

This function sets the HTTP status code to 423 (WrapLocked) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapMethodNotAllowed 

func WrapMethodNotAllowed(message string, data any) *wrapper

WrapMethodNotAllowed creates a wrapper for a response indicating the HTTP method is not allowed (405 Method Not Allowed).

This function sets the HTTP status code to 405 (Method Not Allowed) and includes a message and data payload in the response body. It is typically used when the server knows the method is not supported for the target resource.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapNoContent 

func WrapNoContent(message string, data any) *wrapper

WrapNoContent creates a wrapper for a successful response without a body (204 No Content).

This function sets the HTTP status code to 204 (No Content) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapNotFound 

func WrapNotFound(message string, data any) *wrapper

WrapNotFound creates a wrapper for a resource not found response (404 Not Found).

This function sets the HTTP status code to 404 (Not Found) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapNotImplemented 

func WrapNotImplemented(message string, data any) *wrapper

WrapNotImplemented creates a wrapper for a response indicating unimplemented functionality (501 Not Implemented).

This function sets the HTTP status code to 501 (Not Implemented) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapOk 

func WrapOk(message string, data any) *wrapper

WrapOk creates a wrapper for a successful HTTP response (200 OK).

This function sets the HTTP status code to 200 (OK) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapPaymentRequired 

func WrapPaymentRequired(message string, data any) *wrapper

WrapPaymentRequired creates a wrapper for a response indicating payment is required (402 Payment Required).

This function sets the HTTP status code to 402 (Payment Required) and includes a message and data payload in the response body. It is typically used when access to the requested resource requires payment.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapPreconditionFailed 

func WrapPreconditionFailed(message string, data any) *wrapper

WrapPreconditionFailed creates a wrapper for a response indicating the precondition failed (412 Precondition Failed).

This function sets the HTTP status code to 412 (Precondition Failed) and includes a message and data payload in the response body. It is typically used when the request has not been applied because one or more conditions were not met.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapProcessing 

func WrapProcessing(message string, data any) *wrapper

WrapProcessing creates a wrapper for a response indicating ongoing processing (102 WrapProcessing).

This function sets the HTTP status code to 102 (WrapProcessing) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapRequestEntityTooLarge 

func WrapRequestEntityTooLarge(message string, data any) *wrapper

WrapRequestEntityTooLarge creates a wrapper for a response indicating the request entity is too large (413 Payload Too Large).

This function sets the HTTP status code to 413 (Payload Too Large) and includes a message and data payload in the response body. It is typically used when the server refuses to process a request because the request entity is larger than the server is willing or able to process.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapRequestTimeout 

func WrapRequestTimeout(message string, data any) *wrapper

WrapRequestTimeout creates a wrapper for a response indicating the client request has timed out (408 Request Timeout).

This function sets the HTTP status code to 408 (Request Timeout) and includes a message and data payload in the response body. It is typically used when the server did not receive a complete request message within the time it was prepared to wait.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapServiceUnavailable 

func WrapServiceUnavailable(message string, data any) *wrapper

WrapServiceUnavailable creates a wrapper for a response indicating the service is temporarily unavailable (503 Service Unavailable).

This function sets the HTTP status code to 503 (Service Unavailable) and includes a message and data payload in the response body. It is typically used when the server is unable to handle the request due to temporary overload or maintenance.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapTooManyRequest 

func WrapTooManyRequest(message string, data any) *wrapper

WrapTooManyRequest creates a wrapper for a rate-limiting response (429 Too Many Requests).

This function sets the HTTP status code to 429 (Too Many Requests) and includes a message and data payload in the response body.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapUnauthorized 

func WrapUnauthorized(message string, data any) *wrapper

WrapUnauthorized creates a wrapper for a response indicating authentication is required (401 WrapUnauthorized).

This function sets the HTTP status code to 401 (WrapUnauthorized) and includes a message and data payload in the response body. It is typically used when the request has not been applied because it lacks valid authentication credentials.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapUnprocessableEntity 

func WrapUnprocessableEntity(message string, data any) *wrapper

WrapUnprocessableEntity creates a wrapper for a response indicating the request was well-formed but was unable to be followed due to semantic errors (422 Unprocessable Entity).

This function sets the HTTP status code to 422 (Unprocessable Entity) and includes a message and data payload in the response body. It is typically used when the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapUnsupportedMediaType 

func WrapUnsupportedMediaType(message string, data any) *wrapper

WrapUnsupportedMediaType creates a wrapper for a response indicating the media type is not supported (415 Unsupported Media Type).

This function sets the HTTP status code to 415 (Unsupported Media Type) and includes a message and data payload in the response body. It is typically used when the server refuses to accept the request because the payload is in an unsupported format.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

func WrapUpgradeRequired 

func WrapUpgradeRequired(message string, data any) *wrapper

WrapUpgradeRequired creates a wrapper for a response indicating an upgrade is required (426 Upgrade Required).

This function sets the HTTP status code to 426 (Upgrade Required) and includes a message and data payload in the response body. It is typically used when the client must switch to a different protocol.

Parameters:

  • message: A string containing the response message.
  • data: The data payload to include in the response.

Returns:

  • A pointer to a `wrapper` instance representing the response.

Types

type BufferPool 

type BufferPool struct {
	// contains filtered or unexported fields
}

BufferPool for efficient buffer reuse

func NewBufferPool 

func NewBufferPool(bufferSize int64, poolSize int) *BufferPool

NewBufferPool creates new buffer pool

This function initializes a `BufferPool` struct with a specified buffer size and pool size.

Parameters:

  • bufferSize: The size of each buffer in bytes.
  • poolSize: The maximum number of buffers to maintain in the pool.

Returns:

  • A pointer to a newly created `BufferPool` instance with the specified settings.

func (*BufferPool) Get 

func (bp *BufferPool) Get() []byte

Get returns buffer from pool

If pool is empty, it creates a new buffer of predefined size

Returns:

  • A byte slice buffer

func (*BufferPool) Put 

func (bp *BufferPool) Put(buf []byte)

Put returns buffer to pool

If pool is full, the buffer is discarded

Parameters:

  • buf: A byte slice buffer to be returned to the pool

Returns:

  • None

type CompressionType 

type CompressionType string

CompressionType defines compression algorithm used for data transmission. 

const (
	// No compression applied
	CompressNone CompressionType = "none"

	// GZIP compression algorithm
	CompressGzip CompressionType = "gzip"

	// Deflate compression algorithm
	CompressDeflate CompressionType = "deflate"

	// Flate compression algorithm
	CompressFlate CompressionType = "flate"
)

CompressionType defines the type of compression applied to data. It specifies the algorithm used to compress or decompress data.

type Frame 

type Frame uintptr

Frame represents a program counter inside a stack frame. A `Frame` is essentially a single point in the stack trace, representing a program counter (the location in code) at the time of a function call. Historically, for compatibility reasons, a `Frame` is interpreted as a `uintptr`, but the value stored in the `Frame` represents the program counter + 1. This allows for distinguishing between an invalid program counter and a valid one.

A `Frame` is typically used within a `StackTrace` to track the sequence of function calls leading to the current point in the program. A frame is a low-level representation of a specific place in the code, helping in debugging by pinpointing the exact line of execution that caused an error or event.

Example usage: 

var f Frame = Frame(0x1234567890)
fmt.Println(f) // Prints the value of the program counter + 1

func (Frame) Format 

func (f Frame) Format(s fmt.State, verb rune)

Frame.Format formats the frame according to the fmt.Formatter interface.

Usage: The `verb` parameter controls the formatting output:

  • %s: Source file name.
  • %d: Source line number.
  • %n: Function name.
  • %v: Equivalent to %s:%d.

Flags:

  • %+s: Includes function name and path of the source file relative to the compile-time GOPATH.
  • %+v: Combines %+s and %d (function name, source path, and line number).

Example: 

frame := Frame(somePC)
fmt.Printf("%+v", frame)

func (Frame) MarshalText 

func (f Frame) MarshalText() ([]byte, error)

Frame.MarshalText formats a Frame as a text string. The output is the same as fmt.Sprintf("%+v", f), but without newlines or tabs.

Usage: Converts the Frame to a compact text representation, suitable for logging or serialization.

Example: 

frame := Frame(somePC)
text, err := frame.MarshalText()
if err == nil {
    fmt.Println(string(text))
}

type Locale 

type Locale string

Locale represents an IETF-style locale identifier formatted as language_COUNTRY (e.g., en_US). 

const (
	// English (United States)
	//  Example: en_US
	LocaleEnUS Locale = "en_US"

	// English (United Kingdom)
	//  Example: en_GB
	LocaleEnGB Locale = "en_GB"

	// English (Australia)
	//  Example: en_AU
	LocaleEnAU Locale = "en_AU"

	// English (Canada)
	//  Example: en_CA
	LocaleEnCA Locale = "en_CA"

	// Vietnamese (Vietnam)
	//  Example: vi_VN
	LocaleViVN Locale = "vi_VN"

	// French (France)
	//  Example: fr_FR
	LocaleFrFR Locale = "fr_FR"

	// French (Canada)
	//  Example: fr_CA
	LocaleFrCA Locale = "fr_CA"

	// German (Germany)
	//  Example: de_DE
	LocaleDeDE Locale = "de_DE"

	// Spanish (Spain)
	//  Example: es_ES
	LocaleEsES Locale = "es_ES"

	// Spanish (Mexico)
	//  Example: es_MX
	LocaleEsMX Locale = "es_MX"

	// Portuguese (Brazil)
	//  Example: pt_BR
	LocalePtBR Locale = "pt_BR"

	// Portuguese (Portugal)
	//  Example: pt_PT
	LocalePtPT Locale = "pt_PT"

	// Italian (Italy)
	//  Example: it_IT
	LocaleItIT Locale = "it_IT"

	// Dutch (Netherlands)
	//  Example: nl_NL
	LocaleNlNL Locale = "nl_NL"

	// Russian (Russia)
	//  Example: ru_RU
	LocaleRuRU Locale = "ru_RU"

	// Japanese (Japan)
	//  Example: ja_JP
	LocaleJaJP Locale = "ja_JP"

	// Korean (South Korea)
	//  Example: ko_KR
	LocaleKoKR Locale = "ko_KR"

	// Chinese (Simplified, China)
	//  Example: zh_CN
	LocaleZhCN Locale = "zh_CN"

	// Chinese (Traditional, Taiwan)
	//  Example: zh_TW
	LocaleZhTW Locale = "zh_TW"

	// Thai (Thailand)
	//  Example: th_TH
	LocaleThTH Locale = "th_TH"

	// Indonesian (Indonesia)
	//  Example: id_ID
	LocaleIdID Locale = "id_ID"

	// Malay (Malaysia)
	//  Example: ms_MY
	LocaleMsMY Locale = "ms_MY"

	// Hindi (India)
	//  Example: hi_IN
	LocaleHiIN Locale = "hi_IN"

	// Arabic (Saudi Arabia)
	//  Example: ar_SA
	LocaleArSA Locale = "ar_SA"

	// Turkish (Turkey)
	//  Example: tr_TR
	LocaleTrTR Locale = "tr_TR"

	// Polish (Poland)
	//  Example: pl_PL
	LocalePlPL Locale = "pl_PL"

	// Swedish (Sweden)
	//  Example: sv_SE
	LocaleSvSE Locale = "sv_SE"

	// Danish (Denmark)
	//  Example: da_DK
	LocaleDaDK Locale = "da_DK"

	// Norwegian (Norway)
	//  Example: nb_NO
	LocaleNbNO Locale = "nb_NO"

	// Finnish (Finland)
	//  Example: fi_FI
	LocaleFiFI Locale = "fi_FI"
)

Locale defines the language and regional settings for content localization. It specifies the language and country/region code.

type R 

type R struct {
	// contains filtered or unexported fields
}

R represents a wrapper around the main `wrapper` struct. It is used as a high-level abstraction to provide a simplified interface for handling API responses. The `R` type allows for easier manipulation of the wrapped data, metadata, and other response components, while maintaining the flexibility of the underlying `wrapper` structure.

func (R) AppendError 

func (w R) AppendError(err error, message string) *wrapper

AppendError adds a plain contextual message to an existing error and sets it for the `wrapper` instance.

This function wraps the provided error with an additional plain message and assigns it to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • message: A plain string message to add context to the error.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) AppendErrorAck 

func (w R) AppendErrorAck(err error, message string) *wrapper

AppendErrorAck wraps an existing error with an additional message and sets it for the `wrapper` instance.

This function adds context to the provided error by wrapping it with an additional message. The resulting error is assigned to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • message: A string message to add context to the error.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) AppendErrorf 

func (w R) AppendErrorf(err error, format string, args ...any) *wrapper

AppendErrorf adds a formatted contextual message to an existing error and sets it for the `wrapper` instance.

This function wraps the provided error with an additional formatted message and assigns it to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • format: A format string for constructing the contextual error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) AsStreaming 

func (w R) AsStreaming(reader io.Reader) *StreamingWrapper

AsStreaming converts a regular wrapper instance into a streaming-enabled response with default configuration.

This function provides a simplified, one-line alternative to WithStreaming for common streaming scenarios. It automatically creates a new wrapper if the receiver is nil and applies default streaming configuration, eliminating the need for manual configuration object creation. This is ideal for quick implementations where standard settings (64KB chunks, buffered strategy, no compression) are acceptable.

Parameters:

  • reader: An io.Reader implementation providing the source data stream (e.g., *os.File, *http.Response.Body, *bytes.Buffer). Cannot be nil; streaming will fail if no valid reader is provided.

Returns:

  • A pointer to a new StreamingWrapper instance configured with default settings:
  • ChunkSize: 65536 bytes (64KB)
  • Strategy: STRATEGY_BUFFERED
  • Compression: COMP_NONE
  • MaxConcurrentChunks: 4
  • UseBufferPool: true
  • ReadTimeout: 30 seconds
  • WriteTimeout: 30 seconds
  • If the receiver wrapper is nil, automatically creates a new wrapper before enabling streaming.
  • Returns a StreamingWrapper ready for optional configuration before calling Start().

Example: 

// Minimal streaming setup with defaults - best for simple file downloads
file, _ := os.Open("document.pdf")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/document").
    AsStreaming(file).
    WithTotalBytes(fileSize).
    Start(context.Background())

// Or without creating a new wrapper first
result := (*wrapper)(nil).
    AsStreaming(file).
    Start(context.Background())

Comparison: 

// Using AsStreaming (simple, defaults only)
streaming := response.AsStreaming(reader)

// Using WithStreaming (more control)
streaming := response.WithStreaming(reader, &StreamConfig{
    ChunkSize:           512 * 1024,
    Compression:         COMP_GZIP,
    MaxConcurrentChunks: 8,
})

See Also:

  • WithStreaming: For custom streaming configuration
  • NewStreamConfig: To create custom configuration objects
  • Start: Initiates the streaming operation
  • WithCallback: Adds progress tracking after AsStreaming

func (R) Available 

func (w R) Available() bool

Available checks whether the `wrapper` instance is non-nil.

This function ensures that the `wrapper` object exists and is not nil. It serves as a safety check to avoid null pointer dereferences when accessing the instance's fields or methods.

Returns:

  • A boolean value indicating whether the `wrapper` instance is non-nil:
  • `true` if the `wrapper` instance is non-nil.
  • `false` if the `wrapper` instance is nil.

func (R) AvgJSONBody 

func (w R) AvgJSONBody(path string) (float64, bool)

AvgJSONBody returns the arithmetic mean of all numeric values at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

avg, ok := w.AvgJSONBody("ratings")

func (R) BindCause 

func (w R) BindCause() *wrapper

BindCause sets the error for the `wrapper` instance using its current message.

This function creates an error object from the `message` field of the `wrapper`, assigns it to the `errors` field, and returns the modified instance. It allows for method chaining.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) Body 

func (w R) Body() any

Body retrieves the body data associated with the `wrapper` instance.

This function returns the `data` field of the `wrapper`, which contains the primary data payload of the response.

Returns:

  • The body data (of any type), or `nil` if no body data is present.

func (R) Cause 

func (w R) Cause() error

Cause traverses the error chain and returns the underlying cause of the error associated with the `wrapper` instance.

This function checks if the error stored in the `wrapper` is itself another `wrapper` instance. If so, it recursively calls `Cause` on the inner error to find the ultimate cause. Otherwise, it returns the current error.

Returns:

  • The underlying cause of the error, which can be another error or the original error.

func (R) Clone 

func (w R) Clone() *wrapper

Clone creates a deep copy of the `wrapper` instance.

This function creates a new `wrapper` instance with the same fields as the original instance. It creates a new `header`, `meta`, and `pagination` instances and copies the values from the original instance. It also creates a new `debug` map and copies the values from the original instance.

Returns:

  • A pointer to the cloned `wrapper` instance.
  • `nil` if the `wrapper` instance is not available.

func (R) CollectJSONBodyFloat64 

func (w R) CollectJSONBodyFloat64(path string) []float64

CollectJSONBodyFloat64 collects every value at the given path in the body that can be coerced to float64 (including string-encoded numbers). Non-numeric values are skipped.

Example: 

prices := w.CollectJSONBodyFloat64("items.#.price")

func (R) CompressSafe 

func (w R) CompressSafe(threshold int) *wrapper

CompressSafe compresses the body data if it exceeds a specified threshold.

This function checks if the `wrapper` instance is available and if the body data exceeds the specified threshold for compression. If the body data is larger than the threshold, it compresses the data using gzip and updates the body with the compressed data. It also adds debugging information about the compression process, including the original and compressed sizes. If the threshold is not specified or is less than or equal to zero, it defaults to 1024 bytes (1KB). It also removes any empty debugging fields to clean up the response. Parameters:

  • `threshold`: An integer representing the size threshold for compression. If the body data size exceeds this threshold, it will be compressed.

Returns:

  • A pointer to the `wrapper` instance, allowing for method chaining.

If the `wrapper` is not available, it returns the original instance without modifications.

func (R) CountJSONBody 

func (w R) CountJSONBody(path string) int

CountJSONBody returns the number of elements at the given path in the body. For an array result it returns the array length; for a scalar it returns 1; for a missing path it returns 0.

Example: 

n := w.CountJSONBody("items")

func (R) Debugging 

func (w R) Debugging() map[string]any

Debugging retrieves the debugging information from the `wrapper` instance.

This function checks if the `wrapper` instance is available (non-nil) before returning the value of the `debug` field. If the `wrapper` is not available, it returns an empty map to ensure safe usage.

Returns:

  • A `map[string]interface{}` containing the debugging information.
  • An empty map if the `wrapper` instance is not available.

func (R) DebuggingBool 

func (w R) DebuggingBool(key string, defaultValue bool) bool

DebuggingBool retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A boolean value to return if the key is not available.

Returns:

  • The boolean value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingDuration 

func (w R) DebuggingDuration(key string, defaultValue time.Duration) time.Duration

DebuggingDuration retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Duration value to return if the key is not available.

Returns:

  • The time.Duration value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingFloat32 

func (w R) DebuggingFloat32(key string, defaultValue float32) float32

DebuggingFloat32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float32 value to return if the key is not available.

Returns:

  • The float32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingFloat64 

func (w R) DebuggingFloat64(key string, defaultValue float64) float64

DebuggingFloat64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float64 value to return if the key is not available.

Returns:

  • The float64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingInt 

func (w R) DebuggingInt(key string, defaultValue int) int

DebuggingInt retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An integer value to return if the key is not available.

Returns:

  • The integer value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingInt8 

func (w R) DebuggingInt8(key string, defaultValue int8) int8

DebuggingInt8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int8 value to return if the key is not available.

Returns:

  • The int8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingInt16 

func (w R) DebuggingInt16(key string, defaultValue int16) int16

DebuggingInt16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int16 value to return if the key is not available.

Returns:

  • The int16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingInt32 

func (w R) DebuggingInt32(key string, defaultValue int32) int32

DebuggingInt32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int32 value to return if the key is not available.

Returns:

  • The int32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingInt64 

func (w R) DebuggingInt64(key string, defaultValue int64) int64

DebuggingInt64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int64 value to return if the key is not available.

Returns:

  • The int64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingString 

func (w R) DebuggingString(key string, defaultValue string) string

DebuggingString retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A string value to return if the key is not available.

Returns:

  • The string value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingTime 

func (w R) DebuggingTime(key string, defaultValue time.Time) time.Time

DebuggingTime retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Time value to return if the key is not available.

Returns:

  • The time.Time value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingUint 

func (w R) DebuggingUint(key string, defaultValue uint) uint

DebuggingUint retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint value to return if the key is not available.

Returns:

  • The uint value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingUint8 

func (w R) DebuggingUint8(key string, defaultValue uint8) uint8

DebuggingUint8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint8 value to return if the key is not available.

Returns:

  • The uint8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingUint16 

func (w R) DebuggingUint16(key string, defaultValue uint16) uint16

DebuggingUint16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint16 value to return if the key is not available.

Returns:

  • The uint16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingUint32 

func (w R) DebuggingUint32(key string, defaultValue uint32) uint32

DebuggingUint32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint32 value to return if the key is not available.

Returns:

  • The uint32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DebuggingUint64 

func (w R) DebuggingUint64(key string, defaultValue uint64) uint64

DebuggingUint64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint64 value to return if the key is not available.

Returns:

  • The uint64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) DecompressSafe 

func (w R) DecompressSafe() *wrapper

DecompressSafe decompresses the body data if it is compressed.

This function checks if the `wrapper` instance is available and if the body data is compressed. If the body data is compressed, it decompresses the data using gzip and updates the instance with the decompressed data. It also adds debugging information about the decompression process, including the original and decompressed sizes. If the body data is not compressed, it returns the original instance without modifications.

Returns:

  • A pointer to the `wrapper` instance, allowing for method chaining.

If the `wrapper` is not available, it returns the original instance without modifications.

func (R) DecreaseDeltaCnt 

func (w R) DecreaseDeltaCnt() *wrapper

DecreaseDeltaCnt decrements the delta count in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and decrements the delta count in the `meta` using the `DecreaseDeltaCnt` method.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) DeltaCnt 

func (w R) DeltaCnt() int

DeltaCnt retrieves the delta count from the `meta` instance.

This function checks if the `meta` instance is present and returns the `deltaCnt` field. If the `meta` instance is not present, it returns a default value of `0`.

Returns:

  • An integer representing the delta count.

func (R) DeltaValue 

func (w R) DeltaValue() float64

DeltaValue retrieves the delta value from the `meta` instance.

This function checks if the `meta` instance is present and returns the `deltaValue` field. If the `meta` instance is not present, it returns a default value of `0`.

Returns:

  • A float64 representing the delta value.

func (R) DistinctJSONBody 

func (w R) DistinctJSONBody(path string) []fj.Context

DistinctJSONBody evaluates the given path in the body and returns a deduplicated slice of values using each element's string representation as the equality key. First-occurrence order is preserved.

Example: 

tags := w.DistinctJSONBody("tags")

func (R) Error 

func (w R) Error() string

Error retrieves the error associated with the `wrapper` instance.

This function returns the `errors` field of the `wrapper`, which contains any errors encountered during the operation of the `wrapper`.

Returns:

  • An error object, or `nil` if no errors are present.

func (R) FilterJSONBody 

func (w R) FilterJSONBody(path string, fn func(fj.Context) bool) []fj.Context

FilterJSONBody evaluates the given path in the body, treats the result as an array, and returns only those elements for which fn returns true.

Example: 

active := w.FilterJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("active").Bool()
})

func (R) FindJSONBodyPath 

func (w R) FindJSONBodyPath(value string) string

FindJSONBodyPath returns the first dot-notation path in the body at which a scalar value equals the given string (exact, case-sensitive match).

Returns "" when no leaf matches.

Example: 

path := w.FindJSONBodyPath("[email protected]")

func (R) FindJSONBodyPathMatch 

func (w R) FindJSONBodyPathMatch(pattern string) string

FindJSONBodyPathMatch returns the first dot-notation path in the body at which a scalar value matches the given wildcard pattern.

Example: 

path := w.FindJSONBodyPathMatch("alice*")

func (R) FindJSONBodyPaths 

func (w R) FindJSONBodyPaths(value string) []string

FindJSONBodyPaths returns all dot-notation paths in the body at which a scalar value equals the given string.

Example: 

paths := w.FindJSONBodyPaths("active")

func (R) FindJSONBodyPathsMatch 

func (w R) FindJSONBodyPathsMatch(pattern string) []string

FindJSONBodyPathsMatch returns all dot-notation paths in the body at which a scalar value matches the given wildcard pattern.

Example: 

paths := w.FindJSONBodyPathsMatch("err*")

func (R) FirstJSONBody 

func (w R) FirstJSONBody(path string, fn func(fj.Context) bool) fj.Context

FirstJSONBody evaluates the given path in the body and returns the first element for which fn returns true. Returns a zero-value fj.Context when not found.

Example: 

admin := w.FirstJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("role").String() == "admin"
})

func (R) GroupByJSONBody 

func (w R) GroupByJSONBody(path, keyField string) map[string][]fj.Context

GroupByJSONBody groups the elements at the given path in the body by the string value of keyField, using conv.String for key normalization.

Example: 

byRole := w.GroupByJSONBody("users", "role")

func (R) Hash 

func (w R) Hash() uint64

This method generates a hash value for the `wrapper` instance using the `Hash` method. If the `wrapper` instance is not available or the hash generation fails, it returns an empty string.

Returns:

  • A string representing the hash value.
  • An empty string if the `wrapper` instance is not available or the hash generation fails.

func (R) Hash256 

func (w R) Hash256() string

Hash256 generates a hash string for the `wrapper` instance.

This method generates a hash string for the `wrapper` instance using the `Hash256` method. If the `wrapper` instance is not available or the hash generation fails, it returns an empty string.

Returns:

  • A string representing the hash value.
  • An empty string if the `wrapper` instance is not available or the hash generation fails.

func (R) Header 

func (w R) Header() *header

Header retrieves the `header` associated with the `wrapper` instance.

This function returns the `header` field from the `wrapper` instance, which contains information about the HTTP response or any other relevant metadata. If the `wrapper` instance is correctly initialized, it will return the `header`; otherwise, it may return `nil` if the `header` has not been set.

Returns:

  • A pointer to the `header` instance associated with the `wrapper`.
  • `nil` if the `header` is not set or the `wrapper` is uninitialized.

func (R) IncreaseDeltaCnt 

func (w R) IncreaseDeltaCnt() *wrapper

IncreaseDeltaCnt increments the delta count in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and increments the delta count in the `meta` using the `IncreaseDeltaCnt` method.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) IsBodyPresent 

func (w R) IsBodyPresent() bool

IsBodyPresent checks whether the body data is present in the `wrapper` instance.

This function checks if the `data` field of the `wrapper` is not nil, indicating that the body contains data.

Returns:

  • A boolean value indicating whether the body data is present:
  • `true` if `data` is not nil.
  • `false` if `data` is nil.

func (R) IsClientError 

func (w R) IsClientError() bool

IsClientError checks whether the HTTP status code indicates a client error.

This function checks if the `statusCode` is between 400 and 499, inclusive, which indicates a client error HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a client error:
  • `true` if the status code is between 400 and 499 (inclusive).
  • `false` if the status code is outside of this range.

func (R) IsDebuggingKeyPresent 

func (w R) IsDebuggingKeyPresent(key string) bool

IsDebuggingKeyPresent checks whether a specific key exists in the `debug` information.

This function first checks if debugging information is present using `IsDebuggingPresent()`. Then it uses `coll.MapContainsKey` to verify if the given key is present within the `debug` map.

Parameters:

  • `key`: The key to search for within the `debug` field.

Returns:

  • A boolean value indicating whether the specified key is present in the `debug` map:
  • `true` if the `debug` field is present and contains the specified key.
  • `false` if `debug` is nil or does not contain the key.

func (R) IsDebuggingPresent 

func (w R) IsDebuggingPresent() bool

IsDebuggingPresent checks whether debugging information is present in the `wrapper` instance.

This function verifies if the `debug` field of the `wrapper` is not nil and contains at least one entry. It returns `true` if debugging information is available; otherwise, it returns `false`.

Returns:

  • A boolean value indicating whether debugging information is present:
  • `true` if `debug` is not nil and contains data.
  • `false` if `debug` is nil or empty.

func (R) IsError 

func (w R) IsError() bool

IsError checks whether there is an error present in the `wrapper` instance.

This function returns `true` if the `wrapper` contains an error, which can be any of the following:

  • An error present in the `errors` field.
  • A client error (4xx status code) or a server error (5xx status code).

Returns:

  • A boolean value indicating whether there is an error:
  • `true` if there is an error present, either in the `errors` field or as an HTTP client/server error.
  • `false` if no error is found.

func (R) IsErrorPresent 

func (w R) IsErrorPresent() bool

IsErrorPresent checks whether an error is present in the `wrapper` instance.

This function checks if the `errors` field of the `wrapper` is not nil, indicating that an error has occurred.

Returns:

  • A boolean value indicating whether an error is present:
  • `true` if `errors` is not nil.
  • `false` if `errors` is nil.

func (R) IsHeaderPresent 

func (w R) IsHeaderPresent() bool

IsHeaderPresent checks whether header information is present in the `wrapper` instance.

This function checks if the `header` field of the `wrapper` is not nil, indicating that header information is included.

Returns:

  • A boolean value indicating whether header information is present:
  • `true` if `header` is not nil.
  • `false` if `header` is nil.

func (R) IsInformational 

func (w R) IsInformational() bool

IsInformational checks whether the HTTP status code indicates an informational response.

This function checks if the `statusCode` is between 100 and 199, inclusive, which indicates an informational HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is informational:
  • `true` if the status code is between 100 and 199 (inclusive).
  • `false` if the status code is outside of this range.

func (R) IsJSONBody 

func (w R) IsJSONBody() bool

IsJSONBody checks whether the body data is a valid JSON string.

This function first checks if the `wrapper` is available and if the body data is present using `IsBodyPresent()`. Then it uses the `JSON()` function to retrieve the body data as a JSON string and checks if it is valid using `fj.IsValidJSON()`.

Returns:

  • A boolean value indicating whether the body data is a valid JSON string:
  • `true` if the `wrapper` is available, the body data is present, and the body data is a valid JSON string.
  • `false` if the `wrapper` is not available, the body data is not present, or the body data is not a valid JSON string.

func (R) IsLastPage 

func (w R) IsLastPage() bool

IsLastPage checks whether the current page is the last page of results.

This function verifies that pagination information is present and then checks if the current page is the last page. It combines the checks of `IsPagingPresent()` and `IsLast()` to ensure that the pagination structure exists and that it represents the last page.

Returns:

  • A boolean value indicating whether the current page is the last page:
  • `true` if pagination is present and the current page is the last one.
  • `false` if pagination is not present or the current page is not the last.

func (R) IsMetaPresent 

func (w R) IsMetaPresent() bool

IsMetaPresent checks whether metadata information is present in the `wrapper` instance.

This function checks if the `meta` field of the `wrapper` is not nil, indicating that metadata is available.

Returns:

  • A boolean value indicating whether metadata is present:
  • `true` if `meta` is not nil.
  • `false` if `meta` is nil.

func (R) IsPagingPresent 

func (w R) IsPagingPresent() bool

IsPagingPresent checks whether pagination information is present in the `wrapper` instance.

This function checks if the `pagination` field of the `wrapper` is not nil, indicating that pagination details are included.

Returns:

  • A boolean value indicating whether pagination information is present:
  • `true` if `pagination` is not nil.
  • `false` if `pagination` is nil.

func (R) IsRedirection 

func (w R) IsRedirection() bool

IsRedirection checks whether the HTTP status code indicates a redirection response.

This function checks if the `statusCode` is between 300 and 399, inclusive, which indicates a redirection HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a redirection:
  • `true` if the status code is between 300 and 399 (inclusive).
  • `false` if the status code is outside of this range.

func (R) IsServerError 

func (w R) IsServerError() bool

IsServerError checks whether the HTTP status code indicates a server error.

This function checks if the `statusCode` is between 500 and 599, inclusive, which indicates a server error HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a server error:
  • `true` if the status code is between 500 and 599 (inclusive).
  • `false` if the status code is outside of this range.

func (R) IsStatusCodePresent 

func (w R) IsStatusCodePresent() bool

IsStatusCodePresent checks whether a valid status code is present in the `wrapper` instance.

This function checks if the `statusCode` field of the `wrapper` is greater than 0, indicating that a valid HTTP status code has been set.

Returns:

  • A boolean value indicating whether the status code is present:
  • `true` if `statusCode` is greater than 0.
  • `false` if `statusCode` is less than or equal to 0.

func (R) IsSuccess 

func (w R) IsSuccess() bool

IsSuccess checks whether the HTTP status code indicates a successful response.

This function checks if the `statusCode` is between 200 and 299, inclusive, which indicates a successful HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response was successful:
  • `true` if the status code is between 200 and 299 (inclusive).
  • `false` if the status code is outside of this range.

func (R) IsTotalPresent 

func (w R) IsTotalPresent() bool

IsTotalPresent checks whether the total number of items is present in the `wrapper` instance.

This function checks if the `total` field of the `wrapper` is greater than or equal to 0, indicating that a valid total number of items has been set.

Returns:

  • A boolean value indicating whether the total is present:
  • `true` if `total` is greater than or equal to 0.
  • `false` if `total` is negative (indicating no total value).

func (R) JSON 

func (w R) JSON() string

JSON serializes the `wrapper` instance into a compact JSON string.

This function uses the `encoding.JSON` utility to generate a JSON representation of the `wrapper` instance. The output is a compact JSON string with no additional whitespace or formatting.

Returns:

  • A compact JSON string representation of the `wrapper` instance.

func (R) JSONBodyContains 

func (w R) JSONBodyContains(path, target string) bool

JSONBodyContains reports whether the value at the given path inside the body contains the target substring (case-sensitive).

Returns false when the path does not exist.

Example: 

w.JSONBodyContains("user.role", "admin")

func (R) JSONBodyContainsMatch 

func (w R) JSONBodyContainsMatch(path, pattern string) bool

JSONBodyContainsMatch reports whether the value at the given path inside the body matches the given wildcard pattern.

Returns false when the path does not exist.

Example: 

w.JSONBodyContainsMatch("user.email", "*@example.com")

func (R) JSONBodyParser 

func (w R) JSONBodyParser() fj.Context

JSONBodyParser parses the body of the wrapper as JSON and returns a fj.Context for the entire document. This is the entry point for all fj-based operations on the wrapper.

If the body is nil or cannot be serialized, a zero-value fj.Context is returned. Callers can check presence with ctx.Exists().

Example: 

ctx := w.JSONBodyParser()
fmt.Println(ctx.Get("user.name").String())

func (R) JSONBytes 

func (w R) JSONBytes() []byte

JSONBytes serializes the `wrapper` instance into a JSON byte slice.

This function first checks if the `wrapper` is available and if the body data is a valid JSON string using `IsJSONBody()`. If both conditions are met, it returns the JSON byte slice. Otherwise, it returns an empty byte slice.

Returns:

  • A byte slice containing the JSON representation of the `wrapper` instance.
  • An empty byte slice if the `wrapper` is not available or the body data is not a valid JSON string.

func (R) JSONDebugging 

func (w R) JSONDebugging() string

JSONDebugging retrieves the debugging information from the `wrapper` instance as a JSON string.

This function checks if the `wrapper` instance is available (non-nil) before returning the value of the `debug` field as a JSON string. If the `wrapper` is not available, it returns an empty string to ensure safe usage.

Returns:

  • A `string` containing the debugging information as a JSON string.
  • An empty string if the `wrapper` instance is not available.

func (R) JSONDebuggingBool 

func (w R) JSONDebuggingBool(path string, defaultValue bool) bool

JSONDebuggingBool retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A boolean value to return if the key is not available.

Returns:

  • The boolean value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingDuration 

func (w R) JSONDebuggingDuration(path string, defaultValue time.Duration) time.Duration

JSONDebuggingDuration retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Duration value to return if the key is not available.

Returns:

  • The time.Duration value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingFloat32 

func (w R) JSONDebuggingFloat32(path string, defaultValue float32) float32

JSONDebuggingFloat32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float32 value to return if the key is not available.

Returns:

  • The float32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingFloat64 

func (w R) JSONDebuggingFloat64(path string, defaultValue float64) float64

JSONDebuggingFloat64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float64 value to return if the key is not available.

Returns:

  • The float64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingInt 

func (w R) JSONDebuggingInt(path string, defaultValue int) int

JSONDebuggingInt retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An integer value to return if the key is not available.

Returns:

  • The integer value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingInt8 

func (w R) JSONDebuggingInt8(path string, defaultValue int8) int8

JSONDebuggingInt8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int8 value to return if the key is not available.

Returns:

  • The int8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingInt16 

func (w R) JSONDebuggingInt16(path string, defaultValue int16) int16

JSONDebuggingInt16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int16 value to return if the key is not available.

Returns:

  • The int16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingInt32 

func (w R) JSONDebuggingInt32(path string, defaultValue int32) int32

JSONDebuggingInt32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int32 value to return if the key is not available.

Returns:

  • The int32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingInt64 

func (w R) JSONDebuggingInt64(path string, defaultValue int64) int64

JSONDebuggingInt64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int64 value to return if the key is not available.

Returns:

  • The int64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingString 

func (w R) JSONDebuggingString(path string, defaultValue string) string

JSONDebuggingString retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A string value to return if the key is not available.

Returns:

  • The string value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingTime 

func (w R) JSONDebuggingTime(path string, defaultValue time.Time) time.Time

JSONDebuggingTime retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Time value to return if the key is not available.

Returns:

  • The time.Time value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingUint 

func (w R) JSONDebuggingUint(path string, defaultValue uint) uint

JSONDebuggingUint retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint value to return if the key is not available.

Returns:

  • The uint value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingUint8 

func (w R) JSONDebuggingUint8(path string, defaultValue uint8) uint8

JSONDebuggingUint8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint8 value to return if the key is not available.

Returns:

  • The uint8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingUint16 

func (w R) JSONDebuggingUint16(path string, defaultValue uint16) uint16

JSONDebuggingUint16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint16 value to return if the key is not available.

Returns:

  • The uint16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingUint32 

func (w R) JSONDebuggingUint32(path string, defaultValue uint32) uint32

JSONDebuggingUint32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint32 value to return if the key is not available.

Returns:

  • The uint32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONDebuggingUint64 

func (w R) JSONDebuggingUint64(path string, defaultValue uint64) uint64

JSONDebuggingUint64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint64 value to return if the key is not available.

Returns:

  • The uint64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) JSONPretty 

func (w R) JSONPretty() string

JSONPretty serializes the `wrapper` instance into a prettified JSON string.

This function uses the `encoding.JSONPretty` utility to generate a JSON representation of the `wrapper` instance. The output is a human-readable JSON string with proper indentation and formatting for better readability.

Returns:

  • A prettified JSON string representation of the `wrapper` instance.

func (R) MaxJSONBody 

func (w R) MaxJSONBody(path string) (float64, bool)

MaxJSONBody returns the maximum numeric value at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

v, ok := w.MaxJSONBody("scores")

func (R) Message 

func (w R) Message() string

Message retrieves the message associated with the `wrapper` instance.

This function returns the `message` field of the `wrapper`, which typically provides additional context or a description of the operation's outcome.

Returns:

  • A string representing the message.

func (R) Meta 

func (w R) Meta() *meta

Meta retrieves the `meta` information from the `wrapper` instance.

This function returns the `meta` field, which contains metadata related to the response or data in the `wrapper` instance. If no `meta` information is set, it returns `nil`.

Returns:

  • A pointer to the `meta` instance associated with the `wrapper`.
  • `nil` if no `meta` information is available.

func (R) MinJSONBody 

func (w R) MinJSONBody(path string) (float64, bool)

MinJSONBody returns the minimum numeric value at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

v, ok := w.MinJSONBody("scores")

func (R) MustHash 

func (w R) MustHash() (uint64, *wrapper)

MustHash generates a hash value for the `wrapper` instance.

This method generates a hash value for the `wrapper` instance using the `MustHash` method. If the `wrapper` instance is not available or the hash generation fails, it returns an error.

Returns:

  • A uint64 representing the hash value.
  • An error if the `wrapper` instance is not available or the hash generation fails.

func (R) MustHash256 

func (w R) MustHash256() (string, *wrapper)

MustHash256 generates a hash string for the `wrapper` instance.

This method concatenates the values of the `statusCode`, `message`, `data`, and `meta` fields into a single string and then computes a hash of that string using the `strutil.MustHash256` function. The resulting hash string can be used for various purposes, such as caching or integrity checks.

func (R) NormAll 

func (w R) NormAll() *wrapper

NormAll performs a comprehensive normalization of the wrapper instance.

It sequentially calls the following normalization methods:

  • NormHSC
  • NormPaging
  • NormMeta
  • NormBody
  • NormMessage

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormBody 

func (w R) NormBody() *wrapper

NormBody normalizes the data/body field in the wrapper.

This method ensures that the data field is properly handled:

  • If data is nil and status code indicates success with content, logs a warning (optional)
  • Validates that data type is consistent with the response type
  • For list/array responses, ensures total count is synchronized

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormDebug 

func (w R) NormDebug() *wrapper

NormDebug normalizes the debug information in the wrapper.

This method removes any debug entries that have nil values to ensure the debug map only contains meaningful information.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormHSC 

func (w R) NormHSC() *wrapper

NormHSC normalizes the relationship between the header and status code.

If the status code is not present but the header is, it sets the status code from the header's code. If the header is not present but the status code is, it creates a new header with the status code and its corresponding text.

If both the status code and header are present, it ensures the status code matches the header's code.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormMessage 

func (w R) NormMessage() *wrapper

NormMessage normalizes the message field in the wrapper.

If the message is empty and a status code is present, it sets a default message based on the status code category (success, redirection, client error, server error).

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormMeta 

func (w R) NormMeta() *wrapper

NormMeta normalizes the metadata in the wrapper.

If the meta object is not already initialized, it creates a new one using the `Meta` function. It then ensures that essential fields such as locale, API version, request ID, and requested time are set to default values if they are not already present.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) NormPaging 

func (w R) NormPaging() *wrapper

NormPaging normalizes the pagination information in the wrapper.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. It then calls the `Normalize` method on the pagination instance to ensure its values are consistent.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) OnDebugging 

func (w R) OnDebugging(key string) any

OnDebugging retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `nil` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.

Returns:

  • The value associated with the specified debugging key if it exists.
  • `nil` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (R) Pagination 

func (w R) Pagination() *pagination

Pagination retrieves the `pagination` instance associated with the `wrapper`.

This function returns the `pagination` field of the `wrapper`, allowing access to pagination details such as the current page, total pages, and total items. If no pagination information is available, it returns `nil`.

Returns:

  • A pointer to the `pagination` instance if available.
  • `nil` if the `pagination` field is not set.

func (R) PluckJSONBody 

func (w R) PluckJSONBody(path string, fields ...string) []fj.Context

PluckJSONBody evaluates the given path in the body (expected: array of objects) and returns a new object for each element containing only the specified fields.

Example: 

rows := w.PluckJSONBody("users", "id", "email")

func (R) QueryJSONBody 

func (w R) QueryJSONBody(path string) fj.Context

QueryJSONBody retrieves the value at the given fj dot-notation path from the wrapper's body. The body is serialized to JSON on each call; for repeated queries on the same body, use BodyCtx() once and chain calls on the returned Context.

Parameters:

  • path: A fj dot-notation path (e.g. "user.name", "items.#.id", "roles.0").

Returns:

  • A fj.Context for the matched value. Call .Exists() to check presence.

Example: 

name := w.QueryJSONBody("user.name").String()

func (R) QueryJSONBodyMulti 

func (w R) QueryJSONBodyMulti(paths ...string) []fj.Context

QueryJSONBodyMulti evaluates multiple fj paths against the body in a single pass and returns one fj.Context per path in the same order.

Parameters:

  • paths: One or more fj dot-notation paths.

Returns:

  • A slice of fj.Context values, one per path.

Example: 

results := w.QueryJSONBodyMulti("user.id", "user.email", "roles.#")

func (R) RandDeltaValue 

func (w R) RandDeltaValue() *wrapper

RandDeltaValue generates and sets a random delta value in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `RandDeltaValue` method on the `meta` instance to generate and set a random delta value.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) RandRequestID 

func (w R) RandRequestID() *wrapper

RandRequestID generates and sets a random request ID in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `RandRequestID` method on the `meta` instance to generate and set a random request ID.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) Reply 

func (w R) Reply() R

R represents a wrapper around the main `wrapper` struct. It is used as a high-level abstraction to provide a simplified interface for handling API responses. The `R` type allows for easier manipulation of the wrapped data, metadata, and other response components, while maintaining the flexibility of the underlying `wrapper` structure.

Example usage: 

var response replify.R = replify.New().Reply()
fmt.Println(response.JSON())  // Prints the wrapped response details, including data, headers, and metadata.

func (R) ReplyPtr 

func (w R) ReplyPtr() *R

ReplyPtr returns a pointer to a new R instance that wraps the current `wrapper`.

This method creates a new `R` struct, initializing it with the current `wrapper` instance, and returns a pointer to this new `R` instance. This allows for easier manipulation of the wrapped data and metadata through the `R` abstraction.

Returns:

  • A pointer to an `R` struct that wraps the current `wrapper` instance.

Example usage: 

var responsePtr *replify.R = replify.New().ReplyPtr()
fmt.Println(responsePtr.JSON())  // Prints the wrapped response details, including data, headers, and metadata.

func (R) Reset 

func (w R) Reset() *wrapper

Reset resets the `wrapper` instance to its initial state.

This function sets the `wrapper` instance to its initial state by resetting the `statusCode`, `total`, `message`, `path`, `cacheHash`, `data`, `debug`, `header`, `errors`, `pagination`, and `cachedWrap` fields to their default values. It also resets the `meta` instance to its initial state.

Returns:

  • A pointer to the reset `wrapper` instance.
  • `nil` if the `wrapper` instance is not available.

func (R) Respond 

func (w R) Respond() map[string]any

Respond generates a map representation of the `wrapper` instance.

This method collects various fields of the `wrapper` (e.g., `data`, `header`, `meta`, etc.) and organizes them into a key-value map. Only non-nil or meaningful fields are added to the resulting map to ensure a clean and concise response structure.

Fields included in the response:

  • `data`: The primary data payload, if present.
  • `headers`: The structured header details, if present.
  • `meta`: Metadata about the response, if present.
  • `pagination`: Pagination details, if applicable.
  • `debug`: Debugging information, if provided.
  • `total`: Total number of items, if set to a valid non-negative value.
  • `status_code`: The HTTP status code, if greater than 0.
  • `message`: A descriptive message, if not empty.
  • `path`: The request path, if not empty.

Returns:

  • A `map[string]interface{}` containing the structured response data.

func (R) SearchJSONBody 

func (w R) SearchJSONBody(keyword string) []fj.Context

SearchJSONBody performs a full-tree scan of the body JSON and returns all scalar leaf values whose string representation contains the given keyword (case-sensitive substring match).

Parameters:

  • keyword: The substring to search for. An empty keyword matches every leaf.

Returns:

  • A slice of fj.Context values whose string representation contains keyword.

Example: 

hits := w.SearchJSONBody("admin")
for _, h := range hits {
    fmt.Println(h.String())
}

func (R) SearchJSONBodyByKey 

func (w R) SearchJSONBodyByKey(keys ...string) []fj.Context

SearchJSONBodyByKey performs a full-tree scan of the body JSON and returns all values stored under any of the given key names, regardless of nesting depth.

Parameters:

  • keys: One or more exact object key names to look up.

Example: 

emails := w.SearchJSONBodyByKey("email")

func (R) SearchJSONBodyByKeyPattern 

func (w R) SearchJSONBodyByKeyPattern(keyPattern string) []fj.Context

SearchJSONBodyByKeyPattern performs a full-tree wildcard scan of the body JSON and returns all values stored under object keys that match the given pattern.

Parameters:

  • keyPattern: A wildcard pattern applied to object key names.

Example: 

hits := w.SearchJSONBodyByKeyPattern("user*")

func (R) SearchJSONBodyMatch 

func (w R) SearchJSONBodyMatch(pattern string) []fj.Context

SearchJSONBodyMatch performs a full-tree wildcard scan of the body JSON and returns all scalar leaf values whose string representation matches the given pattern.

The pattern supports '*' (any sequence) and '?' (single character) wildcards.

Parameters:

  • pattern: A wildcard pattern applied to leaf string values.

Example: 

hits := w.SearchJSONBodyMatch("admin*")

func (R) SortJSONBody 

func (w R) SortJSONBody(path, keyField string, ascending bool) []fj.Context

SortJSONBody sorts the elements at the given path in the body by the value of keyField. Numeric fields are compared as float64; all others fall back to string comparison.

Parameters:

  • path: A fj path resolving to an array.
  • keyField: The field to sort by. Pass "" to sort scalar arrays.
  • ascending: Sort direction.

Example: 

sorted := w.SortJSONBody("products", "price", true)

func (R) StatusCode 

func (w R) StatusCode() int

StatusCode retrieves the HTTP status code associated with the `wrapper` instance.

This function returns the `statusCode` field of the `wrapper`, which represents the HTTP status code for the response, indicating the outcome of the request.

Returns:

  • An integer representing the HTTP status code.

func (R) StatusText 

func (w R) StatusText() string

StatusText returns a human-readable string representation of the HTTP status.

This function combines the status code with its associated status text, which is retrieved using the `http.StatusText` function from the `net/http` package. The returned string follows the format "statusCode (statusText)".

For example, if the status code is 200, the function will return "200 (OK)". If the status code is 404, it will return "404 (Not Found)".

Returns:

  • A string formatted as "statusCode (statusText)", where `statusCode` is the numeric HTTP status code and `statusText` is the corresponding textual description.

func (R) Stream 

func (w R) Stream() <-chan []byte

Stream retrieves a channel that streams the body data of the `wrapper` instance.

This function checks if the body data is present and, if so, streams the data in chunks. It creates a buffered channel to hold the streamed data, allowing for asynchronous processing of the response body. If the body is not present, it returns an empty channel. The streaming is done in a separate goroutine to avoid blocking the main execution flow. The body data is chunked into smaller parts using the `Chunk` function, which splits the response data into manageable segments for efficient streaming.

Returns:

  • A channel of byte slices that streams the body data.
  • An empty channel if the body data is not present.

This is useful for handling large responses in a memory-efficient manner, allowing the consumer to process each chunk as it becomes available. Note: The channel is closed automatically when the streaming is complete. If the body is not present, it returns an empty channel.

func (R) SumJSONBody 

func (w R) SumJSONBody(path string) float64

SumJSONBody returns the sum of all numeric values at the given path in the body. Non-numeric elements are ignored. Returns 0 when no numbers are found.

Example: 

total := w.SumJSONBody("items.#.price")

func (R) Total 

func (w R) Total() int

Total retrieves the total number of items associated with the `wrapper` instance.

This function returns the `total` field of the `wrapper`, which indicates the total number of items available, often used in paginated responses.

Returns:

  • An integer representing the total number of items.

func (R) ValidJSONBody 

func (w R) ValidJSONBody() bool

ValidJSONBody reports whether the body of the wrapper is valid JSON.

Returns:

  • true if the body serializes to well-formed JSON; false otherwise.

Example: 

if !w.ValidJSONBody() {
    log.Println("body is not valid JSON")
}

func (R) WithApiVersion 

func (w R) WithApiVersion(v string) *wrapper

WithApiVersion sets the API version in the `meta` field of the `wrapper` instance.

This function checks if the `meta` information is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `WithApiVersion` method on the `meta` instance to set the API version.

Parameters:

  • `v`: A string representing the API version to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithApiVersionf 

func (w R) WithApiVersionf(format string, args ...any) *wrapper

WithApiVersionf sets the API version in the `meta` field of the `wrapper` instance using a formatted string.

This function ensures that the `meta` field in the `wrapper` is initialized. If the `meta` field is not present, a new `meta` instance is created using the `NewMeta` function. Once the `meta` instance is ready, it updates the API version using the `WithApiVersionf` method on the `meta` instance. The API version is constructed by interpolating the provided `format` string with the variadic arguments (`args`).

Parameters:

  • format: A format string used to construct the API version.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (R) WithBody 

func (w R) WithBody(v any) *wrapper

WithBody sets the body data for the `wrapper` instance.

This function updates the `data` field of the `wrapper` with the provided value and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: The value to be set as the body data, which can be any type.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

Example: 

w, err := replify.New().WithBody(myStruct)

Notes:

  • This function does not validate or normalize the input value.
  • It simply assigns the value to the `data` field of the `wrapper`.
  • The value will be marshalled to JSON when the `wrapper` is converted to a string.
  • Consider using WithJSONBody instead if you need to normalize the input value.

func (R) WithCustomFieldKV 

func (w R) WithCustomFieldKV(key string, value any) *wrapper

WithCustomFieldKV sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance.

This function ensures that if the `meta` field is not already set, a new `meta` instance is created. It then adds the provided key-value pair to the custom fields of `meta` using the `WithCustomFieldKV` method.

Parameters:

  • `key`: A string representing the custom field key to set.
  • `value`: The value associated with the custom field key.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithCustomFieldKVf 

func (w R) WithCustomFieldKVf(key string, format string, args ...any) *wrapper

WithCustomFieldKVf sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance using a formatted value.

This function constructs a formatted string value using the provided `format` string and arguments (`args`). It then calls the `WithCustomFieldKV` method to add or update the custom field with the specified key and the formatted value. If the `meta` field of the `wrapper` instance is not initialized, it is created before setting the custom field.

Parameters:

  • key: A string representing the key for the custom field.
  • format: A format string to construct the value.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (R) WithCustomFields 

func (w R) WithCustomFields(values map[string]any) *wrapper

WithCustomFields sets the custom fields in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present. If not, it creates a new `meta` instance and sets the provided custom fields using the `WithCustomFields` method.

Parameters:

  • `values`: A map representing the custom fields to set in the `meta`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithDebugging 

func (w R) WithDebugging(v map[string]any) *wrapper

WithDebugging sets the debugging information for the `wrapper` instance.

This function updates the `debug` field of the `wrapper` with the provided map of debugging data and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A map containing debugging information to be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithDebuggingKV 

func (w R) WithDebuggingKV(key string, value any) *wrapper

WithDebuggingKV adds a key-value pair to the debugging information in the `wrapper` instance.

This function checks if debugging information is already present. If it is not, it initializes an empty map. Then it adds the given key-value pair to the `debug` map and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `key`: The key for the debugging information to be added.
  • `value`: The value associated with the key to be added to the `debug` map.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithDebuggingKVf 

func (w R) WithDebuggingKVf(key string, format string, args ...any) *wrapper

WithDebuggingKVf adds a formatted key-value pair to the debugging information in the `wrapper` instance.

This function creates a formatted string value using the provided `format` string and `args`, then delegates to `WithDebuggingKV` to add the resulting key-value pair to the `debug` map. It returns the modified `wrapper` instance for method chaining.

Parameters:

  • key: A string representing the key for the debugging information.
  • format: A format string for constructing the value.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (R) WithError 

func (w R) WithError(message string) *wrapper

WithError sets an error for the `wrapper` instance using a plain error message.

This function creates an error object from the provided message, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • message: A string containing the error message to be wrapped as an error object.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) WithErrorAck 

func (w R) WithErrorAck(err error) *wrapper

WithErrorAck sets an error with a stack trace for the `wrapper` instance.

This function wraps the provided error with stack trace information, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • err: The error object to be wrapped with stack trace information.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) WithErrorAckf 

func (w R) WithErrorAckf(err error, format string, args ...any) *wrapper

WithErrorAckf wraps an existing error with a formatted message and sets it for the `wrapper` instance.

This function adds context to the provided error by wrapping it with a formatted message. The resulting error is assigned to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • format: A format string for constructing the contextual error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) WithErrorf 

func (w R) WithErrorf(format string, args ...any) *wrapper

WithErrorf sets a formatted error for the `wrapper` instance.

This function uses a formatted string and arguments to construct an error object, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • format: A format string for constructing the error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (R) WithHeader 

func (w R) WithHeader(v *header) *wrapper

WithHeader sets the header for the `wrapper` instance.

This function updates the `header` field of the `wrapper` with the provided `header` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `header` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithIsLast 

func (w R) WithIsLast(v bool) *wrapper

WithIsLast sets whether the current page is the last one in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified boolean value is then applied to indicate whether the current page is the last.

Parameters:

  • v: A boolean indicating whether the current page is the last.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) WithJSONBody 

func (w R) WithJSONBody(v any) (*wrapper, error)

WithJSONBody normalizes the input value and sets it as the body data for the `wrapper` instance.

The method accepts any Go value and handles it according to its dynamic type:

  • string – the string is passed through encoding.NormalizeJSON, which strips common JSON corruption artifacts (BOM, null bytes, escaped structural quotes, trailing commas) before setting the result as the body.
  • []byte – treated as a raw string; the same NormalizeJSON pipeline is applied after converting to string.
  • json.RawMessage – validated directly; if invalid, an error is returned.
  • any other type – marshaled to JSON via encoding.JSONToken and set as the body, which is by definition already valid JSON.
  • nil – returns an error; nil cannot be normalized.

If normalization succeeds, the cleaned value is stored as the body and the method returns the updated wrapper and nil. If it fails, the body is left unchanged and a descriptive error is returned.

Parameters:

  • v: The value to normalize and set as the body.

Returns:

  • A pointer to the modified `wrapper` instance and nil on success.
  • The unchanged `wrapper` instance and an error if normalization fails.

Example: 

// From a raw-string with escaped structural quotes:
w, err := replify.New().WithJSONBody(`{\"key\": "value"}`)

// From a struct:
w, err := replify.New().WithJSONBody(myStruct)

func (R) WithLocale 

func (w R) WithLocale(v string) *wrapper

WithLocale sets the locale in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and sets the locale in the `meta` using the `WithLocale` method.

Parameters:

  • `v`: A string representing the locale to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithMessage 

func (w R) WithMessage(message string) *wrapper

WithMessage sets a message for the `wrapper` instance.

This function updates the `message` field of the `wrapper` with the provided string and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `message`: A string message to be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithMessagef 

func (w R) WithMessagef(message string, args ...any) *wrapper

WithMessagef sets a formatted message for the `wrapper` instance.

This function constructs a formatted string using the provided format string and arguments, assigns it to the `message` field of the `wrapper`, and returns the modified instance.

Parameters:

  • message: A format string for constructing the message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (R) WithMeta 

func (w R) WithMeta(v *meta) *wrapper

WithMeta sets the metadata for the `wrapper` instance.

This function updates the `meta` field of the `wrapper` with the provided `meta` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `meta` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithPage 

func (w R) WithPage(v int) *wrapper

WithPage sets the current page number in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified page number is then applied to the pagination instance.

Parameters:

  • v: The page number to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) WithPagination 

func (w R) WithPagination(v *pagination) *wrapper

WithPagination sets the pagination information for the `wrapper` instance.

This function updates the `pagination` field of the `wrapper` with the provided `pagination` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `pagination` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithPath 

func (w R) WithPath(v string) *wrapper

WithPath sets the request path for the `wrapper` instance.

This function updates the `path` field of the `wrapper` with the provided string and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A string representing the request path.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithPathf 

func (w R) WithPathf(v string, args ...any) *wrapper

WithPathf sets a formatted request path for the `wrapper` instance.

This function constructs a formatted string using the provided format string `v` and arguments `args`, assigns the resulting string to the `path` field of the `wrapper`, and returns the modified instance.

Parameters:

  • v: A format string for constructing the request path.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (R) WithPerPage 

func (w R) WithPerPage(v int) *wrapper

WithPerPage sets the number of items per page in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified items-per-page value is then applied to the pagination instance.

Parameters:

  • v: The number of items per page to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) WithRequestID 

func (w R) WithRequestID(v string) *wrapper

WithRequestID sets the request ID in the `meta` field of the `wrapper` instance.

This function ensures that if `meta` information is not already set in the `wrapper`, a new `meta` instance is created. Then, it calls the `WithRequestID` method on the `meta` instance to set the request ID.

Parameters:

  • `v`: A string representing the request ID to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithRequestIDf 

func (w R) WithRequestIDf(format string, args ...any) *wrapper

WithRequestIDf sets the request ID in the `meta` field of the `wrapper` instance using a formatted string.

This function ensures that the `meta` field in the `wrapper` is initialized. If the `meta` field is not already present, a new `meta` instance is created using the `NewMeta` function. Once the `meta` instance is ready, it updates the request ID by calling the `WithRequestIDf` method on the `meta` instance. The request ID is constructed using the provided `format` string and the variadic `args`.

Parameters:

  • format: A format string used to construct the request ID.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, allowing for method chaining.

func (R) WithRequestedTime 

func (w R) WithRequestedTime(v time.Time) *wrapper

WithRequestedTime sets the requested time in the `meta` field of the `wrapper` instance.

This function ensures that the `meta` field exists, and if not, creates a new one. It then sets the requested time in the `meta` using the `WithRequestedTime` method.

Parameters:

  • `v`: A `time.Time` value representing the requested time.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithStatusCode 

func (w R) WithStatusCode(code int) *wrapper

WithStatusCode sets the HTTP status code for the `wrapper` instance. Ensure that code is between 100 and 599, defaults to 500 if invalid value.

This function updates the `statusCode` field of the `wrapper` and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `code`: An integer representing the HTTP status code to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithStreaming 

func (w R) WithStreaming(reader io.Reader, config *StreamConfig) *StreamingWrapper

WithStreaming enables streaming mode for the wrapper and returns a streaming wrapper for enhanced data transfer capabilities.

This function is the primary entry point for activating streaming functionality on an existing wrapper instance. It creates a new StreamingWrapper that preserves the metadata and context of the original wrapper while adding streaming-specific features such as chunk-based transfer, compression, progress tracking, and bandwidth throttling. The returned StreamingWrapper allows for method chaining to configure streaming parameters before initiating transfer.

Parameters:

  • reader: An io.Reader implementation providing the source data stream (e.g., *os.File, *http.Response.Body, *bytes.Buffer). Cannot be nil; streaming will fail if no valid reader is provided.
  • config: A *StreamConfig containing streaming configuration options (chunk size, compression, strategy, concurrency). If nil, a default configuration is automatically created with sensible defaults:
  • ChunkSize: 65536 bytes (64KB)
  • Strategy: STRATEGY_BUFFERED (balanced throughput and memory)
  • Compression: COMP_NONE
  • MaxConcurrentChunks: 4

Returns:

  • A pointer to a new StreamingWrapper instance that wraps the original wrapper.
  • The StreamingWrapper preserves all metadata from the original wrapper.
  • If the receiver wrapper is nil, creates a new default wrapper before enabling streaming.
  • The returned StreamingWrapper can be chained with configuration methods before calling Start().

Example: 

file, _ := os.Open("large_file.bin")
defer file.Close()

// Simple streaming with defaults
result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Transferred: %.2f MB / %.2f MB\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TotalBytes) / 1024 / 1024)
        }
    }).
    Start(context.Background()).
    WithMessage("File transfer completed")

See Also:

  • AsStreaming: Simplified version with default configuration
  • Start: Initiates the streaming operation
  • WithChunkSize: Configures chunk size
  • WithCompressionType: Enables data compression

func (R) WithTotal 

func (w R) WithTotal(total int) *wrapper

WithTotal sets the total number of items for the `wrapper` instance.

This function updates the `total` field of the `wrapper` and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `total`: An integer representing the total number of items to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (R) WithTotalItems 

func (w R) WithTotalItems(v int) *wrapper

WithTotalItems sets the total number of items in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified total items value is then applied to the pagination instance.

Parameters:

  • v: The total number of items to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (R) WithTotalPages 

func (w R) WithTotalPages(v int) *wrapper

WithTotalPages sets the total number of pages in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified total pages value is then applied to the pagination instance.

Parameters:

  • v: The total number of pages to set.

Returns:

  • A pointer to the updated `wrapper` instance.

type StackTrace 

type StackTrace []Frame

StackTrace represents a stack of Frames, which are ordered from the innermost (newest) function call to the outermost (oldest) function call in the current stack. It provides a high-level representation of the sequence of function calls (the call stack) that led to the current execution point, typically used for debugging or error reporting. The `StackTrace` contains a slice of `Frame` values, which can be interpreted as program counters in the call stack.

The `StackTrace` can be used to generate detailed stack traces when an error occurs, helping developers track down the sequence of function calls that resulted in the error. For example, it may be used in conjunction with the `underlying` and `underlyingStack` types to record where an error occurred in the code (using `Callers()` to populate the stack) and provide information on the call path leading to the error.

Example usage: 

var trace StackTrace = StackTrace{Frame(0x1234567890), Frame(0x0987654321)}
fmt.Println(trace) // Prints the stack trace with the frames

func (StackTrace) Format 

func (st StackTrace) Format(s fmt.State, verb rune)

StackTrace.Format formats the stack trace according to the fmt.Formatter interface.

Usage: The `verb` parameter controls the formatting output:

  • %s: Lists source files for each Frame in the stack.
  • %v: Lists source file and line number for each Frame in the stack.

Flags:

  • %+v: Prints filename, function name, and line number for each Frame.

Example: 

trace := StackTrace{frame1, frame2}
fmt.Printf("%+v", trace)

type StreamChunk 

type StreamChunk struct {
	// SequenceNumber incremental chunk number
	SequenceNumber int64 `json:"sequence_number"`

	// Data chunk content
	Data []byte `json:"-"`

	// Size of chunk
	Size int64 `json:"size"`

	// Checksum for integrity verification
	Checksum uint32 `json:"checksum"`

	// Timestamp when chunk was created
	Timestamp time.Time `json:"timestamp,omitempty"`

	// Compressed indicates if chunk is compressed
	Compressed bool `json:"compressed"`

	// CompressionType used for this chunk
	CompressionType CompressionType `json:"compression_type"`

	// Error if any occurred during chunk processing
	Error error `json:"-"`
}

StreamChunk represents a single chunk of data in a streaming operation.

type StreamConfig 

type StreamConfig struct {
	// ChunkSize defines size of each chunk in bytes (default: 64KB)
	ChunkSize int64 `json:"chunk_size"`

	// IsReceiving indicates if streaming is for receiving data
	// true if receiving data (decompress incoming), false if sending (compress outgoing)
	// it's used to determine direction of data flow
	IsReceiving bool `json:"is_receiving"`

	// Strategy for streaming (direct, buffered, chunked)
	Strategy StreamingStrategy `json:"strategy"`

	// Compression algorithm to use during streaming
	Compression CompressionType `json:"compression"`

	// UseBufferPool enables buffer pooling for efficiency
	UseBufferPool bool `json:"use_buffer_pool"`

	// MaxConcurrentChunks for parallel processing
	MaxConcurrentChunks int `json:"max_concurrent_chunks"`

	// ReadTimeout for read operations
	ReadTimeout time.Duration `json:"read_timeout,omitempty"`

	// WriteTimeout for write operations
	WriteTimeout time.Duration `json:"write_timeout,omitempty"`

	// ThrottleRate in bytes/second (0 = unlimited)
	// to limit bandwidth usage during streaming
	// useful for avoiding network congestion
	ThrottleRate int64 `json:"throttle_rate"`
}

StreamConfig contains streaming configuration options for handling large data transfers.

func NewStreamConfig 

func NewStreamConfig() *StreamConfig

NewStreamConfig creates default streaming configuration

This function initializes a `StreamConfig` struct with default values suitable for typical streaming scenarios.

Returns:

  • A pointer to a newly created `StreamConfig` instance with default settings.

func (*StreamConfig) JSON 

func (s *StreamConfig) JSON() string

JSON returns the JSON representation of the StreamConfig. This method serializes the StreamConfig struct into a JSON string using the encoding.JSON function.

type StreamProgress 

type StreamProgress struct {
	// TotalBytes total data to be streamed
	TotalBytes int64 `json:"total_bytes"`

	// TransferredBytes bytes transferred so far
	TransferredBytes int64 `json:"transferred_bytes"`

	// Percentage completion (0-100)
	Percentage int `json:"percentage"`

	// CurrentChunk chunk number being processed
	CurrentChunk int64 `json:"current_chunk"`

	// TotalChunks total number of chunks
	TotalChunks int64 `json:"total_chunks"`

	// ElapsedTime time since streaming started
	ElapsedTime time.Duration `json:"elapsed_time,omitempty"`

	// EstimatedTimeRemaining estimated time until completion
	EstimatedTimeRemaining time.Duration `json:"estimated_time_remaining,omitempty"`

	// TransferRate bytes per second
	TransferRate int64 `json:"transfer_rate"`

	// LastUpdate time of last progress update
	LastUpdate time.Time `json:"last_update,omitempty"`
}

StreamProgress tracks streaming progress and statistics.

func (*StreamProgress) JSON 

func (s *StreamProgress) JSON() string

JSON returns the JSON representation of the StreamProgress. This method serializes the StreamProgress struct into a JSON string using the encoding.JSON function.

type StreamingCallback 

type StreamingCallback func(progress *StreamProgress, err error)

StreamingCallback function type for async notifications Streamer interface for streaming data with progress tracking

type StreamingHook 

type StreamingHook func(progress *StreamProgress, wrap *R)

StreamingHook is a function type used for asynchronous notifications that provides updates on the progress of a streaming operation along with a reference to the associated R wrapper. This allows the callback to access both the progress information and any relevant response data encapsulated within the R type.

type StreamingMetadata 

type StreamingMetadata struct {
	// Streaming strategy used
	Strategy StreamingStrategy `json:"strategy"`

	// Compression algorithm used
	CompressionType CompressionType `json:"compression_type"`

	// Size of each chunk in bytes
	ChunkSize int64 `json:"chunk_size"`

	// Total number of chunks
	TotalChunks int64 `json:"total_chunks"`

	// Estimated total size of data
	EstimatedTotalSize int64 `json:"estimated_total_size"`

	// Timestamp when streaming started
	StartedAt time.Time `json:"started_at"`

	// Timestamp when streaming completed
	CompletedAt time.Time `json:"completed_at"`

	// Indicates if streaming can be paused
	IsPausable bool `json:"is_pausable"`

	// Indicates if streaming can be resumed
	IsResumable bool `json:"is_resumable"`
}

StreamingMetadata extends wrapper metadata for streaming context Streamer defines methods for streaming data with progress tracking

type StreamingStats 

type StreamingStats struct {
	// Time when streaming started
	StartTime time.Time `json:"start_time,omitempty"`

	// Time when streaming ended
	EndTime time.Time `json:"end_time,omitempty"`

	// Total bytes processed
	TotalBytes int64 `json:"total_bytes"`

	// Bytes after compression
	CompressedBytes int64 `json:"compressed_bytes"`

	// Compression ratio achieved
	CompressionRatio float64 `json:"compression_ratio"`

	// Average size of each chunk
	AverageChunkSize int64 `json:"average_chunk_size"`

	// Total number of chunks processed
	TotalChunks int64 `json:"total_chunks"`

	// Number of chunks that failed
	FailedChunks int64 `json:"failed_chunks"`

	// Number of chunks that were retried
	RetriedChunks int64 `json:"retried_chunks"`

	// Average latency per chunk
	AverageLatency time.Duration `json:"average_latency,omitempty"`

	// Peak bandwidth observed
	PeakBandwidth int64 `json:"peak_bandwidth"`

	// Average bandwidth during streaming
	AverageBandwidth int64 `json:"average_bandwidth"`

	// List of errors encountered during streaming
	Errors []error `json:"-"`
}

StreamingStats contains streaming statistics and performance metrics.

func (*StreamingStats) JSON 

func (s *StreamingStats) JSON() string

JSON returns the JSON representation of the StreamingStats. This method serializes the StreamingStats struct into a JSON string using the encoding.JSON function.

type StreamingStrategy 

type StreamingStrategy string

StreamingStrategy defines how streaming is performed for large datasets or long-running operations. 

const (
	// Direct streaming without buffering
	// Each piece of data is sent immediately as it becomes available.
	StrategyDirect StreamingStrategy = "direct"

	// Buffered streaming with internal buffer
	// Data is collected in a buffer and sent in larger chunks to optimize performance.
	StrategyBuffered StreamingStrategy = "buffered"

	// Chunked streaming with explicit chunk handling
	// Data is divided into chunks of a specified size and sent sequentially.
	StrategyChunked StreamingStrategy = "chunked"
)

StreamingStrategy defines the strategy used for streaming data. It determines how data is sent or received in a streaming manner.

type StreamingWrapper 

type StreamingWrapper struct {
	// contains filtered or unexported fields
}

StreamingWrapper wraps response with streaming capabilities BufferPool represents a pool of reusable byte buffers to optimize memory usage during streaming.

func NewStreaming 

func NewStreaming(reader io.Reader, config *StreamConfig) *StreamingWrapper

NewStreaming creates a new instance of the `StreamingWrapper` struct.

This function initializes a `StreamingWrapper` struct with the provided `reader`, and `config`. If the `config` is nil, it uses default streaming configuration.

Parameters:

  • `reader`: An `io.Reader` instance from which data will be streamed.
  • `config`: A pointer to a `StreamConfig` struct containing streaming configuration.

Returns:

  • A pointer to a newly created `StreamingWrapper` instance with initialized fields.

func (StreamingWrapper) AppendError 

func (w StreamingWrapper) AppendError(err error, message string) *wrapper

AppendError adds a plain contextual message to an existing error and sets it for the `wrapper` instance.

This function wraps the provided error with an additional plain message and assigns it to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • message: A plain string message to add context to the error.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) AppendErrorAck 

func (w StreamingWrapper) AppendErrorAck(err error, message string) *wrapper

AppendErrorAck wraps an existing error with an additional message and sets it for the `wrapper` instance.

This function adds context to the provided error by wrapping it with an additional message. The resulting error is assigned to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • message: A string message to add context to the error.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) AppendErrorf 

func (w StreamingWrapper) AppendErrorf(err error, format string, args ...any) *wrapper

AppendErrorf adds a formatted contextual message to an existing error and sets it for the `wrapper` instance.

This function wraps the provided error with an additional formatted message and assigns it to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • format: A format string for constructing the contextual error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) AsStreaming 

func (w StreamingWrapper) AsStreaming(reader io.Reader) *StreamingWrapper

AsStreaming converts a regular wrapper instance into a streaming-enabled response with default configuration.

This function provides a simplified, one-line alternative to WithStreaming for common streaming scenarios. It automatically creates a new wrapper if the receiver is nil and applies default streaming configuration, eliminating the need for manual configuration object creation. This is ideal for quick implementations where standard settings (64KB chunks, buffered strategy, no compression) are acceptable.

Parameters:

  • reader: An io.Reader implementation providing the source data stream (e.g., *os.File, *http.Response.Body, *bytes.Buffer). Cannot be nil; streaming will fail if no valid reader is provided.

Returns:

  • A pointer to a new StreamingWrapper instance configured with default settings:
  • ChunkSize: 65536 bytes (64KB)
  • Strategy: STRATEGY_BUFFERED
  • Compression: COMP_NONE
  • MaxConcurrentChunks: 4
  • UseBufferPool: true
  • ReadTimeout: 30 seconds
  • WriteTimeout: 30 seconds
  • If the receiver wrapper is nil, automatically creates a new wrapper before enabling streaming.
  • Returns a StreamingWrapper ready for optional configuration before calling Start().

Example: 

// Minimal streaming setup with defaults - best for simple file downloads
file, _ := os.Open("document.pdf")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/document").
    AsStreaming(file).
    WithTotalBytes(fileSize).
    Start(context.Background())

// Or without creating a new wrapper first
result := (*wrapper)(nil).
    AsStreaming(file).
    Start(context.Background())

Comparison: 

// Using AsStreaming (simple, defaults only)
streaming := response.AsStreaming(reader)

// Using WithStreaming (more control)
streaming := response.WithStreaming(reader, &StreamConfig{
    ChunkSize:           512 * 1024,
    Compression:         COMP_GZIP,
    MaxConcurrentChunks: 8,
})

See Also:

  • WithStreaming: For custom streaming configuration
  • NewStreamConfig: To create custom configuration objects
  • Start: Initiates the streaming operation
  • WithCallback: Adds progress tracking after AsStreaming

func (StreamingWrapper) Available 

func (w StreamingWrapper) Available() bool

Available checks whether the `wrapper` instance is non-nil.

This function ensures that the `wrapper` object exists and is not nil. It serves as a safety check to avoid null pointer dereferences when accessing the instance's fields or methods.

Returns:

  • A boolean value indicating whether the `wrapper` instance is non-nil:
  • `true` if the `wrapper` instance is non-nil.
  • `false` if the `wrapper` instance is nil.

func (StreamingWrapper) AvgJSONBody 

func (w StreamingWrapper) AvgJSONBody(path string) (float64, bool)

AvgJSONBody returns the arithmetic mean of all numeric values at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

avg, ok := w.AvgJSONBody("ratings")

func (StreamingWrapper) BindCause 

func (w StreamingWrapper) BindCause() *wrapper

BindCause sets the error for the `wrapper` instance using its current message.

This function creates an error object from the `message` field of the `wrapper`, assigns it to the `errors` field, and returns the modified instance. It allows for method chaining.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) Body 

func (w StreamingWrapper) Body() any

Body retrieves the body data associated with the `wrapper` instance.

This function returns the `data` field of the `wrapper`, which contains the primary data payload of the response.

Returns:

  • The body data (of any type), or `nil` if no body data is present.

func (*StreamingWrapper) Cancel 

func (sw *StreamingWrapper) Cancel() *wrapper

Cancel terminates an ongoing streaming operation immediately and gracefully.

This function stops the streaming process at the current point, preventing further data transfer. It signals the streaming context to stop all read/write operations, halting chunk processing in progress. The cancellation is thread-safe and can be called from any goroutine while streaming is active. Partial data already transferred to the destination is retained; only new chunk transfers are prevented. This is useful for user-initiated interruptions, resource constraints, or error recovery scenarios where resuming the operation is planned. The cancellation timestamp is recorded for audit and debugging purposes. The underlying resources (readers/writers) remain open and must be explicitly closed via Close() if cleanup is required. Cancel returns the wrapper with updated status for chainable response building.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • The function automatically updates the wrapper with:
  • Message: "Streaming cancelled"
  • Debugging key "cancelled_at": Unix timestamp (seconds since epoch)
  • Status code remains unchanged (use chaining to update if needed).
  • In-flight chunks may complete; no data loss guarantee after cancellation.

Cancellation Behavior: 

State Before Cancel      Behavior During Cancel          State After Cancel
────────────────────────────────────────────────────────────────────────────
Streaming in progress    Context signaled, read blocked   Streaming halted
Chunk in flight          Current chunk may complete       No new chunks read
Paused/stalled           Cancel processed immediately     Operation terminated
Already completed        Cancel is no-op (idempotent)     No effect
Never started            Cancel is no-op (no-op state)    Ready for cleanup
Error state              Cancel processed (cleanup)       Cleanup initiated

Cancellation vs Close: 

Aspect                  Cancel()                Close()
───────────────────────────────────────────────────────────
Stops streaming         Yes (context signal)    Yes (closes streams)
Closes reader/writer    No (remains open)       Yes (calls Close)
Retains partial data    Yes (on destination)    Yes (with cleanup)
Resource cleanup        Partial (context only)  Full (all resources)
Idempotent              Yes (safe to call >1x)  Yes (safe to call >1x)
Use case                Pause/interrupt         Final cleanup
Recommended after       Cancel, then retry      Cancel before exit
Thread-safe             Yes                     Yes
Error handling          None                    Reports close errors
Follow-up action        Can resume (new stream) Must create new stream

Example: 

// Example 1: User-initiated cancellation (pause download)
file, _ := os.Open("large_file.iso")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithCustomFieldKV("user_action", "manual-pause").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Error during transfer: %v\n", err)
            return
        }
        fmt.Printf("Progress: %.1f%%\n", float64(p.Percentage))
    })

// Start streaming in background
go func() {
    streaming.Start(context.Background())
}()

// Simulate user pause after 5 seconds
time.Sleep(5 * time.Second)
result := streaming.Cancel().
    WithMessage("Download paused by user").
    WithStatusCode(202). // 202 Accepted - operation paused

fmt.Printf("Cancelled at: %v\n", result.Debugging())

// Example 2: Resource constraint cancellation (memory pressure)
dataExport := createLargeDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/data").
    WithCustomFieldKV("export_type", "bulk").
    WithStreaming(dataExport, nil).
    WithChunkSize(10 * 1024 * 1024).
    WithMaxConcurrentChunks(8).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            return
        }

        // Monitor system memory
        memStats := getMemoryStats()
        if memStats.HeapAlloc > maxAllowedMemory {
            fmt.Printf("Memory pressure detected: %d MB\n",
                memStats.HeapAlloc / 1024 / 1024)
            // Cancel to prevent OOM
        }
    })

result := streaming.Start(context.Background())

if shouldCancelDueToMemory {
    result = streaming.Cancel().
        WithMessage("Cancelled due to memory pressure").
        WithStatusCode(503). // 503 Service Unavailable
        WithCustomFieldKV("reason", "memory-pressure").
        WithCustomFieldKV("memory_used_mb", currentMemory)
}

// Example 3: Error recovery with cancellation and retry
attempt := 0
maxRetries := 3

for attempt < maxRetries {
    attempt++
    fileReader, _ := os.Open("large_file.bin")
    defer fileReader.Close()

    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/download/retry").
        WithCustomFieldKV("attempt", attempt).
        WithStreaming(fileReader, nil).
        WithChunkSize(512 * 1024).
        WithReadTimeout(10000).
        WithWriteTimeout(10000).
        WithCallback(func(p *StreamProgress, err error) {
            if err != nil {
                fmt.Printf("Attempt %d error: %v at %.1f%% progress\n",
                    attempt, err, float64(p.Percentage))
                // Trigger cancellation to allow retry
            }
        })

    result := streaming.Start(context.Background())

    if result.IsSuccess() {
        fmt.Printf("Download succeeded on attempt %d\n", attempt)
        break
    }

    if attempt < maxRetries {
        // Cancel before retry
        streaming.Cancel()
        fmt.Printf("Retrying after failed attempt %d\n", attempt)
        time.Sleep(time.Duration(attempt*2) * time.Second) // Exponential backoff
    }
}

// Example 4: Timeout-based automatic cancellation
file, _ := os.Open("slow_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/with-timeout").
    WithStreaming(file, nil).
    WithChunkSize(256 * 1024).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Transfer failed: %v\n", err)
        }
    })

// Start streaming with a total operation timeout
done := make(chan *wrapper)
go func() {
    result := streaming.Start(context.Background())
    done <- result
}()

// Set overall timeout (different from read/write timeouts)
select {
case result := <-done:
    fmt.Printf("Streaming completed: %s\n", result.Message())
case <-time.After(60 * time.Second): // 60 second total limit
    fmt.Println("Streaming exceeded total timeout")
    streaming.Cancel().
        WithMessage("Cancelled due to total operation timeout").
        WithStatusCode(408). // 408 Request Timeout
        WithDebuggingKV("timeout_seconds", 60)
}

// Example 5: Graceful cancellation with progress snapshot
dataStream := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/stream/graceful-cancel").
    WithStreaming(dataStream, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil && p.CurrentChunk > 1000 {
            fmt.Printf("Cancelling after processing %d chunks\n",
                p.CurrentChunk)
        }
    })

result := streaming.Start(context.Background())

// Capture final progress before cancellation
finalProgress := streaming.GetProgress()
cancelResult := streaming.Cancel().
    WithMessage("Streaming cancelled gracefully").
    WithStatusCode(206). // 206 Partial Content - data transfer interrupted
    WithDebuggingKV("chunks_processed", finalProgress.CurrentChunk).
    WithDebuggingKVf("progress_percentage", "%.1f", float64(finalProgress.Percentage)).
    WithDebuggingKVf("bytes_transferred", "%d", finalProgress.TransferredBytes)

Cancellation Workflow Patterns: 

Pattern                     When to Use                 Benefit
────────────────────────────────────────────────────────────────────
User-Initiated              UI pause/cancel button      User control
Timeout-Based               Watchdog timer              Safety mechanism
Resource-Constrained        Memory/CPU threshold        System protection
Error-Recovery              Retry on failure            Fault tolerance
Graceful-Degradation        Service overload            Load shedding
Circuit-Breaker             Repeated failures           Cascade prevention

Partial Data Handling After Cancellation: 

Destination Type    Partial Data Fate           Cleanup Strategy
───────────────────────────────────────────────────────────────────
File                Partial file remains         Delete or truncate
Network (HTTP)      Partial response sent        Client handles truncation
Buffer (Memory)     Data in buffer persists      Can retry or discard
Database            Partial transactions         Rollback or cleanup
Cloud storage       Partial upload               Delete partial object

Best Practices:

  1. ALWAYS PAIR WITH CLOSE() - Cancel() stops streaming - Close() cleans up resources - Pattern: Cancel() → do cleanup → Close() - Example: streaming.Cancel() // Handle cleanup streaming.Close()

  2. MONITOR CANCELLATION STATE - Check IsStreaming() before/after cancellation - Log cancellation reasons for diagnostics - Track cancellation frequency for patterns - Example: if streaming.IsStreaming() { streaming.Cancel() }

  3. HANDLE PARTIAL DATA - Destination retains data transferred before cancellation - Design cleanup/rollback logic based on destination type - Example for files: streaming.Cancel() if shouldRollback { os.Remove(destinationFile) }

  4. IMPLEMENT IDEMPOTENCY - Cancel() is safe to call multiple times - Subsequent calls are no-ops - Caller doesn't need guard logic - Example: streaming.Cancel() // Safe even if already cancelled streaming.Cancel() // No additional effect

  5. USE WITH ERROR HANDLING - Cancellation should be logged with context - Include progress snapshot in logs - Example: progress := streaming.GetProgress() log.Warnf("Streaming cancelled at %.1f%% after %d chunks", float64(progress.Percentage), progress.CurrentChunk) streaming.Cancel()

See Also:

  • Close: Closes streams and cleans up all resources
  • IsStreaming: Checks if streaming is currently active
  • GetProgress: Captures progress state before cancellation
  • GetStats: Retrieves statistics up to cancellation point
  • WithCallback: Receives cancellation errors (context done)
  • Start: Initiates streaming operation that can be cancelled

func (StreamingWrapper) Cause 

func (w StreamingWrapper) Cause() error

Cause traverses the error chain and returns the underlying cause of the error associated with the `wrapper` instance.

This function checks if the error stored in the `wrapper` is itself another `wrapper` instance. If so, it recursively calls `Cause` on the inner error to find the ultimate cause. Otherwise, it returns the current error.

Returns:

  • The underlying cause of the error, which can be another error or the original error.

func (StreamingWrapper) Clone 

func (w StreamingWrapper) Clone() *wrapper

Clone creates a deep copy of the `wrapper` instance.

This function creates a new `wrapper` instance with the same fields as the original instance. It creates a new `header`, `meta`, and `pagination` instances and copies the values from the original instance. It also creates a new `debug` map and copies the values from the original instance.

Returns:

  • A pointer to the cloned `wrapper` instance.
  • `nil` if the `wrapper` instance is not available.

func (*StreamingWrapper) Close 

func (sw *StreamingWrapper) Close() *wrapper

Close closes the streaming wrapper and releases all underlying resources.

This function performs comprehensive cleanup of the streaming operation by cancelling the streaming context, closing the input reader, and closing the output writer if they implement the io.Closer interface. It ensures all system resources (file handles, network connections, buffers) are properly released and returned to the operating system. Close is idempotent and safe to call multiple times; subsequent calls have no effect. It should be called after streaming completes, is cancelled, or encounters an error to prevent resource leaks. Unlike Cancel() which stops streaming but leaves resources open, Close() performs full cleanup and should be the final operation in a streaming workflow. Errors encountered during resource closure are recorded in the wrapper's error field for diagnostic purposes, allowing the caller to verify cleanup completion. Close() can be called from any goroutine and is thread-safe with respect to the streaming context cancellation.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • The function attempts to close all closeable resources and accumulates all errors encountered.
  • If reader.Close() fails, the error is recorded in the wrapper; writer.Close() is still attempted.
  • If writer.Close() fails, the error is recorded in the wrapper.
  • If both fail, both errors are recorded sequentially in the wrapper.
  • Status code and message are not modified unless close errors occur; use chaining to update if needed.
  • Non-closeable resources (non-io.Closer) are silently skipped with no error.

Resource Closure Semantics: 

Resource Type           Close Behavior                          Error Handling
────────────────────────────────────────────────────────────────────────────────
os.File (reader)        File handle released to OS             Error recorded, continue
os.File (writer)        File handle released to OS             Error recorded, continue
http.Response.Body      TCP connection returned to pool        Error recorded, continue
bytes.Buffer            No-op (not io.Closer)                 Silent skip
io.Pipe                 Pipe closed, EOF to readers            Error recorded
Network connection      Socket closed, connection terminated   Error recorded, continue
Compression reader      Decompressor flushed and closed        Error recorded, continue
Custom io.Closer        Custom Close() called                 Error recorded
Already closed          Typically returns error                Error recorded
Streaming context       Cancellation signal propagated         No-op (already done)

Close vs Cancel Lifecycle: 

Scenario                    Cancel()                Close()
───────────────────────────────────────────────────────────────────────────────
Purpose                     Stop streaming          Full resource cleanup
Context cancellation        Yes                     Yes (redundant)
Closes reader               No                      Yes (if io.Closer)
Closes writer               No                      Yes (if io.Closer)
Releases file handles       No                      Yes
Releases connections        No                      Yes
Cleans up buffers           No                      Yes (via Close)
Partial data preserved      Yes                     Yes
Resource state              Streaming stopped       All resources released
Can restart streaming       Yes (new context)       No (resources gone)
Idempotent                  Yes                     Yes
Error accumulation          No error handling       Accumulates close errors
Typical use case            Interrupt/pause         Final cleanup
Recommended order           Cancel() then Close()   Always call Close()
Thread-safe                 Yes                     Yes

Closure Order and Error Accumulation: 

Step    Action                          Error Behavior
────────────────────────────────────────────────────────────────────
1       Cancel context                  No error (already done)
2       Check reader is io.Closer       Silent skip if not
3       Call reader.Close()             Error recorded, continue
4       Check writer is io.Closer       Silent skip if not
5       Call writer.Close()             Error recorded, continue
6       Return wrapper                  Contains all accumulated errors

Resource Cleanup Requirements by Type: 

Reader Type             Close Requirement           Consequence if not closed
─────────────────────────────────────────────────────────────────────────────
os.File                 Mandatory                   File descriptor leak
io.ReadCloser           Mandatory                   Resource leak (memory/handles)
http.Response.Body      Mandatory                   Connection leak, pool exhaustion
bytes.Buffer            Optional (not closeable)    No consequences
io.Reader (plain)       Optional (no Close)         No consequences
Pipe reader             Mandatory                   Blocked writers, memory leak
Compressed reader       Mandatory                   Decompressor leak
Network socket          Mandatory                   Connection leak, resource leak
Database cursor         Mandatory (custom impl)     Cursor/connection leak
Custom reader           Depends on implementation   Varies by implementation

Writer Type             Close Requirement           Consequence if not closed
─────────────────────────────────────────────────────────────────────────────
os.File                 Mandatory                   File descriptor leak, unflushed data
io.WriteCloser          Mandatory                   Resource leak, buffered data loss
http.ResponseWriter     Not closeable (handled)     Data may be buffered
bytes.Buffer            Optional (not closeable)    No consequences
io.Writer (plain)       Optional (no Close)         No consequences
Pipe writer             Mandatory                   Blocked readers, memory leak
Compressed writer       Mandatory                   Unflushed compressed data
Network socket          Mandatory                   Connection leak
File buffered writer    Mandatory                   Data loss, descriptor leak
Custom writer           Depends on implementation   Varies by implementation

Example: 

// Example 1: Standard cleanup after successful streaming
file, _ := os.Open("large_file.bin")
defer file.Close() // Double-close is safe

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Streaming error: %v\n", err)
        }
    })

// Start streaming
result := streaming.Start(context.Background())

// Always close resources
finalResult := streaming.Close().
    WithMessage("Download completed and resources cleaned up").
    WithStatusCode(200)

if finalResult.IsError() {
    fmt.Printf("Cleanup error: %s\n", finalResult.Error())
}

// Example 2: Error recovery with explicit cleanup
httpResp, _ := http.Get("https://api.example.com/largefile")

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/proxy/remote-file").
    WithStreaming(httpResp.Body, nil). // HTTP response body
    WithChunkSize(256 * 1024).
    WithReadTimeout(10000).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Transfer error: %v at %.1f%%\n",
                err, float64(p.Percentage))
        }
    })

result := streaming.Start(context.Background())

if result.IsError() {
    fmt.Printf("Streaming failed: %s\n", result.Error())
}

// Close HTTP connection and release resources
cleanupResult := streaming.Close().
    WithMessage("Resources released after error").
    WithStatusCode(500)

// Verify cleanup
if cleanupResult.IsError() {
    log.Warnf("Cleanup issues: %s", cleanupResult.Error())
}

// Example 3: Cancellation followed by cleanup
dataExport := createDataReader()
outputFile, _ := os.Create("export.csv")
defer outputFile.Close() // Double-close is safe

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/data").
    WithCustomFieldKV("export_type", "csv").
    WithStreaming(dataExport, nil).
    WithChunkSize(512 * 1024).
    WithMaxConcurrentChunks(4).
    WithWriter(outputFile).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Export error: %v\n", err)
        }
    })

// Simulate user cancellation
time.Sleep(3 * time.Second)
streaming.Cancel().
    WithMessage("Export cancelled by user")

// Cleanup: Close streaming resources
cleanupResult := streaming.Close().
    WithMessage("Export cancelled and resources released")

// Verify files are properly closed
progress := streaming.GetProgress()
fmt.Printf("Partial export: %d bytes in %d chunks\n",
    progress.TransferredBytes, progress.CurrentChunk)

// Example 4: Deferred cleanup pattern (recommended)
func StreamWithAutomaticCleanup(fileReader io.ReadCloser) *wrapper {
    defer func() {
        fileReader.Close() // Redundant but safe with Close()
    }()

    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/auto-cleanup").
        WithStreaming(fileReader, nil).
        WithChunkSize(1024 * 1024)

    result := streaming.Start(context.Background())

    // Cleanup via Close() - safe even with defer above
    return streaming.Close().
        WithMessage("Streaming completed with automatic cleanup")
}

// Example 5: Error handling with comprehensive cleanup
func StreamWithErrorHandling(reader io.ReadCloser, writer io.WriteCloser) (*wrapper, error) {
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/with-error-handling").
        WithStreaming(reader, nil).
        WithChunkSize(256 * 1024).
        WithWriter(writer).
        WithReadTimeout(15000).
        WithWriteTimeout(15000).
        WithCallback(func(p *StreamProgress, err error) {
            if err != nil {
                fmt.Printf("Streaming error at chunk %d: %v\n",
                    p.CurrentChunk, err)
            }
        })

    // Execute streaming
    result := streaming.Start(context.Background())

    // Always cleanup, regardless of success/failure
    finalResult := streaming.Close()

    // Log cleanup status
    if finalResult.IsError() {
        fmt.Printf("Cleanup warnings: %s\n", finalResult.Error())
        // Don't fail overall operation due to close errors
    }

    // Return original streaming result (not close result)
    return result, nil
}

// Example 6: Comparison of cleanup patterns
// Pattern 1: Minimal cleanup (not recommended - resource leak potential)
streaming := replify.New().WithStreaming(file, nil)
streaming.Start(context.Background())
// Missing: streaming.Close() -> RESOURCE LEAK

// Pattern 2: Basic cleanup (recommended)
streaming := replify.New().WithStreaming(file, nil)
result := streaming.Start(context.Background())
streaming.Close() // ✓ Proper cleanup

// Pattern 3: Error-aware cleanup (best for production)
streaming := replify.New().WithStreaming(file, nil)
result := streaming.Start(context.Background())
cleanupResult := streaming.Close()
if cleanupResult.IsError() {
    log.Warnf("Streaming cleanup had issues: %s", cleanupResult.Error())
}

// Pattern 4: Defer-based cleanup (most idiomatic)
func downloadFile(fileReader io.ReadCloser) *wrapper {
    streaming := replify.New().WithStreaming(fileReader, nil)
    defer streaming.Close() // Guaranteed cleanup

    return streaming.Start(context.Background())
}

Idempotency Guarantee: 

Call Sequence               Behavior                Result
─────────────────────────────────────────────────────────────────────
Close()                     Normal cleanup          Resources released
Close(); Close()            Second call is no-op    No additional effect
Close(); Close(); Close()   All no-ops after first  Safe to call >1x

Safety Example:
  defer streaming.Close() // Call 1
  ...
  streaming.Close() // Call 2 - safe, no-op
  ...
  if cleanup {
      streaming.Close() // Call 3 - safe, no-op
  }

Best Practices:

  1. ALWAYS CLOSE AFTER STREAMING - Use defer for guarantee - Pattern: streaming := replify.New().WithStreaming(reader, nil) defer streaming.Close() result := streaming.Start(ctx)

  2. HANDLE CLOSE ERRORS - Check for close errors - Log for diagnostics - Example: cleanupResult := streaming.Close() if cleanupResult.IsError() { log.Warnf("Close error: %s", cleanupResult.Error()) }

  3. CLOSE AFTER CANCEL - Cancel first (stop streaming) - Then Close (release resources) - Pattern: streaming.Cancel() streaming.Close()

  4. DOUBLE-CLOSE IS SAFE - io.Closer implementations handle multiple Close() calls - Idempotent design - Example: defer file.Close() // OS level defer streaming.Close() // Streaming level // Both safe even if called in any order

  5. CLOSE EARLY ON ERROR - Close immediately on error - Don't delay cleanup - Example: result := streaming.Start(ctx) if result.IsError() { streaming.Close() // Cleanup immediately return result } streaming.Close() // Normal cleanup

Resource Leak Scenarios and Prevention: 

Scenario                           Risk Level    Prevention
──────────────────────────────────────────────────────────────────
Missing Close() entirely           CRITICAL      Use defer streaming.Close()
Close() only in success path       HIGH          Always close (use defer)
Exception/panic without Close      HIGH          Defer statement essential
Goroutine exit without Close       HIGH          Ensure Close() in goroutine
File handle accumulation           MEDIUM        Monitor open file count
Connection pool exhaustion         MEDIUM        Close responses promptly
Memory buffering accumulation      MEDIUM        Close flushes buffers
Deadlock on Close                  LOW           Streaming handles correctly

Performance Considerations: 

Operation                   Time Cost        Notes
──────────────────────────────────────────────────────────────
Cancel context              <1ms             Context already signaled
Type assertion (io.Closer)   <1μs            Cheap operation
reader.Close()              1-100ms          Depends on implementation
writer.Close()              1-100ms          Depends on implementation (flush)
Total Close() operation      2-200ms          Dominated by actual Close() calls
Defer overhead              <1μs             Negligible cost

See Also:

  • Cancel: Stops streaming without closing resources
  • IsStreaming: Checks if streaming is currently active
  • GetProgress: Captures final progress before close
  • GetStats: Retrieves final statistics before resources close
  • Start: Initiates streaming operation
  • WithReader/WithWriter: Provides closeable resources

func (StreamingWrapper) CollectJSONBodyFloat64 

func (w StreamingWrapper) CollectJSONBodyFloat64(path string) []float64

CollectJSONBodyFloat64 collects every value at the given path in the body that can be coerced to float64 (including string-encoded numbers). Non-numeric values are skipped.

Example: 

prices := w.CollectJSONBodyFloat64("items.#.price")

func (StreamingWrapper) CompressSafe 

func (w StreamingWrapper) CompressSafe(threshold int) *wrapper

CompressSafe compresses the body data if it exceeds a specified threshold.

This function checks if the `wrapper` instance is available and if the body data exceeds the specified threshold for compression. If the body data is larger than the threshold, it compresses the data using gzip and updates the body with the compressed data. It also adds debugging information about the compression process, including the original and compressed sizes. If the threshold is not specified or is less than or equal to zero, it defaults to 1024 bytes (1KB). It also removes any empty debugging fields to clean up the response. Parameters:

  • `threshold`: An integer representing the size threshold for compression. If the body data size exceeds this threshold, it will be compressed.

Returns:

  • A pointer to the `wrapper` instance, allowing for method chaining.

If the `wrapper` is not available, it returns the original instance without modifications.

func (StreamingWrapper) CountJSONBody 

func (w StreamingWrapper) CountJSONBody(path string) int

CountJSONBody returns the number of elements at the given path in the body. For an array result it returns the array length; for a scalar it returns 1; for a missing path it returns 0.

Example: 

n := w.CountJSONBody("items")

func (StreamingWrapper) Debugging 

func (w StreamingWrapper) Debugging() map[string]any

Debugging retrieves the debugging information from the `wrapper` instance.

This function checks if the `wrapper` instance is available (non-nil) before returning the value of the `debug` field. If the `wrapper` is not available, it returns an empty map to ensure safe usage.

Returns:

  • A `map[string]interface{}` containing the debugging information.
  • An empty map if the `wrapper` instance is not available.

func (StreamingWrapper) DebuggingBool 

func (w StreamingWrapper) DebuggingBool(key string, defaultValue bool) bool

DebuggingBool retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A boolean value to return if the key is not available.

Returns:

  • The boolean value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingDuration 

func (w StreamingWrapper) DebuggingDuration(key string, defaultValue time.Duration) time.Duration

DebuggingDuration retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Duration value to return if the key is not available.

Returns:

  • The time.Duration value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingFloat32 

func (w StreamingWrapper) DebuggingFloat32(key string, defaultValue float32) float32

DebuggingFloat32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float32 value to return if the key is not available.

Returns:

  • The float32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingFloat64 

func (w StreamingWrapper) DebuggingFloat64(key string, defaultValue float64) float64

DebuggingFloat64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float64 value to return if the key is not available.

Returns:

  • The float64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingInt 

func (w StreamingWrapper) DebuggingInt(key string, defaultValue int) int

DebuggingInt retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An integer value to return if the key is not available.

Returns:

  • The integer value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingInt8 

func (w StreamingWrapper) DebuggingInt8(key string, defaultValue int8) int8

DebuggingInt8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int8 value to return if the key is not available.

Returns:

  • The int8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingInt16 

func (w StreamingWrapper) DebuggingInt16(key string, defaultValue int16) int16

DebuggingInt16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int16 value to return if the key is not available.

Returns:

  • The int16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingInt32 

func (w StreamingWrapper) DebuggingInt32(key string, defaultValue int32) int32

DebuggingInt32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int32 value to return if the key is not available.

Returns:

  • The int32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingInt64 

func (w StreamingWrapper) DebuggingInt64(key string, defaultValue int64) int64

DebuggingInt64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int64 value to return if the key is not available.

Returns:

  • The int64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingString 

func (w StreamingWrapper) DebuggingString(key string, defaultValue string) string

DebuggingString retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A string value to return if the key is not available.

Returns:

  • The string value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingTime 

func (w StreamingWrapper) DebuggingTime(key string, defaultValue time.Time) time.Time

DebuggingTime retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Time value to return if the key is not available.

Returns:

  • The time.Time value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingUint 

func (w StreamingWrapper) DebuggingUint(key string, defaultValue uint) uint

DebuggingUint retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint value to return if the key is not available.

Returns:

  • The uint value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingUint8 

func (w StreamingWrapper) DebuggingUint8(key string, defaultValue uint8) uint8

DebuggingUint8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint8 value to return if the key is not available.

Returns:

  • The uint8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingUint16 

func (w StreamingWrapper) DebuggingUint16(key string, defaultValue uint16) uint16

DebuggingUint16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint16 value to return if the key is not available.

Returns:

  • The uint16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingUint32 

func (w StreamingWrapper) DebuggingUint32(key string, defaultValue uint32) uint32

DebuggingUint32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint32 value to return if the key is not available.

Returns:

  • The uint32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DebuggingUint64 

func (w StreamingWrapper) DebuggingUint64(key string, defaultValue uint64) uint64

DebuggingUint64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint64 value to return if the key is not available.

Returns:

  • The uint64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) DecompressSafe 

func (w StreamingWrapper) DecompressSafe() *wrapper

DecompressSafe decompresses the body data if it is compressed.

This function checks if the `wrapper` instance is available and if the body data is compressed. If the body data is compressed, it decompresses the data using gzip and updates the instance with the decompressed data. It also adds debugging information about the decompression process, including the original and decompressed sizes. If the body data is not compressed, it returns the original instance without modifications.

Returns:

  • A pointer to the `wrapper` instance, allowing for method chaining.

If the `wrapper` is not available, it returns the original instance without modifications.

func (StreamingWrapper) DecreaseDeltaCnt 

func (w StreamingWrapper) DecreaseDeltaCnt() *wrapper

DecreaseDeltaCnt decrements the delta count in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and decrements the delta count in the `meta` using the `DecreaseDeltaCnt` method.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) DeltaCnt 

func (w StreamingWrapper) DeltaCnt() int

DeltaCnt retrieves the delta count from the `meta` instance.

This function checks if the `meta` instance is present and returns the `deltaCnt` field. If the `meta` instance is not present, it returns a default value of `0`.

Returns:

  • An integer representing the delta count.

func (StreamingWrapper) DeltaValue 

func (w StreamingWrapper) DeltaValue() float64

DeltaValue retrieves the delta value from the `meta` instance.

This function checks if the `meta` instance is present and returns the `deltaValue` field. If the `meta` instance is not present, it returns a default value of `0`.

Returns:

  • A float64 representing the delta value.

func (StreamingWrapper) DistinctJSONBody 

func (w StreamingWrapper) DistinctJSONBody(path string) []fj.Context

DistinctJSONBody evaluates the given path in the body and returns a deduplicated slice of values using each element's string representation as the equality key. First-occurrence order is preserved.

Example: 

tags := w.DistinctJSONBody("tags")

func (StreamingWrapper) Error 

func (w StreamingWrapper) Error() string

Error retrieves the error associated with the `wrapper` instance.

This function returns the `errors` field of the `wrapper`, which contains any errors encountered during the operation of the `wrapper`.

Returns:

  • An error object, or `nil` if no errors are present.

func (*StreamingWrapper) Errors 

func (sw *StreamingWrapper) Errors() []error

Errors returns a copy of all errors that occurred during the streaming operation.

This function provides thread-safe access to the complete error history accumulated during streaming. Errors are recorded for each chunk processing failure, I/O operation failure, compression/decompression error, timeout expiration, or context cancellation. The function returns a defensive copy of the error slice to prevent external modification of the internal error list. Multiple calls to Errors() return independent copies; modifications to one copy do not affect others or the internal state. This is useful for comprehensive error reporting, diagnostics, debugging, and implementing retry or circuit breaker logic. Errors are maintained in chronological order (FIFO) with the first error at index 0 and the most recent error at the last index. The error list is thread-safe and can be accessed from any goroutine during or after streaming.

Returns:

  • A newly allocated slice containing copies of all errors that occurred.
  • Returns an empty slice if no errors occurred during streaming.
  • Returns an empty slice if the streaming wrapper is nil.
  • The returned slice is independent; modifications do not affect internal state.
  • Each call returns a fresh copy; subsequent calls may contain additional errors if streaming is ongoing or if new errors were recorded after the previous call.
  • Errors are maintained in chronological order (FIFO): first error at index 0, latest at last index.
  • Thread-safe: safe to call from multiple goroutines simultaneously during streaming.

Error Types Recorded: 

Error Category              When Recorded                   Example
─────────────────────────────────────────────────────────────────────────
Read errors                 reader.Read() fails             Connection reset, EOF mismatch
Write errors                writer.Write() fails            Slow client timeout, buffer full
Compression errors          Compress/decompress fails       Invalid compressed data
Context errors              Context deadline exceeded       Read/write timeout triggered
Checksum errors             Chunk integrity check fails     Data corruption detected
Type assertion errors       Reader/writer not Closeable     Interface mismatch (rare)
User errors                 Invalid parameters passed       Negative timeout, empty strategy
Resource errors             Resource allocation failed      Out of memory, descriptor limit
Custom errors               Application-specific errors     Custom reader/writer errors
Accumulated errors          Multiple chunk failures         Retries and partial failures

Error Recording Behavior: 

Event                           Error Recorded    Behavior
────────────────────────────────────────────────────────────────────
Single chunk read fail          Yes (1 error)     Streaming continues (retry next chunk)
Single chunk write fail         Yes (1 error)     Streaming continues
Read timeout triggered          Yes (1 error)     Streaming terminates
Write timeout triggered         Yes (1 error)     Streaming terminates
Compression fails              Yes (1 error)     Chunk skipped, streaming continues
Decompression fails            Yes (1 error)     Chunk skipped, streaming continues
Context cancelled              Yes (1 error)     Streaming terminates gracefully
Multiple chunk failures        Yes (N errors)     All recorded in order
No errors during transfer      No errors          Empty error list
Successful completion          No new errors      Final list unchanged

Error History Timeline Example: 

Timeline                         Errors() Returns                  Explanation
─────────────────────────────────────────────────────────────────────────────
Chunk 1-100 ok                   []                                No errors yet
Chunk 101 write timeout          [timeout error]                   First error recorded
Chunk 102 ok (retry)             [timeout error]                   List unchanged
Chunk 103 write fail             [timeout error, write error]      Second error added
Chunk 104-200 ok                 [timeout error, write error]      List stable
Chunk 201 compression fail       [timeout error, write error, ...] Third error added
Streaming completes              [all accumulated errors]          Final error list

Example: 

// Example 1: Simple error checking after streaming
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(256 * 1024).
    WithReadTimeout(10000).
    WithWriteTimeout(10000).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Chunk %d error: %v\n", p.CurrentChunk, err)
        }
    })

result := streaming.Start(context.Background())

// Check all errors that occurred
errors := streaming.Errors()
if len(errors) > 0 {
    fmt.Printf("Streaming completed with %d errors:\n", len(errors))
    for i, err := range errors {
        fmt.Printf("  Error %d: %v\n", i+1, err)
    }
} else {
    fmt.Println("Streaming completed successfully with no errors")
}

// Example 2: Error analysis for retry logic
httpResp, _ := http.Get("https://api.example.com/largefile")
defer httpResp.Body.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/proxy/remote-download").
    WithStreaming(httpResp.Body, nil).
    WithChunkSize(1024 * 1024).
    WithReadTimeout(15000).
    WithWriteTimeout(15000)

result := streaming.Start(context.Background())
streamErrors := streaming.Errors()

// Analyze errors to decide retry strategy
timeoutCount := 0
ioErrorCount := 0
otherErrorCount := 0

for _, err := range streamErrors {
    errStr := err.Error()
    if strings.Contains(errStr, "timeout") {
        timeoutCount++
    } else if strings.Contains(errStr, "read") || strings.Contains(errStr, "write") {
        ioErrorCount++
    } else {
        otherErrorCount++
    }
}

fmt.Printf("Error summary:\n")
fmt.Printf("  Timeouts: %d\n", timeoutCount)
fmt.Printf("  I/O errors: %d\n", ioErrorCount)
fmt.Printf("  Other errors: %d\n", otherErrorCount)

// Decide retry based on error types
if timeoutCount > ioErrorCount {
    fmt.Println("Recommendation: Increase timeout and retry")
} else if ioErrorCount > 0 {
    fmt.Println("Recommendation: Check network connectivity and retry")
}

// Example 3: Error logging with context
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/bulk-data").
    WithCustomFieldKV("export_id", "exp-2025-1114-001").
    WithStreaming(dataExport, nil).
    WithChunkSize(10 * 1024 * 1024).
    WithMaxConcurrentChunks(8).
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Warnf("Export %s: chunk %d failed: %v",
                "exp-2025-1114-001", p.CurrentChunk, err)
        }
    })

result := streaming.Start(context.Background())
allErrors := streaming.Errors()

// Comprehensive error reporting
if len(allErrors) > 0 {
    log.Warnf("Export exp-2025-1114-001: %d errors during transfer:", len(allErrors))
    for i, err := range allErrors {
        log.Warnf("  [Error %d/%d] %v", i+1, len(allErrors), err)
    }

    // Store error history for later investigation
    progress := streaming.GetProgress()
    stats := streaming.GetStats()
    log.Infof("Export context: Progress=%.1f%%, Chunks=%d, Bytes=%d",
        float64(progress.Percentage), progress.CurrentChunk, stats.TotalBytes)
}

// Example 4: Circuit breaker pattern with error tracking
maxErrorsAllowed := 5
circuitOpen := false

fileReader, _ := os.Open("data.bin")
defer fileReader.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/stream/circuit-breaker").
    WithStreaming(fileReader, nil).
    WithChunkSize(512 * 1024).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            // Check current error count
            currentErrors := streaming.Errors()
            if len(currentErrors) >= maxErrorsAllowed {
                fmt.Printf("Circuit breaker: %d errors exceeded limit, stopping\n",
                    len(currentErrors))
                circuitOpen = true
                streaming.Cancel()
            }
        }
    })

result := streaming.Start(context.Background())
finalErrors := streaming.Errors()

if circuitOpen {
    fmt.Printf("Streaming stopped due to circuit breaker (errors: %d)\n",
        len(finalErrors))
} else if len(finalErrors) > 0 {
    fmt.Printf("Streaming completed with %d tolerable errors\n",
        len(finalErrors))
}

// Example 5: Error deduplication and categorization
func AnalyzeStreamingErrors(streaming *StreamingWrapper) map[string]int {
    errors := streaming.Errors()
    errorCounts := make(map[string]int)
    errorTypes := make(map[string]bool)

    for _, err := range errors {
        errMsg := err.Error()

        // Categorize error
        var errorType string
        switch {
        case strings.Contains(errMsg, "timeout"):
            errorType = "timeout"
        case strings.Contains(errMsg, "connection"):
            errorType = "connection"
        case strings.Contains(errMsg, "read"):
            errorType = "read"
        case strings.Contains(errMsg, "write"):
            errorType = "write"
        case strings.Contains(errMsg, "compression"):
            errorType = "compression"
        default:
            errorType = "other"
        }

        errorCounts[errorType]++
        errorTypes[errorType] = true
    }

    fmt.Println("Error breakdown:")
    for errorType := range errorTypes {
        fmt.Printf("  %s: %d\n", errorType, errorCounts[errorType])
    }

    return errorCounts
}

// Example 6: Error history export for diagnostics
func ExportErrorReport(streaming *StreamingWrapper) string {
    errors := streaming.Errors()
    progress := streaming.GetProgress()
    stats := streaming.GetStats()

    var report strings.Builder
    report.WriteString("=== STREAMING ERROR REPORT ===\n")
    report.WriteString(fmt.Sprintf("Timestamp: %s\n", time.Now().Format(time.RFC3339)))
    report.WriteString(fmt.Sprintf("Total Errors: %d\n", len(errors)))
    report.WriteString(fmt.Sprintf("Progress: %.1f%% (%d/%d bytes)\n",
        float64(progress.Percentage), progress.TransferredBytes, progress.TotalBytes))
    report.WriteString(fmt.Sprintf("Chunks: %d processed\n", progress.CurrentChunk))
    report.WriteString(fmt.Sprintf("Duration: %s\n", stats.EndTime.Sub(stats.StartTime)))

    report.WriteString("\n=== ERROR DETAILS ===\n")
    for i, err := range errors {
        report.WriteString(fmt.Sprintf("[%d] %v\n", i+1, err))
    }

    return report.String()
}

Error Handling Patterns: 

Pattern                         Use Case                        Implementation
─────────────────────────────────────────────────────────────────────────────
No-error path                   Success only                    if len(errors) == 0
Basic error check               Error awareness                 if len(errors) > 0
Error counting                  Threshold-based decisions       len(errors) > threshold
Error categorization            Retry logic selection           Analyze error types
Error deduplication             Deduplicate repeated errors     Use map for uniqueness
Circuit breaker                 Fail-fast on repeated errors    Break on error count
Error trend analysis            Long-term diagnostics          Track error patterns
Detailed error reporting        Production diagnostics          Export error history

Thread-Safety Guarantees: 

Scenario                        Thread-Safe    Notes
─────────────────────────────────────────────────────────────────
Errors() during streaming       Yes            Uses RWMutex lock
Errors() after streaming done   Yes            Lock prevents race
Multiple concurrent Errors()    Yes            RWMutex allows parallel reads
Errors() + HasErrors()          Yes            Consistent snapshot
Errors() + GetProgress()        Maybe          Different locks (consult separately)
Errors() in callback            Yes            Called by streaming goroutine
Errors() in cancel/close        Yes            Idempotent operation

Performance Notes: 

Operation                   Time Complexity    Space Complexity    Notes
─────────────────────────────────────────────────────────────────────
Errors() call               O(n)               O(n)                Copies full slice
First call (0 errors)       O(1)               O(1)                Minimal overhead
Mid-stream (1000 errors)    O(1000)            O(1000)             Allocates new slice
Final call (10000 errors)   O(10000)           O(10000)            Large allocation
RWMutex acquisition         O(1)               O(1)                Lock contention minimal
Memory allocation           O(n)               O(n)                Linear in error count

Related Error Checking Methods: 

Method              Returns                 Use Case
────────────────────────────────────────────────────────────────────
HasErrors()         bool                    Quick check for any error
Errors()            []error                 Complete error list (this function)
GetProgress()       *StreamProgress         Error count in progress struct
GetStats()          *StreamingStats         FailedChunks in stats
GetWrapper()        *wrapper                Wrapper error messages

See Also:

  • HasErrors: Quickly checks if any errors occurred without retrieving list
  • GetProgress: Includes error occurrence information in progress
  • GetStats: Provides failed chunk count and error array
  • GetWrapper: Returns wrapper with accumulated error messages
  • WithCallback: Callback receives individual errors as they occur
  • Start: Initiates streaming and accumulates errors during operation

func (StreamingWrapper) FilterJSONBody 

func (w StreamingWrapper) FilterJSONBody(path string, fn func(fj.Context) bool) []fj.Context

FilterJSONBody evaluates the given path in the body, treats the result as an array, and returns only those elements for which fn returns true.

Example: 

active := w.FilterJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("active").Bool()
})

func (StreamingWrapper) FindJSONBodyPath 

func (w StreamingWrapper) FindJSONBodyPath(value string) string

FindJSONBodyPath returns the first dot-notation path in the body at which a scalar value equals the given string (exact, case-sensitive match).

Returns "" when no leaf matches.

Example: 

path := w.FindJSONBodyPath("[email protected]")

func (StreamingWrapper) FindJSONBodyPathMatch 

func (w StreamingWrapper) FindJSONBodyPathMatch(pattern string) string

FindJSONBodyPathMatch returns the first dot-notation path in the body at which a scalar value matches the given wildcard pattern.

Example: 

path := w.FindJSONBodyPathMatch("alice*")

func (StreamingWrapper) FindJSONBodyPaths 

func (w StreamingWrapper) FindJSONBodyPaths(value string) []string

FindJSONBodyPaths returns all dot-notation paths in the body at which a scalar value equals the given string.

Example: 

paths := w.FindJSONBodyPaths("active")

func (StreamingWrapper) FindJSONBodyPathsMatch 

func (w StreamingWrapper) FindJSONBodyPathsMatch(pattern string) []string

FindJSONBodyPathsMatch returns all dot-notation paths in the body at which a scalar value matches the given wildcard pattern.

Example: 

paths := w.FindJSONBodyPathsMatch("err*")

func (StreamingWrapper) FirstJSONBody 

func (w StreamingWrapper) FirstJSONBody(path string, fn func(fj.Context) bool) fj.Context

FirstJSONBody evaluates the given path in the body and returns the first element for which fn returns true. Returns a zero-value fj.Context when not found.

Example: 

admin := w.FirstJSONBody("users", func(ctx fj.Context) bool {
    return ctx.Get("role").String() == "admin"
})

func (*StreamingWrapper) GetProgress 

func (sw *StreamingWrapper) GetProgress() *StreamProgress

GetProgress returns a thread-safe snapshot of the current streaming progress.

This function provides real-time access to the current streaming operation state without blocking or affecting the transfer. It returns a defensive copy of the progress structure containing the latest metrics including current chunk number, bytes transferred, percentage complete, elapsed time, estimated time remaining, transfer rate, and any transient error from the most recent chunk. GetProgress is thread-safe and can be called from any goroutine; the internal mutex ensures consistent snapshot isolation. The returned StreamProgress is a copy, not a reference; modifications to the returned progress do not affect the internal state or subsequent calls. This is the primary method for real-time progress monitoring, progress bars, ETA calculations, and bandwidth monitoring during streaming. GetProgress is non-blocking, O(1) complexity, and safe to call very frequently (hundreds of times per second) without performance degradation. The returned progress represents the state at the moment of the call; subsequent streaming updates do not affect the returned copy. Progress is available immediately when Start() begins and remains stable after streaming completes, allowing pre-streaming and post-streaming progress queries.

Returns:

  • A pointer to a new StreamProgress structure containing a copy of current progress metrics.
  • If the streaming wrapper is nil, returns an empty StreamProgress{} with all fields zero-valued.
  • The returned StreamProgress reflects the state at the exact moment of the call.
  • For ongoing streaming: returns current progress (actively changing with each call).
  • For completed/cancelled streaming: returns final progress (stable, unchanged).
  • Thread-safe: acquires RWMutex read lock to ensure consistent snapshot.
  • Copy semantics: returned progress is independent; modifications do not affect streaming.
  • Non-blocking: O(1) operation, safe for high-frequency polling (100+ calls/second).
  • All timestamp values are in UTC with nanosecond precision.
  • All byte counts use int64 to support transfers up to 9.2 exabytes.

StreamProgress Structure Contents: 

Field Category          Field Name                      Type            Purpose
─────────────────────────────────────────────────────────────────────────────────────
Chunk Information
                        CurrentChunk                    int64           Current chunk being processed
                        TotalChunks                     int64           Total chunks to process
                        ChunkSize                       int64           Size of each chunk
                        Size                            int64           Size of current chunk

Data Transfer
                        TransferredBytes                int64           Bytes transferred so far
                        TotalBytes                      int64           Total bytes to transfer
                        RemainingBytes                  int64           Bytes remaining
                        FailedBytes                     int64           Bytes that failed

Progress Metrics
                        Percentage                      float64         0.0-100.0 or 0.0-1.0
                        PercentageString                string          Human-readable like "45.2%"

Timing Information
                        StartTime                       time.Time       When streaming started
                        ElapsedTime                     time.Duration   Time elapsed since start
                        EstimatedTimeRemaining          time.Duration   ETA until completion

Transfer Rate
                        TransferRate                    int64           Current B/s rate
                        TransferRateMBps                float64         Current MB/s rate

Error Tracking
                        LastError                       error           Most recent error (if any)
                        HasError                        bool            Whether error occurred

Example: 

// Example 1: Simple progress monitoring during streaming
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4)

// Start streaming in background
done := make(chan *wrapper)
go func() {
    result := streaming.Start(context.Background())
    done <- result
}()

// Monitor progress
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

for {
    select {
    case <-ticker.C:
        if !streaming.IsStreaming() {
            break
        }

        // Get progress snapshot (O(1) safe call)
        progress := streaming.GetProgress()

        fmt.Printf("\rDownloading: %.1f%% (%d / %d chunks) | Speed: %.2f MB/s | ETA: %s",
            progress.Percentage,
            progress.CurrentChunk,
            progress.TotalChunks,
            float64(progress.TransferRate) / 1024 / 1024,
            progress.EstimatedTimeRemaining.String())
    case result := <-done:
        fmt.Println("\nDownload completed")
        if result.IsError() {
            fmt.Printf("Error: %s\n", result.Error())
        }
        return
    }
}

// Example 2: Progress bar with ETA calculation
func DisplayProgressBar(streaming *StreamingWrapper) {
    ticker := time.NewTicker(100 * time.Millisecond)
    defer ticker.Stop()

    for range ticker.C {
        if !streaming.IsStreaming() {
            break
        }

        progress := streaming.GetProgress()

        // Draw progress bar
        barLength := 40
        filledLength := int(float64(barLength) * progress.Percentage / 100.0)
        bar := strings.Repeat("█", filledLength) + strings.Repeat("░", barLength - filledLength)

        // Format output
        fmt.Printf("\r[%s] %.1f%% | %d/%d chunks | Speed: %.2f MB/s | ETA: %s",
            bar,
            progress.Percentage,
            progress.CurrentChunk,
            progress.TotalChunks,
            float64(progress.TransferRate) / 1024 / 1024,
            progress.EstimatedTimeRemaining.String())
    }
    fmt.Println()
}

// Example 3: Error handling in progress monitoring
httpResp, _ := http.Get("https://api.example.com/largefile")
defer httpResp.Body.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/proxy/remote-file").
    WithStreaming(httpResp.Body, nil).
    WithChunkSize(512 * 1024).
    WithReadTimeout(15000).
    WithWriteTimeout(15000).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Chunk %d error: %v\n", p.CurrentChunk, err)
        }
    })

done := make(chan *wrapper)
go func() {
    result := streaming.Start(context.Background())
    done <- result
}()

// Monitor with error detection
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

for {
    select {
    case <-ticker.C:
        progress := streaming.GetProgress()

        // Check for current error
        if progress.HasError {
            fmt.Printf("\r[ERROR] Chunk %d: %v | Progress: %.1f%%",
                progress.CurrentChunk, progress.LastError, progress.Percentage)
        } else {
            fmt.Printf("\r[OK] Chunk %d | Progress: %.1f%% | Speed: %.2f MB/s",
                progress.CurrentChunk,
                progress.Percentage,
                float64(progress.TransferRate) / 1024 / 1024)
        }

        if !streaming.IsStreaming() {
            break
        }
    case result := <-done:
        if result.IsError() {
            fmt.Printf("\nFinal error: %s\n", result.Error())
        }
        return
    }
}

// Example 4: Progress metrics for decision making
func CheckProgressThreshold(streaming *StreamingWrapper, threshold float64) bool {
    progress := streaming.GetProgress()
    return progress.Percentage >= threshold
}

// Example 5: Bandwidth monitoring and rate limiting
func MonitorBandwidth(streaming *StreamingWrapper) {
    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    var previousBytes int64

    for range ticker.C {
        progress := streaming.GetProgress()

        // Calculate instantaneous rate
        currentBytes := progress.TransferredBytes
        instantaneousRate := currentBytes - previousBytes

        fmt.Printf("Bandwidth: Avg=%.2f MB/s | Current≈%.2f MB/s | Remaining: %s\n",
            float64(progress.TransferRate) / 1024 / 1024,
            float64(instantaneousRate) / 1024 / 1024,
            progress.EstimatedTimeRemaining.String())

        previousBytes = currentBytes

        if !streaming.IsStreaming() {
            break
        }
    }
}

// Example 6: ETA-based interruption
func StreamWithTimeLimit(streaming *StreamingWrapper, maxDuration time.Duration) {
    done := make(chan *wrapper)
    go func() {
        result := streaming.Start(context.Background())
        done <- result
    }()

    ticker := time.NewTicker(100 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            progress := streaming.GetProgress()

            // Check if ETA exceeds limit
            if progress.ElapsedTime + progress.EstimatedTimeRemaining > maxDuration {
                fmt.Printf("ETA exceeds time limit, cancelling\n")
                fmt.Printf("Elapsed: %s | Remaining: %s | Total ETA: %s > %s\n",
                    progress.ElapsedTime.String(),
                    progress.EstimatedTimeRemaining.String(),
                    (progress.ElapsedTime + progress.EstimatedTimeRemaining).String(),
                    maxDuration.String())
                streaming.Cancel()
                break
            }

            fmt.Printf("Progress: %.1f%% | ETA: %s\n",
                progress.Percentage, progress.EstimatedTimeRemaining.String())
        case result := <-done:
            if result.IsError() {
                fmt.Printf("Streaming error: %s\n", result.Error())
            }
            return
        }
    }
}

Progress Field Semantics: 

Field                       Type        Valid Range         When Updated
──────────────────────────────────────────────────────────────────────────
CurrentChunk                int64       0 to TotalChunks    After each chunk
TotalChunks                 int64       0 to max            Set once, then stable
Percentage                  float64     0.0 to 100.0        Continuous
TransferRate                int64       0 to GB/s           Continuous
EstimatedTimeRemaining      Duration    0 to max            Continuous
LastError                   error       nil or error        On chunk error
HasError                    bool        true/false          On chunk error
ElapsedTime                 Duration    0 to streaming dur  Continuous

Progress Update Frequency: 

Update Source                   Frequency                   Precision
──────────────────────────────────────────────────────────────────────
Chunk completion                Per chunk                   Exact
Byte counter                    Per byte (internal)         1 byte
Elapsed time                    Nanosecond precision        Real-time
Rate calculation                Per chunk or per second     Running average
ETA calculation                 Per chunk                   Based on current rate
Error status                    Per chunk failure           Immediate

Progress Snapshot Semantics: 

Aspect                          Behavior                        Implication
──────────────────────────────────────────────────────────────────────────
Return value                    Copy of current state           Independent snapshot
Modifications                   Do not affect streaming         Safe to modify
Multiple calls                  Each returns fresh snapshot     Time-dependent results
Call during streaming           Returns current live state      Real-time information
Call after streaming            Returns final state             Stable completion metrics
Garbage collection              Copy safe from GC               Lifetime guaranteed
Concurrent calls                Thread-safe reads              Multiple goroutines safe
Call frequency                  O(1) operation                 100+ calls/second safe

Performance Characteristics: 

Operation                       Time Complexity    Space Complexity    Actual Cost
──────────────────────────────────────────────────────────────────────────────
RWMutex read lock acquisition   O(1) amortized     None                <1μs typical
Memory copy (progress := *sw.progress) O(1)        O(1) (fixed struct)  ~200 bytes copy
Return statement                 O(1)               None                <1μs
Total GetProgress() call         O(1)               O(1)                1-3μs typical
Lock contention (high concurrency) O(1)            None                <10μs worst case
High-frequency polling (100/sec) Feasible           Minimal             Negligible overhead

Comparison with GetStats(): 

Aspect                  GetProgress()           GetStats()
──────────────────────────────────────────────────────────────────
Purpose                 Real-time monitoring    Complete statistics
Field count             ~13 fields              ~25+ fields
Compression metrics     Not included            CompressionRatio
Bandwidth metrics       Current rate only       Avg/Peak/Min rates
Timing                  Elapsed + ETA           Detailed timings
Memory metrics          Not included            Memory stats
Chunk success/fail      Not included            Failure counts
Update frequency        Per chunk (continuous)  Per call
Typical use             Progress bar, ETA       Analysis, reporting
Overhead                Minimal (copy)          Moderate (more fields)

Thread-Safety Implementation: 

Component                   Protection                  Guarantee
──────────────────────────────────────────────────────────────────
sw.progress structure        RWMutex read lock           Consistent snapshot
Memory copy                  Copy isolation              Copy not affected by updates
Return pointer               Safe return                 No data race on return
Concurrent reads             Allowed by RWMutex          Multiple readers OK
Concurrent with writes       Blocked until write done    Consistent reads guaranteed
Lock acquisition             O(1) amortized              Negligible overhead
Lock duration                <1μs                        Brief, minimal contention

Copy Guarantee: 

Scenario                                    Return Value Guarantees
────────────────────────────────────────────────────────────────────
Two consecutive calls                       Different memory addresses
Modify returned progress                    Does not affect next GetProgress() call
Returned progress with nil pointer          Safe to dereference
Multiple concurrent calls                   Each gets independent copy
Internal progress updated after call        Returned progress unchanged
Returned pointer valid after streaming      Pointer lifetime guaranteed
Progress during active chunk transfer       Captured at call moment
Progress after completion                   Final metrics stable

Progress Calculation Methods: 

Metric                          Calculation Method
────────────────────────────────────────────────────────────────────
Percentage                      (TransferredBytes / TotalBytes) * 100.0
TransferRate                    TransferredBytes / ElapsedTime.Seconds()
EstimatedTimeRemaining          (RemainingBytes / TransferRate)
RemainingBytes                  TotalBytes - TransferredBytes
PercentageString                fmt.Sprintf("%.1f%%", Percentage)
Time per chunk                  ElapsedTime / CurrentChunk
Chunks remaining                TotalChunks - CurrentChunk

ETA Accuracy and Limitations: 

Factor                          Impact on ETA Accuracy
────────────────────────────────────────────────────────────────────
Constant transfer rate          ETA very accurate
Varying transfer rate           ETA less accurate (uses current rate)
Network congestion              ETA may underestimate
Throttling enabled              ETA more predictable
Client slowdowns                ETA may underestimate
Compression effectiveness       ETA may change as ratio improves
Early in transfer               ETA less reliable (small sample)
Late in transfer                ETA more reliable (better rate averaging)

Practical Use Cases: 

Use Case                        How to Use GetProgress()           Example
──────────────────────────────────────────────────────────────────────────
Progress bar                    Use Percentage for fill level      [████░░░░] 45%
ETA display                     Show EstimatedTimeRemaining        ETA: 2m 15s
Speed monitor                   Monitor TransferRate               Speed: 45.5 MB/s
Cancellation threshold          if Percentage > 90: cancel         Auto-skip large transfers
Memory estimation               Use CurrentChunk & ChunkSize       Memory: 4 chunks × 1MB
Error detection                 Check HasError and LastError       Error handling
Completion check                if Percentage == 100              Final validation
Multiple transfers              Track individual progress          Multi-file download

Integration with Callback: 

Callback Provides               GetProgress() Adds
──────────────────────────────────────────────────────────────────────────────
Individual chunk state          Complete aggregate progress
Chunk-by-chunk errors           Overall progress and rate
Real-time notifications         Historical timing (elapsed, ETA)
Low-level control               High-level metrics (percentage, rate)

Recommendation: Use both together:
  - WithCallback: immediate per-chunk feedback
  - GetProgress: periodic overall status

Best Practices:

  1. CALL FREQUENTLY FOR REAL-TIME UPDATES - O(1) operation, safe for high frequency - 100+ calls/second feasible - No performance degradation - Pattern: ticker := time.NewTicker(100 * time.Millisecond) progress := streaming.GetProgress() // O(1) safe call

  2. USE BOTH PERCENTAGE AND BYTES FOR ACCURACY - Percentage may vary based on TotalBytes - Bytes provide exact count - Together give complete picture - Example: fmt.Printf("%.1f%% (%d/%d bytes)\n", progress.Percentage, progress.TransferredBytes, progress.TotalBytes)

  3. HANDLE ETA CAREFULLY - ETA is estimate based on current rate - May be inaccurate with variable rates - More accurate later in transfer - Never guarantee to user as absolute time - Example: fmt.Printf("Estimated completion: ~%s (may vary)\n", progress.EstimatedTimeRemaining.String())

  4. CHECK ERROR STATUS IN PROGRESS - HasError indicates chunk error - LastError provides error details - Streaming continues after chunk error - Use HasErrors() for overall error status - Example: if progress.HasError { fmt.Printf("Current chunk error: %v\n", progress.LastError) }

  5. DISTINGUISH PROGRESS FROM COMPLETION - GetProgress(): state during streaming - GetStats(): comprehensive final analysis - Use both for complete understanding - Example: progress := streaming.GetProgress() // Real-time stats := streaming.GetStats() // Final metrics

Related Methods and Workflows: 

Method                  Provides                    When to Use
──────────────────────────────────────────────────────────────────────
GetProgress()           Current progress snapshot   Real-time monitoring (this function)
GetStats()              Complete final statistics   After streaming, analysis
IsStreaming()           Active status boolean       State checking
GetWrapper()            HTTP response metadata      Response building
HasErrors()             Error existence boolean     Quick error check
Errors()                Error list                  Error analysis
WithCallback()          Per-chunk notifications     Immediate feedback

Common Polling Pattern: 

// ✓ RECOMMENDED: Fixed interval polling
ticker := time.NewTicker(100 * time.Millisecond)
for range ticker.C {
    progress := streaming.GetProgress() // Safe O(1)
    fmt.Printf("%.1f%% | ETA: %s\n",
        progress.Percentage,
        progress.EstimatedTimeRemaining.String())
}

// ⚠️  CAUTION: Busy polling
for streaming.IsStreaming() {
    progress := streaming.GetProgress() // Safe but high CPU
    // No sleep = 100% CPU usage
}

// ✓ RECOMMENDED: Event-based via callback
streaming.WithCallback(func(p *StreamProgress, err error) {
    // Called per chunk (less frequent than polling)
    fmt.Printf("Chunk %d processed\n", p.CurrentChunk)
})

See Also:

  • GetStats: Comprehensive statistics including compression, bandwidth analysis
  • IsStreaming: Check if streaming is currently active
  • GetWrapper: Access HTTP response metadata
  • WithCallback: Receive per-chunk progress notifications
  • Start: Initiates streaming and generates progress updates
  • Cancel: Stops streaming, progress reflects cancellation point

func (*StreamingWrapper) GetStats 

func (sw *StreamingWrapper) GetStats() *StreamingStats

GetStats returns a thread-safe copy of streaming statistics with computed compression metrics.

This function provides access to the complete streaming statistics accumulated up to the current point, with automatic calculation of the compression ratio based on current total bytes and compressed bytes. The compression ratio is computed dynamically at call time to ensure accuracy even if compression occurs during streaming. GetStats is thread-safe and can be called from any goroutine without synchronization; the internal mutex ensures consistent snapshot isolation. The returned StreamingStats is a defensive copy, not a reference; modifications to the returned stats do not affect the internal state or future calls. This is the primary low-level method for retrieving raw streaming metrics; GetStreamingStats() is a higher-level alias that calls this function. GetStats is non-blocking and safe to call frequently for real-time monitoring, diagnostics, or progress tracking during streaming. All metrics are maintained with precision appropriate to their data type: nanosecond precision for timing, byte-level precision for data sizes, and floating-point precision for ratios. Statistics are available immediately after Start() begins and remain stable after streaming completes or is cancelled.

Returns:

  • A pointer to a new StreamingStats structure containing a copy of all accumulated statistics.
  • If the streaming wrapper is nil, returns an empty StreamingStats{} with all fields zero-valued.
  • The CompressionRatio field is computed dynamically:
  • If TotalBytes == 0 or CompressedBytes == 0: CompressionRatio = 1.0 (no compression)
  • Otherwise: CompressionRatio = CompressedBytes / TotalBytes (as float64, range 0.0-1.0)
  • All other fields reflect the exact state at the moment of the call.
  • For ongoing streaming: returns partial statistics reflecting progress so far.
  • For completed streaming: returns final complete statistics.
  • Thread-safe: acquires RWMutex read lock to ensure consistent snapshot.
  • Copy semantics: returned stats are independent; no aliasing to internal state.
  • Non-blocking: O(1) operation after lock acquisition (fast read, not slow copy of large data).

Compression Ratio Calculation Semantics: 

Scenario                                    Compression Ratio Result    Rationale
────────────────────────────────────────────────────────────────────────────────
No compression configured                   1.0                        No reduction occurred
Compression not yet started                 1.0                        TotalBytes or CompressedBytes = 0
Compression in progress (partial data)      0.0 - 1.0                  Ratio of data processed
Compression completed (all data)            0.0 - 1.0                  Ratio of final result
TotalBytes = 0 (no data to compress)        1.0                        Guard condition
CompressedBytes = 0 (first read)            1.0                        Not yet compressed
CompressedBytes > TotalBytes (rare)         > 1.0                      Expansion (incompressible data)
COMP_NONE strategy                          1.0                        No compression applied
COMP_GZIP strategy (text)                   0.15 - 0.30                Typical 70-85% savings
COMP_DEFLATE strategy (text)                0.20 - 0.35                Typical 65-80% savings
COMP_GZIP strategy (binary)                 0.85 - 1.0                 Little to no reduction
COMP_GZIP strategy (images/video)           0.99 - 1.0                 Pre-compressed, expansion

Compression Ratio Interpretation: 

Ratio Value             Interpretation                  Typical Data Type
─────────────────────────────────────────────────────────────────────────
1.0                     No compression (100% of orig)   Incompressible or disabled
0.50 - 1.0              Some compression                Binary, mixed content
0.20 - 0.50             Good compression                Text, JSON, CSV, logs
0.10 - 0.20             Excellent compression           Highly repetitive text
< 0.10                  Exceptional compression         Very redundant data
> 1.0                   Expansion (compression failed)  Incompressible data

Statistics Copying Behavior: 

Operation                       Cost            Benefit                         Impact
──────────────────────────────────────────────────────────────────────────────
Shallow copy (used here)        O(1)            Fast, safe from mutation        Recommended
Deep copy (not used)            O(n)            Would be safer for slices       Unnecessary
Shared reference (not done)     O(0)            Fastest                         Unsafe (race)
Memory allocation                ~512 bytes      Small fixed structure           Minimal overhead
RWMutex lock duration           <1μs            Brief lock window               Minimal contention
Total call time                 1-5μs           Sub-microsecond operation       Negligible

Comparison with GetStreamingStats(): 

Aspect                  GetStats()              GetStreamingStats()
──────────────────────────────────────────────────────────────────────
Purpose                 Low-level raw access    High-level wrapper API
Compression ratio       Computed dynamically    Computed dynamically
Return type             *StreamingStats         *StreamingStats
Thread-safety           Yes (RWMutex)           Yes (calls GetStats)
Performance             Slightly faster         Identical (wrapper)
Recommendation          Internal/advanced use   Public API/recommended
Implementation          Direct access           Calls this function
Use case                Low-level monitoring    Standard monitoring

Thread-Safety Implementation: 

Component                   Protection                  Guarantee
──────────────────────────────────────────────────────────────────
sw.stats structure           RWMutex read lock           Consistent snapshot
CompressionRatio field       Lock held during calc       Atomicity of calculation
Memory copy (stats := *sw.stats) Snapshot isolation       Copy not affected by updates
Return pointer              Safe return                 No data race on return
Concurrent reads             Allowed by RWMutex         Multiple readers OK
Concurrent with writes       Blocked until write done    Consistent reads guaranteed
Lock acquisition             O(1) amortized             Negligible overhead
Lock duration                <1μs                       Brief, minimal contention

Statistics Copy Guarantee: 

Scenario                                    Return Value Guarantees
────────────────────────────────────────────────────────────────────
Two consecutive calls                       Different memory addresses
Modify returned stats                       Does not affect next GetStats() call
Returned stats with nil pointer             Safe to dereference
Multiple concurrent calls                   Each gets independent copy
Internal stats updated after call           Returned stats unchanged
Returned pointer valid after streaming      Pointer lifetime guaranteed

Example: 

// Example 1: Simple statistics retrieval with compression info
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(4)

// Start streaming
go streaming.Start(context.Background())

// Monitor statistics in real-time
time.Sleep(1 * time.Second)
stats := streaming.GetStats()

if stats.TotalBytes > 0 {
    compressionSavings := (1.0 - stats.CompressionRatio) * 100
    fmt.Printf("Progress: %.2f MB / %.2f MB\n",
        float64(stats.TransferredBytes) / 1024 / 1024,
        float64(stats.TotalBytes) / 1024 / 1024)
    fmt.Printf("Compression: %.1f%% savings (ratio: %.2f)\n",
        compressionSavings, stats.CompressionRatio)
}

// Example 2: Real-time monitoring loop with compression tracking
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/bulk-data").
    WithStreaming(dataExport, nil).
    WithChunkSize(5 * 1024 * 1024).
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(8)

// Start streaming in background
done := make(chan bool)
go func() {
    streaming.Start(context.Background())
    done <- true
}()

// Monitor progress with live compression stats
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

for {
    select {
    case <-ticker.C:
        if !streaming.IsStreaming() {
            break
        }

        // Get stats snapshot (O(1) operation)
        stats := streaming.GetStats()
        progress := streaming.GetProgress()

        originalMB := float64(stats.TotalBytes) / 1024 / 1024
        compressedMB := float64(stats.CompressedBytes) / 1024 / 1024
        saved := (1.0 - stats.CompressionRatio) * 100

        fmt.Printf("\rProgress: %.1f%% | Original: %.2f MB → Compressed: %.2f MB (%.1f%% saved)",
            float64(progress.Percentage), originalMB, compressedMB, saved)
    case <-done:
        fmt.Println("\nStreaming completed")
        return
    }
}

// Example 3: Compression effectiveness analysis
func AnalyzeCompressionEffectiveness(streaming *StreamingWrapper) {
    stats := streaming.GetStats()

    if stats.TotalBytes == 0 {
        fmt.Println("No data transferred")
        return
    }

    compressionRatio := stats.CompressionRatio
    savings := (1.0 - compressionRatio) * 100

    fmt.Printf("Compression Analysis:\n")
    fmt.Printf("  Original size:    %.2f MB\n",
        float64(stats.TotalBytes) / 1024 / 1024)
    fmt.Printf("  Compressed size:  %.2f MB\n",
        float64(stats.CompressedBytes) / 1024 / 1024)
    fmt.Printf("  Compression ratio: %.4f (%.1f%% reduction)\n",
        compressionRatio, savings)

    // Compression effectiveness assessment
    switch {
    case compressionRatio >= 0.99:
        fmt.Println("  Assessment: No compression benefit (incompressible data)")
    case compressionRatio >= 0.80:
        fmt.Println("  Assessment: Low compression benefit")
    case compressionRatio >= 0.50:
        fmt.Println("  Assessment: Moderate compression benefit")
    case compressionRatio >= 0.20:
        fmt.Println("  Assessment: Good compression benefit")
    default:
        fmt.Println("  Assessment: Excellent compression benefit")
    }

    // Time cost analysis
    if stats.ElapsedTime.Seconds() > 0 {
        originalMBps := float64(stats.TotalBytes) / 1024 / 1024 / stats.ElapsedTime.Seconds()
        compressedMBps := float64(stats.CompressedBytes) / 1024 / 1024 / stats.ElapsedTime.Seconds()
        timeOverhead := (float64(stats.CPUTime.Milliseconds()) / stats.ElapsedTime.Milliseconds()) * 100

        fmt.Printf("  Original throughput:    %.2f MB/s\n", originalMBps)
        fmt.Printf("  Compressed throughput:  %.2f MB/s\n", compressedMBps)
        fmt.Printf("  CPU overhead:           %.1f%%\n", timeOverhead)
    }
}

// Example 4: Statistics mutation safety demonstration
func DemonstrateCopySafety(streaming *StreamingWrapper) {
    // Get first snapshot
    stats1 := streaming.GetStats()
    fmt.Printf("Stats1: %d bytes\n", stats1.TotalBytes)

    // Mutate returned copy (does not affect streaming)
    stats1.TotalBytes = 999999

    // Get second snapshot (should be unaffected by mutation)
    stats2 := streaming.GetStats()
    fmt.Printf("Stats2: %d bytes (unaffected by mutation)\n", stats2.TotalBytes)

    // Verify original streaming state unchanged
    assert(stats2.TotalBytes != 999999, "Stats should not be affected by returned copy mutation")
}

// Example 5: Performance-critical monitoring
func HighFrequencyMonitoring(streaming *StreamingWrapper) {
    // GetStats() is O(1) and safe to call very frequently
    ticker := time.NewTicker(100 * time.Millisecond) // 10 calls/second
    defer ticker.Stop()

    for i := 0; i < 10; i++ {
        select {
        case <-ticker.C:
            stats := streaming.GetStats() // Very fast O(1) call

            // Update metrics in real-time
            fmt.Printf("Byte %d: %d/%d (%.1f%%) | Compression: %.2f\n",
                i,
                stats.TransferredBytes,
                stats.TotalBytes,
                float64(stats.TransferredBytes) / float64(stats.TotalBytes) * 100,
                stats.CompressionRatio)

            if !streaming.IsStreaming() {
                fmt.Println("Streaming complete")
                return
            }
        }
    }
}

// Example 6: Detailed statistics report with copy verification
func GenerateStatisticsReport(streaming *StreamingWrapper) string {
    stats := streaming.GetStats()

    var report strings.Builder

    report.WriteString("=== STREAMING STATISTICS REPORT ===\n")
    report.WriteString(fmt.Sprintf("Generated: %s\n\n", time.Now().Format(time.RFC3339)))

    // Data metrics
    report.WriteString("DATA TRANSFER:\n")
    report.WriteString(fmt.Sprintf("  Total bytes:       %d (%.2f MB)\n",
        stats.TotalBytes, float64(stats.TotalBytes) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Transferred:       %d (%.2f MB)\n",
        stats.TransferredBytes, float64(stats.TransferredBytes) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Failed:            %d bytes\n",
        stats.FailedBytes))

    // Compression metrics
    report.WriteString("\nCOMPRESSION:\n")
    report.WriteString(fmt.Sprintf("  Original size:     %.2f MB\n",
        float64(stats.TotalBytes) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Compressed size:   %.2f MB\n",
        float64(stats.CompressedBytes) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Compression ratio: %.4f\n",
        stats.CompressionRatio))
    report.WriteString(fmt.Sprintf("  Savings:           %.1f%%\n",
        (1.0 - stats.CompressionRatio) * 100))
    report.WriteString(fmt.Sprintf("  Type:              %s\n",
        stats.CompressionType))

    // Performance metrics
    report.WriteString("\nPERFORMANCE:\n")
    report.WriteString(fmt.Sprintf("  Duration:          %.2f seconds\n",
        stats.ElapsedTime.Seconds()))
    report.WriteString(fmt.Sprintf("  Avg bandwidth:     %.2f MB/s\n",
        float64(stats.AverageBandwidth) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Peak bandwidth:    %.2f MB/s\n",
        float64(stats.PeakBandwidth) / 1024 / 1024))
    report.WriteString(fmt.Sprintf("  Min bandwidth:     %.2f MB/s\n",
        float64(stats.MinimumBandwidth) / 1024 / 1024))

    // Chunk metrics
    report.WriteString("\nCHUNK PROCESSING:\n")
    report.WriteString(fmt.Sprintf("  Total chunks:      %d\n",
        stats.TotalChunks))
    report.WriteString(fmt.Sprintf("  Processed:         %d\n",
        stats.ProcessedChunks))
    report.WriteString(fmt.Sprintf("  Failed:            %d\n",
        stats.FailedChunks))
    report.WriteString(fmt.Sprintf("  Success rate:      %.1f%%\n",
        float64(stats.ProcessedChunks) / float64(stats.TotalChunks) * 100))

    // Error metrics
    if stats.HasErrors {
        report.WriteString("\nERRORS:\n")
        report.WriteString(fmt.Sprintf("  Count:             %d\n",
            stats.ErrorCount))
        report.WriteString(fmt.Sprintf("  First error:       %v\n",
            stats.FirstError))
        report.WriteString(fmt.Sprintf("  Last error:        %v\n",
            stats.LastError))
    }

    return report.String()
}

Compression Ratio Edge Cases: 

Condition                           Result              Expected Behavior
────────────────────────────────────────────────────────────────────────
TotalBytes = 0                      1.0                 Guard: avoid division by zero
CompressedBytes = 0                 1.0                 Guard: compression not started
CompressedBytes = TotalBytes        1.0                 No compression occurred
CompressedBytes > TotalBytes        > 1.0               Data expanded (incompressible)
CompressedBytes < TotalBytes        < 1.0               Compression succeeded
Both = 0                            1.0                 Guard: no transfer occurred
Negative values (should not occur)  Calculated as-is    Undefined (data consistency issue)

Performance Characteristics: 

Operation                       Time Complexity    Space Complexity    Actual Cost
──────────────────────────────────────────────────────────────────────────────
RWMutex read lock acquisition   O(1) amortized     None                <1μs typical
Memory copy (stats := *sw.stats) O(1)               O(1) (fixed struct)  ~512 bytes copy
CompressionRatio calculation     O(1)               None                <1μs
Return statement                 O(1)               None                <1μs
Total GetStats() call            O(1)               O(1)                1-5μs typical
Lock contention (high concurrency) O(1)             None                <10μs worst case

Thread-Safety Guarantees: 

Guarantee                                           Assurance
─────────────────────────────────────────────────────────────────────
No data race on reads                              RWMutex read lock
Returned copy independent of internal state        Shallow copy (new address)
CompressionRatio consistent with other fields      Calculated under lock
Multiple concurrent GetStats() calls safe          Allowed by RWMutex
Safe to call from streaming goroutine              RWMutex allows concurrent reads
Safe to call from monitoring goroutines            Parallel readers supported
Copy valid after streaming completes               Copy lifetime independent
No leaks or dangling pointers                      Automatic memory management

Best Practices:

  1. CALL DURING OR AFTER STREAMING - Statistics available immediately - Partial stats during streaming, complete after - Safe to call frequently for monitoring - Pattern: stats := streaming.GetStats() ratio := stats.CompressionRatio // Automatically computed

  2. USE FOR COMPRESSION ANALYSIS - CompressionRatio computed dynamically - Always current as of call time - Safe for repeated calls - Example: stats1 := streaming.GetStats() time.Sleep(100ms) stats2 := streaming.GetStats() // ratio reflects current compression state

  3. MONITOR SAFELY IN TIGHT LOOPS - O(1) operation, safe to call frequently - Each call gets independent copy - No mutual exclusion issues - Example: for streaming.IsStreaming() { stats := streaming.GetStats() // Safe O(1) call // Use stats }

  4. DON'T RELY ON COPY LIFETIME - Copy is valid indefinitely - But reflects state only at call time - Call again for updated metrics - Pattern: stats := streaming.GetStats() // Snapshot at T1 // stats won't update as streaming progresses stats = streaming.GetStats() // Get new snapshot at T2

  5. COMBINE COMPRESSION METRICS WITH BANDWIDTH - CompressionRatio shows space efficiency - AverageBandwidth shows time efficiency - Together show transfer effectiveness - Example: ratio := stats.CompressionRatio bandwidth := float64(stats.AverageBandwidth) / 1024 / 1024 fmt.Printf("Compression: %.1f%%, Bandwidth: %.2f MB/s\n", (1-ratio)*100, bandwidth)

Related Methods and Workflows: 

Workflow Stage              Method to Call              What it Provides
───────────────────────────────────────────────────────────────────────────
Real-time progress          GetProgress()               Current chunk, bytes, %
Real-time statistics        GetStats()                  Full metrics (this function)
Final analysis              GetStreamingStats()         Complete stats (alias)
Error tracking              Errors(), HasErrors()       Error list/existence
Response building           GetWrapper()                HTTP metadata
State checking              IsStreaming()               Is transfer active

Differences from Previous Snapshots: 

Call Number    TotalBytes    CompressedBytes    CompressionRatio
──────────────────────────────────────────────────────────────────
1st call       1MB           0.5MB              0.5000
2nd call (100ms later) 2MB  0.9MB              0.4500
3rd call (200ms later) 2MB  1.0MB              0.5000
// Each call shows current state; ratio reflects current compression effectiveness

See Also:

  • GetStreamingStats: Higher-level alias for GetStats (calls this function)
  • GetProgress: Real-time progress without compression ratio
  • CompressionRatio: Automatically computed as CompressedBytes / TotalBytes
  • WithCompressionType: Configure compression algorithm before streaming
  • Start: Initiates streaming and accumulates statistics

func (*StreamingWrapper) GetStreamingProgress 

func (sw *StreamingWrapper) GetStreamingProgress() *StreamProgress

GetStreamingProgress returns current progress information from an ongoing or completed streaming operation.

This function provides high-level access to real-time progress metrics through a convenient alias to GetProgress(). It returns a defensive copy of the current streaming state including chunk counts, bytes transferred, percentage complete, elapsed time, estimated time remaining, transfer rate, and any transient errors. GetStreamingProgress is the primary public API method for progress monitoring; GetProgress() is the underlying low-level implementation. This function is thread-safe, non-blocking, and optimized for frequent calls including high-frequency polling (100+ calls per second). The returned StreamProgress is independent; modifications do not affect internal streaming state. Progress information is available immediately when Start() begins and remains accessible after streaming completes or is cancelled. This is the recommended method for building progress bars, displaying ETAs, monitoring bandwidth, implementing progress-based controls, and tracking real-time transfer metrics in production systems.

Returns:

  • A pointer to a new StreamProgress structure containing a snapshot of current progress metrics.
  • If the streaming wrapper is nil, returns an empty StreamProgress{} with all fields zero-valued.
  • The returned StreamProgress reflects the exact state at the moment of the call.
  • For ongoing streaming: returns current live metrics that change with subsequent calls.
  • For completed/cancelled streaming: returns final stable metrics.
  • Thread-safe: uses internal RWMutex for consistent snapshot isolation.
  • Copy semantics: returned progress is independent; modifications do not affect streaming.
  • Non-blocking: O(1) complexity, safe for high-frequency polling without performance impact.
  • All percentage values are in range 0.0-100.0 (or 0.0-1.0 as documented).
  • All byte counts use int64 to support transfers up to 9.2 exabytes.

Functional Equivalence: 

GetStreamingProgress() ≡ GetProgress()

Both functions return identical data and have identical performance characteristics.
GetStreamingProgress() is the recommended public API; GetProgress() is the lower-level implementation.
Use either function interchangeably; GetStreamingProgress() provides semantic clarity for high-level use.

StreamProgress Contents Overview: 

Category                Information Available
──────────────────────────────────────────────────────────────────
Chunk Information        Current chunk #, total chunks, chunk size
Data Transfer            Bytes transferred, total bytes, remaining
Progress Metrics         Percentage complete, human-readable percentage
Timing                   Start time, elapsed time, estimated time remaining
Transfer Rate            Current bandwidth (B/s and MB/s)
Error State              Current error (if any), error flag

Use Cases and Patterns: 

Use Case                            Recommended Pattern
────────────────────────────────────────────────────────────────────
Progress bar display                Get percentage: progress.Percentage
ETA display                         Get ETA: progress.EstimatedTimeRemaining
Speed monitoring                    Get rate: float64(progress.TransferRate) / 1024 / 1024
Real-time statistics               Get chunk/bytes: progress.CurrentChunk, progress.TransferredBytes
Progress-based cancellation         if progress.Percentage > threshold: cancel()
Error detection                     if progress.HasError: handle(progress.LastError)
Bandwidth analysis                  Track TransferRate over time
Memory estimation                   currentMemory = progress.CurrentChunk * ChunkSize
Multi-transfer tracking             Aggregate progress from multiple transfers
Progress notification               Emit event with progress.Percentage

Example: 

// Example 1: Simple progress retrieval and display
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4)

// Start streaming in background
done := make(chan *wrapper)
go func() {
    result := streaming.Start(context.Background())
    done <- result
}()

// Monitor with high-level API
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

for {
    select {
    case <-ticker.C:
        if !streaming.IsStreaming() {
            break
        }

        // Use high-level GetStreamingProgress() API
        progress := streaming.GetStreamingProgress()

        fmt.Printf("\rDownload: %.1f%% | %d / %d chunks | Speed: %.2f MB/s | ETA: %s",
            progress.Percentage,
            progress.CurrentChunk,
            progress.TotalChunks,
            float64(progress.TransferRate) / 1024 / 1024,
            progress.EstimatedTimeRemaining.String())
    case result := <-done:
        fmt.Println("\nDownload completed")
        return
    }
}

// Example 2: Progress monitoring with progress bar UI
func DisplayProgressUI(streaming *StreamingWrapper) {
    ticker := time.NewTicker(100 * time.Millisecond)
    defer ticker.Stop()

    for range ticker.C {
        if !streaming.IsStreaming() {
            fmt.Println("\n[✓] Transfer completed")
            break
        }

        // Get current progress using high-level API
        progress := streaming.GetStreamingProgress()

        // Draw visual progress bar
        barLength := 50
        filledLength := int(float64(barLength) * progress.Percentage / 100.0)
        emptyLength := barLength - filledLength

        bar := strings.Repeat("█", filledLength) + strings.Repeat("░", emptyLength)

        // Format detailed status line
        fmt.Printf("\r[%s] %6.2f%% | Chunk %4d / %4d | Speed: %7.2f MB/s | ETA: %8s | Total: %8s",
            bar,
            progress.Percentage,
            progress.CurrentChunk,
            progress.TotalChunks,
            float64(progress.TransferRate) / 1024 / 1024,
            progress.EstimatedTimeRemaining.String(),
            formatBytes(progress.TotalBytes))
    }
}

// Example 3: High-level progress monitoring with statistics integration
func MonitorWithStatistics(streaming *StreamingWrapper) {
    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        if !streaming.IsStreaming() {
            break
        }

        // Get real-time progress
        progress := streaming.GetStreamingProgress()

        // Get cumulative statistics
        stats := streaming.GetStreamingStats()

        fmt.Printf("Status Report:\n")
        fmt.Printf("  Progress:       %.1f%% (%d / %d chunks)\n",
            progress.Percentage, progress.CurrentChunk, progress.TotalChunks)
        fmt.Printf("  Data:           %.2f MB / %.2f MB\n",
            float64(progress.TransferredBytes) / 1024 / 1024,
            float64(progress.TotalBytes) / 1024 / 1024)
        fmt.Printf("  Speed:          %.2f MB/s (avg: %.2f MB/s)\n",
            float64(progress.TransferRate) / 1024 / 1024,
            float64(stats.AverageBandwidth) / 1024 / 1024)
        fmt.Printf("  Time:           Elapsed: %s | ETA: %s\n",
            progress.ElapsedTime.String(),
            progress.EstimatedTimeRemaining.String())
        fmt.Printf("  Errors:         %d / %d chunks\n",
            stats.FailedChunks, stats.TotalChunks)
    }
}

// Example 4: Progress-based adaptive control
func StreamWithAdaptiveControl(streaming *StreamingWrapper) {
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    lastBandwidth := float64(0)

    for range ticker.C {
        progress := streaming.GetStreamingProgress()

        currentBandwidth := float64(progress.TransferRate) / 1024 / 1024

        // Adaptive logging: log more frequently if bandwidth drops
        if currentBandwidth < lastBandwidth * 0.8 {
            fmt.Printf("\n[!] Bandwidth drop detected: %.2f MB/s → %.2f MB/s\n",
                lastBandwidth, currentBandwidth)
        }

        // Progress-based decisions
        switch {
        case progress.Percentage > 95:
            fmt.Printf("\r[●] Almost done! %.1f%% | ETA: ~%.0f seconds",
                progress.Percentage,
                progress.EstimatedTimeRemaining.Seconds())
        case progress.Percentage > 50:
            fmt.Printf("\r[◕] Halfway! %.1f%% | ETA: %s",
                progress.Percentage,
                progress.EstimatedTimeRemaining.String())
        case progress.Percentage > 0:
            fmt.Printf("\r[◐] Started %.1f%% | ETA: %s",
                progress.Percentage,
                progress.EstimatedTimeRemaining.String())
        }

        // Check for errors
        if progress.HasError {
            fmt.Printf("\n[!] Error on chunk %d: %v\n", progress.CurrentChunk, progress.LastError)
        }

        lastBandwidth = currentBandwidth

        if !streaming.IsStreaming() {
            fmt.Println("\n[✓] Transfer complete")
            break
        }
    }
}

// Example 5: Progress aggregation for multiple transfers
type MultiTransferProgress struct {
    transfers map[string]*StreamingWrapper
    total     TransferMetrics
}

type TransferMetrics struct {
    TotalBytes      int64
    TransferredBytes int64
    ActiveCount     int
    CompletedCount  int
}

func (mtp *MultiTransferProgress) UpdateMetrics() TransferMetrics {
    mtp.total = TransferMetrics{}

    for name, streaming := range mtp.transfers {
        progress := streaming.GetStreamingProgress()

        mtp.total.TotalBytes += progress.TotalBytes
        mtp.total.TransferredBytes += progress.TransferredBytes

        if streaming.IsStreaming() {
            mtp.total.ActiveCount++
        } else {
            mtp.total.CompletedCount++
        }
    }

    return mtp.total
}

func (mtp *MultiTransferProgress) DisplayOverall() {
    metrics := mtp.UpdateMetrics()

    overallPercent := 0.0
    if metrics.TotalBytes > 0 {
        overallPercent = float64(metrics.TransferredBytes) / float64(metrics.TotalBytes) * 100.0
    }

    fmt.Printf("Overall Progress: %.1f%% (%d / %d transfers active)\n",
        overallPercent, metrics.ActiveCount, metrics.CompletedCount)
}

// Example 6: Complete production-ready progress monitoring
type ProgressMonitor struct {
    streaming      *StreamingWrapper
    updateInterval time.Duration
    output         io.Writer
    startTime      time.Time
}

func NewProgressMonitor(streaming *StreamingWrapper, updateInterval time.Duration) *ProgressMonitor {
    return &ProgressMonitor{
        streaming:      streaming,
        updateInterval: updateInterval,
        output:         os.Stdout,
        startTime:      time.Now(),
    }
}

func (pm *ProgressMonitor) Monitor(ctx context.Context) {
    ticker := time.NewTicker(pm.updateInterval)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            return
        case <-ticker.C:
            pm.displayProgress()

            if !pm.streaming.IsStreaming() {
                pm.displayFinal()
                return
            }
        }
    }
}

func (pm *ProgressMonitor) displayProgress() {
    progress := pm.streaming.GetStreamingProgress()

    // Visual progress bar
    barWidth := 40
    filledWidth := int(float64(barWidth) * progress.Percentage / 100.0)
    bar := strings.Repeat("=", filledWidth) + strings.Repeat("-", barWidth-filledWidth)

    // Speed indicator
    speedMBps := float64(progress.TransferRate) / 1024 / 1024
    speedIndicator := "↓"
    if speedMBps > 100 {
        speedIndicator = "↓↓"
    }

    // Format output
    output := fmt.Sprintf(
        "\r[%s] %5.1f%% | %s %6.1f MB/s | ETA: %8s | %s / %s",
        bar,
        progress.Percentage,
        speedIndicator,
        speedMBps,
        progress.EstimatedTimeRemaining.String(),
        formatBytes(progress.TransferredBytes),
        formatBytes(progress.TotalBytes),
    )

    fmt.Fprint(pm.output, output)
}

func (pm *ProgressMonitor) displayFinal() {
    stats := pm.streaming.GetStreamingStats()
    progress := pm.streaming.GetStreamingProgress()

    fmt.Fprintf(pm.output, "\n✓ Transfer completed in %.2f seconds\n", stats.ElapsedTime.Seconds())
    fmt.Fprintf(pm.output, "  Total:       %s\n", formatBytes(progress.TotalBytes))
    fmt.Fprintf(pm.output, "  Chunks:      %d\n", progress.TotalChunks)
    fmt.Fprintf(pm.output, "  Speed:       %.2f MB/s (avg)\n",
        float64(stats.AverageBandwidth) / 1024 / 1024)

    if stats.HasErrors {
        fmt.Fprintf(pm.output, "  Errors:      %d\n", stats.ErrorCount)
    }
}

Public API Recommendation: 

For Calling Code              Use This Function         Why
──────────────────────────────────────────────────────────────────
Application code              GetStreamingProgress()    High-level, semantic clarity
UI components                 GetStreamingProgress()    Clear intent, recommended API
Progress bars                 GetStreamingProgress()    Standard pattern
Monitoring systems            GetStreamingProgress()    Public API contract
High-level streaming logic    GetStreamingProgress()    Clear naming, recommended

Internal streaming impl       GetProgress()             Direct access, faster
Low-level performance code    GetProgress()             Avoids indirection
Performance-critical paths    GetProgress()             Negligible difference

Semantics and Guarantees: 

Aspect                          Guarantee / Behavior
──────────────────────────────────────────────────────────────────
Return type                     *StreamProgress (same as GetProgress)
Thread-safety                   Yes (RWMutex protected)
Copy semantics                  Independent copy (safe from mutation)
Performance                     O(1) constant time (same as GetProgress)
Call frequency safety           100+ calls/second safe (same as GetProgress)
Functional equivalence          Identical to GetProgress (alias pattern)
Semantic clarity                Enhanced (public API naming)
Implementation                  Direct call to GetProgress()

Performance Profile: 

Metric                          Value / Characteristic
──────────────────────────────────────────────────────────────────
Time complexity                 O(1) constant
Space complexity                O(1) fixed (StreamProgress struct)
Typical call duration           1-3 microseconds
Memory allocation               ~200 bytes per call
Lock contention                 Minimal (read-only)
Concurrent call support         Hundreds per second
Call frequency recommendation   1-10 Hz for UI (100-500 ms intervals)
High-frequency monitoring       Up to 100+ Hz feasible
Safe for real-time systems      Yes
Suitable for animation frames   Yes (60+ FPS capable)

Integration Pattern (Recommended): 

// Typical integration pattern in a streaming application
func DownloadWithProgress(url string, destination string) error {
    // Setup
    reader := createReader(url)           // Data source
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/download").
        WithStreaming(reader, nil).
        WithChunkSize(1024 * 1024)

    // Background streaming
    done := make(chan error)
    go func() {
        result := streaming.Start(context.Background())
        done <- result.Error()
    }()

    // Progress monitoring (main thread / UI thread)
    ticker := time.NewTicker(100 * time.Millisecond)
    for {
        select {
        case <-ticker.C:
            // Get current progress using public API
            progress := streaming.GetStreamingProgress()
            updateUI(progress.Percentage, progress.EstimatedTimeRemaining)
        case err := <-done:
            ticker.Stop()
            return err
        }
    }
}

Comparison with Alternatives: 

Method                      Purpose                         When to Use
─────────────────────────────────────────────────────────────────────────
GetStreamingProgress()      Real-time progress (public API) Application code
GetProgress()               Real-time progress (impl)       Internal code
GetStreamingStats()         Complete statistics             Analysis/reporting
IsStreaming()               Check if active                 State queries
WithCallback()              Per-chunk notifications         Immediate feedback
Errors()                    All errors                      Error analysis

Recommended Polling Frequencies: 

Use Case                        Frequency           Interval
──────────────────────────────────────────────────────────────────
Progress bar (CLI)              2-5 Hz              200-500ms
Web UI progress indicator       1-2 Hz              500ms-1s
Real-time monitoring dashboard  10 Hz               100ms
Mobile app progress display     2-5 Hz              200-500ms
Detailed diagnostics            10-20 Hz            50-100ms
Animation/game frame rate       60+ Hz              16ms
High-frequency monitoring       100+ Hz             10ms
Low-power/battery-conscious     0.5-1 Hz            1-2s

See Also:

  • GetProgress: Low-level implementation (functional equivalent)
  • GetStreamingStats: Complete statistics and performance metrics
  • IsStreaming: Check if streaming is currently active
  • WithCallback: Receive per-chunk progress notifications
  • GetWrapper: Access HTTP response metadata
  • Start: Initiates streaming and generates progress
  • Cancel: Stops streaming operation

func (*StreamingWrapper) GetStreamingStats 

func (sw *StreamingWrapper) GetStreamingStats() *StreamingStats

GetStreamingStats returns complete statistics about the streaming operation accumulated up to the current point.

This function provides detailed metrics and analytics about the streaming transfer including total bytes transferred, compression statistics, bandwidth metrics, chunk processing information, error counts, timing data, and resource utilization. The statistics accumulate throughout the streaming operation and represent the state at the time of the call. For ongoing streaming, GetStreamingStats() returns partial statistics reflecting progress so far; for completed streaming, it returns complete final statistics. This is the primary method for obtaining comprehensive streaming performance data, diagnostics, and analytics. GetStreamingStats is thread-safe and can be called from any goroutine during or after streaming without blocking the operation. The returned StreamingStats structure is a snapshot copy; modifications to the returned stats do not affect the internal state. All statistics are maintained with microsecond precision for timing measurements and byte-level accuracy for data transfers.

Returns:

  • A pointer to a StreamingStats structure containing complete streaming statistics.
  • Returns an empty StreamingStats{} if the streaming wrapper is nil.
  • For ongoing streaming: returns partial statistics reflecting progress to current point.
  • For completed streaming: returns final complete statistics from entire operation.
  • All timestamps are in UTC with nanosecond precision (time.Time format).
  • All byte counts and rates are 64-bit integers (int64) for large transfer support.
  • All percentage and ratio values are floating-point (0.0-1.0 or 0-100.0) as documented.
  • Thread-safe: safe to call concurrently from multiple goroutines.
  • Snapshot semantics: returned stats are independent; modifications do not affect streaming.

StreamingStats Structure Contents: 

Field Category          Field Name                      Type        Purpose
─────────────────────────────────────────────────────────────────────────────────────
Timing Information
                        StartTime                       time.Time   When streaming began
                        EndTime                         time.Time   When streaming ended
                        ElapsedTime                     time.Duration Duration of operation

Data Transfer
                        TotalBytes                      int64       Total bytes to transfer
                        TransferredBytes                int64       Bytes actually transferred
                        FailedBytes                     int64       Bytes not transferred

Chunk Processing
                        TotalChunks                     int64       Total chunks to process
                        ProcessedChunks                 int64       Chunks processed successfully
                        FailedChunks                    int64       Chunks that failed

Compression Data
                        OriginalSize                    int64       Size before compression
                        CompressedSize                  int64       Size after compression
                        CompressionRatio               float64     compressed/original (0.0-1.0)
                        CompressionType                string      COMP_NONE, COMP_GZIP, COMP_DEFLATE

Bandwidth Metrics
                        AverageBandwidth               int64       Average B/s for entire transfer
                        PeakBandwidth                  int64       Maximum B/s during transfer
                        MinimumBandwidth               int64       Minimum B/s during transfer
                        ThrottleRate                   int64       Configured throttle rate

Error Tracking
                        Errors                         []error     All errors that occurred
                        ErrorCount                     int64       Total number of errors
                        HasErrors                      bool        Whether any errors occurred
                        FirstError                     error       First error encountered (if any)
                        LastError                      error       Most recent error (if any)

Resource Utilization
                        CPUTime                        time.Duration Time spent on CPU
                        MemoryAllocated                int64       Memory allocated during transfer
                        MaxMemoryUsage                 int64       Peak memory during transfer
                        BufferPoolHits                 int64       Count of buffer pool reuses
                        BufferPoolMisses               int64       Count of buffer pool misses

Configuration
                        ChunkSize                      int64       Configured chunk size
                        MaxConcurrentChunks            int64       Max parallel chunk processing
                        StreamingStrategy              string      Strategy used (BUFFERED, DIRECT, etc)
                        UseBufferPool                  bool        Whether buffer pooling was enabled

Example: 

// Example 1: Simple statistics retrieval after streaming
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4)

result := streaming.Start(context.Background())

// Retrieve complete statistics
stats := streaming.GetStreamingStats()

fmt.Printf("Streaming Statistics:\n")
fmt.Printf("  Total bytes: %d\n", stats.TotalBytes)
fmt.Printf("  Transferred: %d\n", stats.TransferredBytes)
fmt.Printf("  Duration: %s\n", stats.ElapsedTime)
fmt.Printf("  Chunks processed: %d/%d\n",
    stats.ProcessedChunks, stats.TotalChunks)
fmt.Printf("  Average bandwidth: %.2f MB/s\n",
    float64(stats.AverageBandwidth) / 1024 / 1024)

// Example 2: Comprehensive statistics analysis
httpResp, _ := http.Get("https://api.example.com/largefile")
defer httpResp.Body.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/proxy/remote-file").
    WithStreaming(httpResp.Body, nil).
    WithChunkSize(512 * 1024).
    WithMaxConcurrentChunks(4).
    WithCompressionType(COMP_GZIP).
    WithThrottleRate(1024 * 1024) // 1MB/s

result := streaming.Start(context.Background())

// Detailed statistics analysis
stats := streaming.GetStreamingStats()

if stats.TotalBytes > 0 {
    successRate := float64(stats.ProcessedChunks) / float64(stats.TotalChunks) * 100
    compressionSavings := (1.0 - stats.CompressionRatio) * 100

    fmt.Printf("=== TRANSFER STATISTICS ===\n")
    fmt.Printf("Size:\n")
    fmt.Printf("  Original:    %.2f MB\n", float64(stats.OriginalSize) / 1024 / 1024)
    fmt.Printf("  Compressed:  %.2f MB\n", float64(stats.CompressedSize) / 1024 / 1024)
    fmt.Printf("  Savings:     %.1f%%\n", compressionSavings)

    fmt.Printf("Chunks:\n")
    fmt.Printf("  Total:       %d\n", stats.TotalChunks)
    fmt.Printf("  Processed:   %d\n", stats.ProcessedChunks)
    fmt.Printf("  Failed:      %d\n", stats.FailedChunks)
    fmt.Printf("  Success:     %.1f%%\n", successRate)

    fmt.Printf("Performance:\n")
    fmt.Printf("  Duration:    %.2f seconds\n", stats.ElapsedTime.Seconds())
    fmt.Printf("  Avg Rate:    %.2f MB/s\n",
        float64(stats.AverageBandwidth) / 1024 / 1024)
    fmt.Printf("  Peak Rate:   %.2f MB/s\n",
        float64(stats.PeakBandwidth) / 1024 / 1024)
    fmt.Printf("  Min Rate:    %.2f MB/s\n",
        float64(stats.MinimumBandwidth) / 1024 / 1024)

    if stats.HasErrors {
        fmt.Printf("Errors:\n")
        fmt.Printf("  Count:       %d\n", stats.ErrorCount)
        fmt.Printf("  First:       %v\n", stats.FirstError)
        fmt.Printf("  Last:        %v\n", stats.LastError)
    }
}

// Example 3: Performance monitoring and diagnostics
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/bulk-data").
    WithCustomFieldKV("export_id", "exp-2025-1114-001").
    WithStreaming(dataExport, nil).
    WithChunkSize(10 * 1024 * 1024).
    WithMaxConcurrentChunks(8).
    WithCompressionType(COMP_GZIP).
    WithBufferPooling(true)

result := streaming.Start(context.Background())
stats := streaming.GetStreamingStats()

// Build diagnostic report
fmt.Printf("Export exp-2025-1114-001 Report\n")
fmt.Printf("================================\n")
fmt.Printf("Timing: %s (%.2f seconds)\n",
    stats.EndTime.Sub(stats.StartTime),
    stats.ElapsedTime.Seconds())
fmt.Printf("Data: %.2f MB → %.2f MB (%.1f%% compression)\n",
    float64(stats.OriginalSize) / 1024 / 1024,
    float64(stats.CompressedSize) / 1024 / 1024,
    (1.0 - stats.CompressionRatio) * 100)
fmt.Printf("Chunks: %d processed, %d failed\n",
    stats.ProcessedChunks, stats.FailedChunks)
fmt.Printf("Bandwidth: %d B/s (avg) | %d B/s (peak) | %d B/s (throttle)\n",
    stats.AverageBandwidth, stats.PeakBandwidth, stats.ThrottleRate)
fmt.Printf("Resources: %d MB allocated | %d MB peak\n",
    stats.MemoryAllocated / 1024 / 1024,
    stats.MaxMemoryUsage / 1024 / 1024)
fmt.Printf("Errors: %d total\n", stats.ErrorCount)

// Example 4: Statistics in response metadata
func BuildStatisticsResponse(streaming *StreamingWrapper) *wrapper {
    stats := streaming.GetStreamingStats()

    return streaming.GetWrapper().
        WithStatusCode(200).
        WithMessage("Streaming completed with statistics").
        WithDebuggingKV("total_bytes", stats.TotalBytes).
        WithDebuggingKV("transferred_bytes", stats.TransferredBytes).
        WithDebuggingKV("chunks_total", stats.TotalChunks).
        WithDebuggingKV("chunks_processed", stats.ProcessedChunks).
        WithDebuggingKV("chunks_failed", stats.FailedChunks).
        WithDebuggingKVf("duration_seconds", "%.2f", stats.ElapsedTime.Seconds()).
        WithDebuggingKVf("avg_bandwidth_mbps", "%.2f",
            float64(stats.AverageBandwidth) / 1024 / 1024).
        WithDebuggingKVf("compression_ratio_percent", "%.1f",
            (1.0 - stats.CompressionRatio) * 100).
        WithDebuggingKV("error_count", stats.ErrorCount)
}

// Example 5: Conditional statistics reporting based on transfer size
func ReportStatisticsIfLarge(streaming *StreamingWrapper) {
    stats := streaming.GetStreamingStats()

    // Only detailed report for large transfers
    const largeTransferThreshold = 100 * 1024 * 1024 // 100MB

    if stats.TotalBytes > largeTransferThreshold {
        fmt.Printf("Large Transfer Report (%d MB)\n", stats.TotalBytes / 1024 / 1024)
        fmt.Printf("Duration: %.2f seconds\n", stats.ElapsedTime.Seconds())
        fmt.Printf("Bandwidth: %.2f MB/s (avg), %.2f MB/s (peak)\n",
            float64(stats.AverageBandwidth) / 1024 / 1024,
            float64(stats.PeakBandwidth) / 1024 / 1024)
        fmt.Printf("Compression: %.1f%% saved\n",
            (1.0 - stats.CompressionRatio) * 100)
        fmt.Printf("Success rate: %.1f%%\n",
            float64(stats.ProcessedChunks) / float64(stats.TotalChunks) * 100)

        if stats.HasErrors {
            fmt.Printf("Errors: %d encountered\n", stats.ErrorCount)
        }
    }
}

// Example 6: Statistics trend analysis (comparing multiple transfers)
type TransferAnalytics struct {
    transfers []StreamingStats
}

func (ta *TransferAnalytics) AddTransfer(stats *StreamingStats) {
    ta.transfers = append(ta.transfers, *stats)
}

func (ta *TransferAnalytics) AnalyzeTrends() {
    if len(ta.transfers) == 0 {
        return
    }

    var (
        totalDuration    time.Duration
        avgBandwidth     float64
        avgCompressionRatio float64
        successfulCount  int
    )

    for _, stats := range ta.transfers {
        totalDuration += stats.ElapsedTime
        avgBandwidth += float64(stats.AverageBandwidth)
        avgCompressionRatio += stats.CompressionRatio
        if !stats.HasErrors {
            successfulCount++
        }
    }

    count := float64(len(ta.transfers))
    successRate := float64(successfulCount) / count * 100

    fmt.Printf("Transfer Analytics (last %d transfers):\n", len(ta.transfers))
    fmt.Printf("  Success rate: %.1f%%\n", successRate)
    fmt.Printf("  Avg duration: %.2f seconds\n", totalDuration.Seconds() / count)
    fmt.Printf("  Avg bandwidth: %.2f MB/s\n",
        (avgBandwidth / count) / 1024 / 1024)
    fmt.Printf("  Avg compression: %.1f%%\n",
        (1.0 - avgCompressionRatio / count) * 100)
}

Statistics Timing Precision: 

Metric                  Resolution        Precision           Use For
──────────────────────────────────────────────────────────────────────
StartTime/EndTime       Nanosecond         time.Time           Exact operation timing
ElapsedTime             Nanosecond         time.Duration       Transfer duration
CPUTime                 Microsecond        time.Duration       CPU utilization analysis
Timing calculations     Nanosecond         Arithmetic result   Sub-millisecond analysis

Statistics Data Precision: 

Metric                  Type        Range                   Precision
─────────────────────────────────────────────────────────────────────
Byte counts             int64       0 to 9.2 EB            1 byte
Chunk counts            int64       0 to 9.2 billion       1 chunk
Bandwidth values        int64       0 B/s to GB/s          1 B/s
Compression ratio       float64     0.0 to 1.0             ~1e-15
Memory values           int64       0 to 9.2 EB            1 byte

Statistics Availability Timeline: 

Streaming Stage              Statistics Available                         Completeness
────────────────────────────────────────────────────────────────────────────────────
Before Start()               None (empty structure)                       Empty
During Start() (early)       Partial (StartTime only)                    Minimal
During Start() (mid-stream)  Partial (progress, partial data)            Growing
After Start() completes      Complete (all fields, final values)         100%
After Cancel()               Partial at cancellation point                At cancel time
After Close()                Same as after Start() (unchanged)            Unchanged

Statistics Snapshot Semantics: 

Aspect                          Behavior                        Implication
──────────────────────────────────────────────────────────────────────────
Return value                    Pointer to StreamingStats       Copy returned, not reference
Modifications                   Do not affect streaming         Safe to modify returned stats
Multiple calls                  Independent snapshots           Each call gets fresh snapshot
Call during streaming           Returns partial statistics      Time-dependent results
Call after streaming            Returns complete statistics    Final values stable
Garbage collection              Stats safe from GC            Lifetime guaranteed
Concurrent calls                Thread-safe reads              Multiple goroutines safe

Performance Statistics Calculation Methods: 

Metric                              Calculation Method
────────────────────────────────────────────────────────────────────
AverageBandwidth                    TransferredBytes / ElapsedTime.Seconds()
CompressionRatio                    CompressedSize / OriginalSize
Success rate                        ProcessedChunks / TotalChunks * 100
Failed bytes                        TotalBytes - TransferredBytes
Effective throughput                TransferredBytes / ElapsedTime.Seconds()
Time per chunk                      ElapsedTime / ProcessedChunks
Memory per chunk                    MemoryAllocated / MaxConcurrentChunks

Integration with Other Methods: 

Method                  Returns                 When to Use                  Data Overlap
──────────────────────────────────────────────────────────────────────────────────
GetStreamingStats()     *StreamingStats         Complete statistics          All streaming metrics
GetProgress()           *StreamProgress         Current progress              Current chunk, bytes, %
GetWrapper()            *wrapper                Response building             Status, message, headers
Errors()                []error                 Error analysis                Error list
HasErrors()             bool                    Quick error check             Error existence
GetStats()              *StreamingStats         (alias for this function)    Same as GetStreamingStats

Statistics for Different Streaming Strategies: 

Strategy                Statistics Specific Behavior
──────────────────────────────────────────────────────────────────────
STRATEGY_DIRECT         Linear chunk processing, simple bandwidth calc
STRATEGY_BUFFERED       Concurrent I/O, more accurate peak/min bandwidth
STRATEGY_CHUNKED        Explicit chunk control, detailed chunk-level stats
All strategies          Same final metrics, different measurement precision

Best Practices:

  1. RETRIEVE AFTER STREAMING COMPLETES - Get final comprehensive statistics - Pattern: result := streaming.Start(ctx) stats := streaming.GetStreamingStats() // All fields populated

  2. COMBINE WITH PROGRESS FOR UNDERSTANDING - Progress shows real-time state - Stats shows final analysis - Pattern: progress := streaming.GetProgress() // Where we are now stats := streaming.GetStreamingStats() // Overall result

  3. USE FOR PERFORMANCE ANALYSIS - Bandwidth metrics for optimization - Memory metrics for resource planning - Compression metrics for effectiveness - Error metrics for reliability analysis

  4. INCLUDE IN RESPONSE METADATA - Add key statistics to API response - Help clients understand transfer - Example: WithDebuggingKV("avg_bandwidth_mbps", float64(stats.AverageBandwidth) / 1024 / 1024)

  5. LOG FOR DIAGNOSTICS - Complete statistics for troubleshooting - Identify performance issues - Track historical trends - Example: log.Infof("Transfer: %d bytes, %.2f s, %.2f MB/s", stats.TransferredBytes, stats.ElapsedTime.Seconds(), float64(stats.AverageBandwidth) / 1024 / 1024)

See Also:

  • GetProgress: Real-time progress tracking (complement to GetStreamingStats)
  • GetWrapper: Response building with metadata
  • GetStats: Alias for GetStreamingStats (same function)
  • Errors: Retrieve error list (stats includes error count)
  • HasErrors: Quick error check (stats has HasErrors field)
  • Start: Executes streaming and accumulates statistics
  • Cancel: Stops streaming (preserves stats up to cancellation)

func (*StreamingWrapper) GetWrapper 

func (sw *StreamingWrapper) GetWrapper() *wrapper

GetWrapper returns the underlying wrapper object associated with this streaming wrapper.

This function provides access to the base wrapper instance that was either passed into WithStreaming() or automatically created during streaming initialization. The returned wrapper contains all HTTP response metadata including status code, message, headers, custom fields, and debugging information accumulated during the streaming operation. This is useful for building complete API responses, accessing response metadata, chaining additional wrapper methods, and integrating streaming results with the standard wrapper API. GetWrapper is non-blocking, thread-safe, and can be called at any time during or after streaming. The returned wrapper reference points to the same underlying object; modifications through the returned reference affect the original wrapper state. Multiple calls to GetWrapper() return the same wrapper instance, not copies. This enables seamless integration between streaming and standard wrapper patterns, allowing users to leverage both the streaming-specific functionality and the comprehensive wrapper API in a unified response-building workflow.

Returns:

  • A pointer to the underlying wrapper instance if the streaming wrapper is valid.
  • If the streaming wrapper is nil, returns a newly created empty wrapper (safety fallback).
  • The returned wrapper is the same instance used throughout streaming; not a copy.
  • All streaming metadata (status code, message, debug info) is available via the wrapper.
  • Modifications to the returned wrapper affect the final response object.
  • The wrapper reference is thread-safe to read; use proper synchronization for modifications.
  • Multiple calls return the same instance (identity equality: w1 == w2).

Wrapper Integration Points: 

Aspect                          How GetWrapper() Facilitates Integration
───────────────────────────────────────────────────────────────────────────
Status code management          Access/modify response HTTP status code
Message/error text              Set response message or error description
Custom fields                   Add domain-specific data to response
Debugging information           Add/retrieve debugging KV pairs
Response headers                Configure HTTP response headers
Response body                   Set body content (though streaming uses writer)
Pagination info                 Add pagination metadata
Error wrapping                  Wrap errors in standard wrapper format
Method chaining                 Chain multiple wrapper methods together
Final response building         Construct complete API response

Typical Integration Pattern: 

// Create streaming wrapper
streaming := response.WithStreaming(reader, config)

// Configure streaming
result := streaming.
    WithChunkSize(1024 * 1024).
    WithCompressionType(COMP_GZIP).
    Start(ctx)

// Access wrapper for response building
finalResponse := streaming.GetWrapper().
    WithStatusCode(200).
    WithMessage("Streaming completed").
    WithTotal(streaming.GetProgress().CurrentChunk)

Access Patterns: 

Pattern                             Use Case                        Example
──────────────────────────────────────────────────────────────────────────
Immediate access                    Read current status             status := GetWrapper().StatusCode()
Post-streaming response             Build final response            GetWrapper().WithStatusCode(200)
Error handling                      Wrap errors in response         GetWrapper().WithError(err)
Metadata enrichment                 Add context information         GetWrapper().WithDebuggingKV(...)
Header configuration                Set HTTP response headers       GetWrapper().WithHeader(...)
Pagination integration              Add page info if applicable     GetWrapper().WithPagination(...)
Custom field addition               Domain-specific data            GetWrapper().WithCustomFieldKV(...)
Conditional response building       Different paths based on state  if hasErrors: WithStatusCode(206)
Response chaining                   Build response inline           return GetWrapper().WithMessage(...)
Debugging/diagnostics               Access accumulated metadata     GetWrapper().Debugging()

Example: 

// Example 1: Simple response building after streaming
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4)

result := streaming.Start(context.Background())

// Access wrapper to build final response
finalResponse := streaming.GetWrapper().
    WithMessage("File download completed").
    WithDebuggingKV("total_chunks",
        streaming.GetProgress().CurrentChunk).
    WithDebuggingKV("bytes_transferred",
        streaming.GetProgress().TransferredBytes)

// Example 2: Error handling with wrapper integration
httpResp, _ := http.Get("https://api.example.com/largefile")
defer httpResp.Body.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/proxy/remote-file").
    WithStreaming(httpResp.Body, nil).
    WithChunkSize(512 * 1024).
    WithReadTimeout(15000).
    WithWriteTimeout(15000).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Warnf("Streaming chunk %d error: %v",
                p.CurrentChunk, err)
        }
    })

result := streaming.Start(context.Background())

// Use GetWrapper() for error response building
if streaming.HasErrors() {
    finalResponse := streaming.GetWrapper().
        WithStatusCode(206). // 206 Partial Content
        WithMessage("File download completed with errors").
        WithError(fmt.Sprintf("%d chunks failed",
            len(streaming.Errors()))).
        WithDebuggingKV("error_count", len(streaming.Errors())).
        WithDebuggingKV("failed_chunks", streaming.GetStats().FailedChunks)
} else {
    finalResponse := streaming.GetWrapper().
        WithStatusCode(200).
        WithMessage("File download completed successfully").
        WithDebuggingKV("bytes_transferred",
            streaming.GetStats().TotalBytes)
}

// Example 3: Metadata enrichment with streaming context
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/users").
    WithCustomFieldKV("export_type", "csv").
    WithCustomFieldKV("export_id", "exp-2025-1114-001").
    WithStreaming(dataExport, nil).
    WithChunkSize(512 * 1024).
    WithMaxConcurrentChunks(4).
    WithCompressionType(COMP_GZIP)

result := streaming.Start(context.Background())
stats := streaming.GetStats()
progress := streaming.GetProgress()

// Rich metadata response via GetWrapper()
finalResponse := streaming.GetWrapper().
    WithStatusCode(200).
    WithMessage("User export completed").
    WithDebuggingKV("export_id", "exp-2025-1114-001").
    WithDebuggingKV("export_status", "completed").
    WithDebuggingKV("records_exported", progress.CurrentChunk).
    WithDebuggingKV("original_size_bytes", stats.TotalBytes).
    WithDebuggingKVf("compressed_size_bytes", "%d", stats.CompressedBytes).
    WithDebuggingKVf("compression_ratio", "%.2f%%",
        (1.0 - stats.CompressionRatio) * 100).
    WithDebuggingKV("duration_seconds",
        stats.EndTime.Sub(stats.StartTime).Seconds()).
    WithDebuggingKVf("average_bandwidth_mbps", "%.2f",
        float64(stats.AverageBandwidth) / 1024 / 1024)

// Example 4: Conditional response building with wrapper
func BuildStreamingResponse(streaming *StreamingWrapper) *wrapper {
    progress := streaming.GetProgress()
    stats := streaming.GetStats()

    // Start with base wrapper
    response := streaming.GetWrapper()

    // Branch based on streaming outcome
    if streaming.HasErrors() {
        errorCount := len(streaming.Errors())
        if errorCount > 10 {
            // Many errors - mostly failed
            return response.
                WithStatusCode(500).
                WithMessage("Streaming failed with many errors").
                WithError(fmt.Sprintf("%d chunks failed", errorCount)).
                WithDebuggingKV("success_rate_percent",
                    int(float64(stats.TotalChunks - stats.FailedChunks) /
                        float64(stats.TotalChunks) * 100))
        } else {
            // Few errors - mostly succeeded
            return response.
                WithStatusCode(206).
                WithMessage("Streaming completed with minor errors").
                WithDebuggingKV("error_count", errorCount).
                WithDebuggingKV("success_rate_percent",
                    int(float64(stats.TotalChunks - stats.FailedChunks) /
                        float64(stats.TotalChunks) * 100))
        }
    } else {
        // Perfect success
        return response.
            WithStatusCode(200).
            WithMessage("Streaming completed successfully").
            WithDebuggingKV("total_chunks", stats.TotalChunks).
            WithDebuggingKV("total_bytes", stats.TotalBytes).
            WithDebuggingKVf("duration_seconds", "%.2f",
                stats.EndTime.Sub(stats.StartTime).Seconds())
    }
}

// Example 5: Accessing wrapper during streaming (concurrent monitoring)
func MonitorStreamingWithWrapper(streaming *StreamingWrapper) {
    ticker := time.NewTicker(500 * time.Millisecond)
    defer ticker.Stop()

    for range ticker.C {
        if !streaming.IsStreaming() {
            break
        }

        // Access wrapper status info
        wrapper := streaming.GetWrapper()
        progress := streaming.GetProgress()

        fmt.Printf("Status: %d | Message: %s | Progress: %.1f%%\n",
            wrapper.StatusCode(),
            wrapper.Message(),
            float64(progress.Percentage))
    }
}

// Example 6: Complete workflow with wrapper integration
func CompleteStreamingWorkflow(fileReader io.ReadCloser,
                                exportID string) *wrapper {
    // Create streaming wrapper
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/export/complete-workflow").
        WithCustomFieldKV("export_id", exportID).
        WithStreaming(fileReader, nil).
        WithChunkSize(1024 * 1024).
        WithMaxConcurrentChunks(4).
        WithCompressionType(COMP_GZIP).
        WithCallback(func(p *StreamProgress, err error) {
            if err != nil {
                log.Warnf("[%s] Chunk %d error: %v",
                    exportID, p.CurrentChunk, err)
            }
        })

    // Execute streaming
    result := streaming.Start(context.Background())

    // Cleanup
    streaming.Close()

    // Get streaming statistics
    stats := streaming.GetStats()
    progress := streaming.GetProgress()

    // Build complete response via GetWrapper()
    finalResponse := streaming.GetWrapper()

    // Status code based on outcome
    if streaming.HasErrors() {
        finalResponse = finalResponse.WithStatusCode(206)
    } else {
        finalResponse = finalResponse.WithStatusCode(200)
    }

    // Add comprehensive metadata
    finalResponse.
        WithMessage("Workflow execution completed").
        WithDebuggingKV("export_id", exportID).
        WithDebuggingKV("status", "completed").
        WithDebuggingKV("chunks_processed", progress.CurrentChunk).
        WithDebuggingKV("total_chunks", stats.TotalChunks).
        WithDebuggingKV("original_size", stats.TotalBytes).
        WithDebuggingKV("compressed_size", stats.CompressedBytes).
        WithDebuggingKVf("compression_ratio", "%.1f%%",
            (1.0 - stats.CompressionRatio) * 100).
        WithDebuggingKV("error_count", len(streaming.Errors())).
        WithDebuggingKV("failed_chunks", stats.FailedChunks).
        WithDebuggingKVf("duration_ms", "%d",
            stats.EndTime.Sub(stats.StartTime).Milliseconds()).
        WithDebuggingKVf("bandwidth_mbps", "%.2f",
            float64(stats.AverageBandwidth) / 1024 / 1024)

    return finalResponse
}

Wrapper Metadata Available Through GetWrapper(): 

Category                Information Available              Example Access
──────────────────────────────────────────────────────────────────────────
HTTP Status              StatusCode, IsError, IsSuccess    wrapper.StatusCode()
Response Message         Message text                      wrapper.Message()
Errors                   Error wrapping, message           wrapper.Error()
Custom Fields            Domain-specific data              wrapper.CustomFields()
Debugging Info           KV debugging pairs                wrapper.Debugging()
Response Headers         HTTP response headers             wrapper.Headers()
Path                     API endpoint path                 wrapper.Path()
Pagination               Page/limit/offset info            wrapper.Pagination()
Request/Response timing  Built via debugging KV            wrapper.DebuggingKV()
All metadata             Complete wrapper state            wrapper.*() methods

Streaming-Specific Metadata Added via GetWrapper(): 

Metadata Item                   Source                  Purpose
────────────────────────────────────────────────────────────────────────
streaming_strategy              WithStreaming()         Track chosen strategy
compression_type                WithCompressionType()   Track compression used
chunk_size                       WithChunkSize()         Track chunk size
total_bytes                      WithTotalBytes()        Track total data size
max_concurrent_chunks            WithMaxConcurrentChunks Track parallelism
throttle_rate_bps                WithThrottleRate()      Track bandwidth limit
buffer_pooling_enabled           WithBufferPooling()     Track buffer reuse
read_timeout_ms                  WithReadTimeout()       Track read timeout
write_timeout_ms                 WithWriteTimeout()      Track write timeout
streaming_error                  Start() on error        Error message if failed
failed_chunks                    Start()                 Count of failed chunks
total_errors                     Start()                 Count of accumulated errors
started_at                       Start()                 Timestamp when started
completed_at                     Start()                 Timestamp when completed
cancelled_at                     Cancel()                Timestamp when cancelled
duration_ms                      Start()                 Total operation duration
compression_ratio                GetStats()              Compression effectiveness

Identity and Mutation Semantics: 

Aspect                          Behavior                        Implication
──────────────────────────────────────────────────────────────────────────
Multiple calls return same ref   GetWrapper() == GetWrapper()    Single instance
Modifications visible everywhere wrapper.WithStatusCode(201)     Shared state
Not a copy                       Mutations affect original        Direct reference
Thread-safe reads                RWMutex protected               Safe access
Concurrent modifications         May race                        Use sync for changes
Post-streaming access            Safe, no cleanup needed         Wrapper persists
Reference persistence            Available until wrapper freed   Lifetime guaranteed
Copy semantics                   Reference, not value            No deep copy made

Common Usage Patterns: 

Pattern                                         Benefit                         Example
─────────────────────────────────────────────────────────────────────────────
Post-streaming status check                     Immediate feedback              wrapper.StatusCode()
Error response building                         Consistent error format         WithError(...).WithStatusCode(...)
Metadata enrichment                             Rich response context           WithDebuggingKV(...) for each stat
Conditional response chains                     Flexible response building      if hasErrors: 206 else: 200
Inline response construction                    Compact code                    return GetWrapper().WithMessage(...)
Concurrent progress monitoring                  Real-time status access         Polling wrapper state
Logging with wrapper context                    Diagnostic context              Log wrapper.Debugging()
Response wrapping for downstream                Consistent API contracts        Pass wrapper to other services

Best Practices:

  1. CALL AFTER STREAMING COMPLETES - GetWrapper() returns final state - Call after Start() returns for complete information - Pattern: result := streaming.Start(ctx) finalResponse := streaming.GetWrapper().WithMessage("Done")

  2. USE FOR RESPONSE BUILDING - GetWrapper() is designed for constructing API responses - Chain methods for clean, readable code - Example: return streaming.GetWrapper(). WithStatusCode(200). WithMessage("Export completed"). WithDebuggingKV("total_chunks", stats.TotalChunks)

  3. COMBINE WITH STREAMING STATS - GetWrapper() provides wrapper metadata - GetStats() provides streaming metrics - GetProgress() provides progress info - Use all three for complete picture - Example: wrapper := streaming.GetWrapper() stats := streaming.GetStats() return wrapper.WithDebuggingKV("bytes", stats.TotalBytes)

  4. HANDLE NIL STREAMING GRACEFULLY - GetWrapper() creates new wrapper if streaming is nil - Safe fallback for defensive programming - No need for nil checks before calling - Example: wrapper := nilStreaming.GetWrapper() // Safe, returns new wrapper

  5. DON'T MODIFY DURING STREAMING - Wrapper mutations during streaming may race - Read-only access is safe - Modifications after streaming are safe - Example: // During streaming: safe statusCode := streaming.GetWrapper().StatusCode() // During streaming: unsafe (may race) streaming.GetWrapper().WithMessage("New message") // After streaming: safe streaming.GetWrapper().WithMessage("Completed")

Relationship to Other Methods: 

Method                  Provides                    When to Use
──────────────────────────────────────────────────────────────────────
GetWrapper()            Wrapper with metadata       Building final response
GetStats()              Streaming metrics           Statistics/diagnostics
GetProgress()           Current progress info       Progress tracking
Errors()                Error list copy             Error analysis
HasErrors()             Boolean error check         Quick error detection
GetStreamingStats()     Complete stats              After streaming
GetStreamingProgress()  Final progress              After streaming
IsStreaming()           Active status               Concurrent monitoring

See Also:

  • Start: Executes streaming and populates wrapper with results
  • WithStreaming: Creates streaming wrapper with base wrapper
  • Cancel: Stops streaming, updates wrapper state
  • Close: Closes resources, does not affect wrapper
  • GetStats: Returns streaming statistics (complement to GetWrapper)
  • GetProgress: Returns progress information (complement to GetWrapper)
  • WithStatusCode/WithMessage/etc: Wrapper methods for building response

func (StreamingWrapper) GroupByJSONBody 

func (w StreamingWrapper) GroupByJSONBody(path, keyField string) map[string][]fj.Context

GroupByJSONBody groups the elements at the given path in the body by the string value of keyField, using conv.String for key normalization.

Example: 

byRole := w.GroupByJSONBody("users", "role")

func (*StreamingWrapper) HasErrors 

func (sw *StreamingWrapper) HasErrors() bool

HasErrors checks whether any errors occurred during the streaming operation without retrieving the full error list.

This function provides a lightweight, efficient way to determine if the streaming operation encountered any errors without allocating memory to copy the entire error slice. It performs a simple boolean check on the error count, returning true if at least one error was recorded and false if no errors occurred. This is useful as a fast filter before calling the more expensive Errors() method, or for conditional logic that only needs to know "did errors occur?" rather than "what were all the errors?". HasErrors is thread-safe and can be called from any goroutine during or after streaming. It provides a snapshot of the error state at the moment of the call; subsequent errors may be recorded if streaming is still ongoing. This is the recommended method for quick error checks, assertions, and control flow decisions where the specific error details are not needed.

Returns:

  • true if one or more errors were recorded during streaming.
  • false if no errors occurred (zero errors).
  • false if the streaming wrapper is nil.
  • Thread-safe: multiple goroutines can call concurrently without blocking.
  • Snapshot behavior: returns state at call time; ongoing streaming may change result.

Performance Characteristics: 

Operation                   Time Complexity    Space Complexity    Notes
─────────────────────────────────────────────────────────────────────────
HasErrors() call            O(1)               O(0)                Constant time
Single length check         <1μs               None                Just compares int
RWMutex lock acquisition    O(1) amortized     None                Lock contention rare
No allocation               None               O(0)                Stack only
vs Errors() copy            10-100x faster     No allocation       Major advantage
Concurrent calls            Parallel reads     None                Multiple readers OK

When to Use HasErrors vs Errors: 

Scenario                            Use HasErrors()    Use Errors()
──────────────────────────────────────────────────────────────────────────
Quick "any error?" check            ✓ YES             ✗ No
Conditionals (if err occurred)      ✓ YES             ✗ No
Need specific error details         ✗ No              ✓ YES
Error analysis/categorization       ✗ No              ✓ YES
Logging all errors                  ✗ No              ✓ YES
Circuit breaker threshold           ✓ YES             ✗ No
Before calling Errors()             ✓ YES             ✗ No
Memory-constrained environment      ✓ YES             ✗ No
Performance-critical path           ✓ YES             ✗ No
Error reporting/diagnostics         ✗ No              ✓ YES

Error State Timeline: 

Point in Streaming              HasErrors() Returns    Explanation
────────────────────────────────────────────────────────────────────
Before Start()                  false                  No streaming yet
Chunks 1-100 ok                 false                  No errors encountered
Chunk 101 timeout               true                   First error recorded
Chunk 102 ok (retry)            true                   Error list not cleared
Chunk 103 write fail            true                   Additional error added
Streaming completes             true                   Final error list preserved
After Close()                   true                   Errors not cleared
New streaming instance          false                  Fresh error list

Example: 

// Example 1: Simple error checking after streaming
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithReadTimeout(15000).
    WithWriteTimeout(15000)

result := streaming.Start(context.Background())

// Fast check for errors without allocating error list
if streaming.HasErrors() {
    fmt.Println("Streaming completed with errors")
    // Only retrieve full error list if we know errors exist
    errors := streaming.Errors()
    fmt.Printf("Total errors: %d\n", len(errors))
} else {
    fmt.Println("Streaming completed successfully")
}

// Example 2: Conditional response building with error checking
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/users").
    WithStreaming(dataExport, nil).
    WithChunkSize(512 * 1024).
    WithMaxConcurrentChunks(4)

result := streaming.Start(context.Background())
streaming.Close()

// Build response based on error status (no expensive Errors() call if not needed)
finalResponse := result
if streaming.HasErrors() {
    finalResponse = result.
        WithStatusCode(206). // 206 Partial Content
        WithMessage("Export completed with some errors").
        WithDebuggingKV("error_count", len(streaming.Errors())).
        WithDebuggingKV("has_errors", true)
} else {
    finalResponse = result.
        WithStatusCode(200).
        WithMessage("Export completed successfully")
}

// Example 3: Circuit breaker pattern with fast error detection
maxErrorsAllowed := 10

fileReader, _ := os.Open("large-backup.tar.gz")
defer fileReader.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/backup/stream").
    WithStreaming(fileReader, nil).
    WithChunkSize(10 * 1024 * 1024).
    WithMaxConcurrentChunks(8).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            // Fast check first (O(1))
            if streaming.HasErrors() {
                // Only if errors exist, check count (O(n))
                errorCount := len(streaming.Errors())
                if errorCount >= maxErrorsAllowed {
                    fmt.Printf("Circuit breaker: %d errors >= %d limit\n",
                        errorCount, maxErrorsAllowed)
                    streaming.Cancel()
                }
            }
        }
    })

result := streaming.Start(context.Background())

// Example 4: Assert no errors (test/validation)
func AssertStreamingSuccess(t *testing.T, streaming *StreamingWrapper) {
    if streaming.HasErrors() {
        t.Fatalf("Expected no errors, but got: %v", streaming.Errors())
    }
}

// Usage in test
func TestStreamingDownload(t *testing.T) {
    file, _ := os.Open("testdata.bin")
    defer file.Close()

    streaming := replify.New().
        WithStreaming(file, nil).
        WithChunkSize(65536)

    result := streaming.Start(context.Background())

    AssertStreamingSuccess(t, streaming) // Fast assertion

    if !result.IsSuccess() {
        t.Fatalf("Expected success, got status %d", result.StatusCode())
    }
}

// Example 5: Conditional detailed error logging
func LogStreamingResult(streaming *StreamingWrapper, contextInfo string) {
    // Fast check first (O(1) - cheap operation)
    if streaming.HasErrors() {
        // Only do expensive error retrieval if errors exist
        errors := streaming.Errors()
        log.Warnf("[%s] Streaming had %d errors:", contextInfo, len(errors))

        for i, err := range errors {
            log.Warnf("  [Error %d/%d] %v", i+1, len(errors), err)
        }
    } else {
        // Success path - no expensive operations
        log.Infof("[%s] Streaming completed successfully", contextInfo)
    }
}

// Example 6: Multi-condition error checking pattern
func HandleStreamingCompletion(streaming *StreamingWrapper) *wrapper {
    progress := streaming.GetProgress()

    // Chain conditions from cheapest to most expensive
    if !streaming.HasErrors() {
        // Path 1: Fast success case (O(1))
        return streaming.GetWrapper().
            WithStatusCode(200).
            WithMessage("Streaming completed successfully").
            WithTotal(progress.CurrentChunk)
    } else if len(streaming.Errors()) <= 5 {
        // Path 2: Moderate error case (O(n) but small n)
        return streaming.GetWrapper().
            WithStatusCode(206).
            WithMessage("Streaming completed with minor errors").
            WithDebuggingKV("error_count", len(streaming.Errors()))
    } else {
        // Path 3: Severe error case (O(n) but warranted)
        errors := streaming.Errors()
        return streaming.GetWrapper().
            WithStatusCode(500).
            WithMessage("Streaming failed with multiple errors").
            WithDebuggingKV("error_count", len(errors)).
            WithDebuggingKV("error_summary", strings.Join(
                func() []string {
                    summary := make([]string, len(errors))
                    for i, err := range errors {
                        summary[i] = err.Error()
                    }
                    return summary
                }(),
                "; "))
    }
}

Performance Comparison Example: 

// ❌ INEFFICIENT: Always copy errors even if not needed
func BadPattern(streaming *StreamingWrapper) {
    errors := streaming.Errors() // O(n) allocation even if not used
    if len(errors) > 0 {
        fmt.Println("Has errors")
    }
}

// ✅ EFFICIENT: Check first, then retrieve if needed
func GoodPattern(streaming *StreamingWrapper) {
    if streaming.HasErrors() { // O(1) - cheap
        errors := streaming.Errors() // O(n) - only if needed
        if len(errors) > 0 {
            fmt.Println("Has errors")
        }
    }
}

// Performance impact with large error lists:
// 100 errors:   HasErrors() 1μs vs Errors() 10μs (10x faster)
// 1000 errors:  HasErrors() 1μs vs Errors() 100μs (100x faster)
// 10000 errors: HasErrors() 1μs vs Errors() 1ms (1000x faster)

Optimization Strategy: 

Condition                       Optimization
────────────────────────────────────────────────────────────────────
Need to check for errors        Use HasErrors() first
Need error details              Call Errors() only if HasErrors() true
Need error count                if has errors: len(Errors()); else: 0
Performance-critical code       Always use HasErrors() as filter
Memory-constrained              Use HasErrors() to avoid allocation
Logging conditional errors      if HasErrors(): log(Errors())
Circuit breaker implementation  if HasErrors(): break on threshold
Response building               if HasErrors(): build error response

Thread-Safety and Concurrency: 

Scenario                                    Thread-Safe    Details
─────────────────────────────────────────────────────────────────────
HasErrors() during streaming                Yes            RWMutex protects
Multiple concurrent HasErrors()             Yes            Parallel reads allowed
HasErrors() + Start() concurrently          Yes            Independent operations
HasErrors() + Errors() race                 Yes            Consistent snapshot
HasErrors() + Cancel() concurrently         Yes            Operations independent
HasErrors() in multiple goroutines          Yes            Lock-free on success path
Contention under high concurrency           Rare           RWMutex optimized
Call during callback                        Yes            Safe from within callback

Common Pitfalls and Solutions: 

Pitfall                                 Problem                 Solution
─────────────────────────────────────────────────────────────────────────
Always calling Errors()                 Unnecessary allocation   Use HasErrors() first
Assuming no errors = all ok             Incomplete check        Also check status code
Race on error count during streaming    Timing dependent        Use atomic/lock
Ignoring errors in success path         Silent failures         Always check HasErrors()
Calling HasErrors() in tight loop       Lock contention         Cache result or defer
Not pairing with error details          Lost diagnostic info    Use Errors() when needed
Forgetting return value                 No-op statement         Assign or use result

Related Methods Comparison: 

Method                  Returns         Cost        When to Use
─────────────────────────────────────────────────────────────────────
HasErrors()             bool            O(1)        Fast "any error?" check
Errors()                []error         O(n)        Need all error details
Len(Errors())           int             O(n)        Need error count (bad idea!)
GetStats().Errors       []error         O(n)        Stats + errors together
GetProgress()           *StreamProgress O(1)        Check progress, not errors
IsError() (wrapper)     bool            O(1)        Check HTTP status error

Best Practices:

  1. USE AS FAST FILTER - Check HasErrors() first (O(1)) - Only call Errors() if HasErrors() returns true (O(n)) - Saves memory and CPU for error-free paths - Example: if streaming.HasErrors() { errors := streaming.Errors() // Handle errors }

  2. COMBINE WITH STATUS CHECKING - Don't assume HasErrors() = request failed - Also check wrapper.IsError() for HTTP status - Example: if streaming.HasErrors() || !result.IsSuccess() { // Handle error condition }

  3. USE IN CONDITIONALS FOR CLARITY - More readable than len(Errors()) > 0 - Self-documenting code intent - Example: if streaming.HasErrors() { // Clear intent vs if len(streaming.Errors()) > 0 { // Allocates unnecessarily }

  4. CACHE RESULT IN LOOPS - Avoid repeated lock acquisitions - Example: hasErrors := streaming.HasErrors() for i := 0; i < 1000; i++ { if hasErrors { // Use cached value // Handle error condition } }

  5. LOG ONLY ON ERROR - Avoid expensive error list creation in success path - Example: if streaming.HasErrors() { log.Warnf("Errors: %v", streaming.Errors()) } // vs always allocating in non-error path

See Also:

  • Errors: Retrieves full error list (use when HasErrors() is true)
  • GetStats: Provides FailedChunks count and error array
  • GetProgress: Includes streaming progress information
  • GetWrapper: Returns wrapper with status/message
  • Start: Initiates streaming and accumulates errors
  • WithCallback: Receives individual errors during streaming

func (StreamingWrapper) Hash 

func (w StreamingWrapper) Hash() uint64

This method generates a hash value for the `wrapper` instance using the `Hash` method. If the `wrapper` instance is not available or the hash generation fails, it returns an empty string.

Returns:

  • A string representing the hash value.
  • An empty string if the `wrapper` instance is not available or the hash generation fails.

func (StreamingWrapper) Hash256 

func (w StreamingWrapper) Hash256() string

Hash256 generates a hash string for the `wrapper` instance.

This method generates a hash string for the `wrapper` instance using the `Hash256` method. If the `wrapper` instance is not available or the hash generation fails, it returns an empty string.

Returns:

  • A string representing the hash value.
  • An empty string if the `wrapper` instance is not available or the hash generation fails.

func (StreamingWrapper) Header 

func (w StreamingWrapper) Header() *header

Header retrieves the `header` associated with the `wrapper` instance.

This function returns the `header` field from the `wrapper` instance, which contains information about the HTTP response or any other relevant metadata. If the `wrapper` instance is correctly initialized, it will return the `header`; otherwise, it may return `nil` if the `header` has not been set.

Returns:

  • A pointer to the `header` instance associated with the `wrapper`.
  • `nil` if the `header` is not set or the `wrapper` is uninitialized.

func (StreamingWrapper) IncreaseDeltaCnt 

func (w StreamingWrapper) IncreaseDeltaCnt() *wrapper

IncreaseDeltaCnt increments the delta count in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and increments the delta count in the `meta` using the `IncreaseDeltaCnt` method.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) IsBodyPresent 

func (w StreamingWrapper) IsBodyPresent() bool

IsBodyPresent checks whether the body data is present in the `wrapper` instance.

This function checks if the `data` field of the `wrapper` is not nil, indicating that the body contains data.

Returns:

  • A boolean value indicating whether the body data is present:
  • `true` if `data` is not nil.
  • `false` if `data` is nil.

func (StreamingWrapper) IsClientError 

func (w StreamingWrapper) IsClientError() bool

IsClientError checks whether the HTTP status code indicates a client error.

This function checks if the `statusCode` is between 400 and 499, inclusive, which indicates a client error HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a client error:
  • `true` if the status code is between 400 and 499 (inclusive).
  • `false` if the status code is outside of this range.

func (StreamingWrapper) IsDebuggingKeyPresent 

func (w StreamingWrapper) IsDebuggingKeyPresent(key string) bool

IsDebuggingKeyPresent checks whether a specific key exists in the `debug` information.

This function first checks if debugging information is present using `IsDebuggingPresent()`. Then it uses `coll.MapContainsKey` to verify if the given key is present within the `debug` map.

Parameters:

  • `key`: The key to search for within the `debug` field.

Returns:

  • A boolean value indicating whether the specified key is present in the `debug` map:
  • `true` if the `debug` field is present and contains the specified key.
  • `false` if `debug` is nil or does not contain the key.

func (StreamingWrapper) IsDebuggingPresent 

func (w StreamingWrapper) IsDebuggingPresent() bool

IsDebuggingPresent checks whether debugging information is present in the `wrapper` instance.

This function verifies if the `debug` field of the `wrapper` is not nil and contains at least one entry. It returns `true` if debugging information is available; otherwise, it returns `false`.

Returns:

  • A boolean value indicating whether debugging information is present:
  • `true` if `debug` is not nil and contains data.
  • `false` if `debug` is nil or empty.

func (StreamingWrapper) IsError 

func (w StreamingWrapper) IsError() bool

IsError checks whether there is an error present in the `wrapper` instance.

This function returns `true` if the `wrapper` contains an error, which can be any of the following:

  • An error present in the `errors` field.
  • A client error (4xx status code) or a server error (5xx status code).

Returns:

  • A boolean value indicating whether there is an error:
  • `true` if there is an error present, either in the `errors` field or as an HTTP client/server error.
  • `false` if no error is found.

func (StreamingWrapper) IsErrorPresent 

func (w StreamingWrapper) IsErrorPresent() bool

IsErrorPresent checks whether an error is present in the `wrapper` instance.

This function checks if the `errors` field of the `wrapper` is not nil, indicating that an error has occurred.

Returns:

  • A boolean value indicating whether an error is present:
  • `true` if `errors` is not nil.
  • `false` if `errors` is nil.

func (StreamingWrapper) IsHeaderPresent 

func (w StreamingWrapper) IsHeaderPresent() bool

IsHeaderPresent checks whether header information is present in the `wrapper` instance.

This function checks if the `header` field of the `wrapper` is not nil, indicating that header information is included.

Returns:

  • A boolean value indicating whether header information is present:
  • `true` if `header` is not nil.
  • `false` if `header` is nil.

func (StreamingWrapper) IsInformational 

func (w StreamingWrapper) IsInformational() bool

IsInformational checks whether the HTTP status code indicates an informational response.

This function checks if the `statusCode` is between 100 and 199, inclusive, which indicates an informational HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is informational:
  • `true` if the status code is between 100 and 199 (inclusive).
  • `false` if the status code is outside of this range.

func (StreamingWrapper) IsJSONBody 

func (w StreamingWrapper) IsJSONBody() bool

IsJSONBody checks whether the body data is a valid JSON string.

This function first checks if the `wrapper` is available and if the body data is present using `IsBodyPresent()`. Then it uses the `JSON()` function to retrieve the body data as a JSON string and checks if it is valid using `fj.IsValidJSON()`.

Returns:

  • A boolean value indicating whether the body data is a valid JSON string:
  • `true` if the `wrapper` is available, the body data is present, and the body data is a valid JSON string.
  • `false` if the `wrapper` is not available, the body data is not present, or the body data is not a valid JSON string.

func (StreamingWrapper) IsLastPage 

func (w StreamingWrapper) IsLastPage() bool

IsLastPage checks whether the current page is the last page of results.

This function verifies that pagination information is present and then checks if the current page is the last page. It combines the checks of `IsPagingPresent()` and `IsLast()` to ensure that the pagination structure exists and that it represents the last page.

Returns:

  • A boolean value indicating whether the current page is the last page:
  • `true` if pagination is present and the current page is the last one.
  • `false` if pagination is not present or the current page is not the last.

func (StreamingWrapper) IsMetaPresent 

func (w StreamingWrapper) IsMetaPresent() bool

IsMetaPresent checks whether metadata information is present in the `wrapper` instance.

This function checks if the `meta` field of the `wrapper` is not nil, indicating that metadata is available.

Returns:

  • A boolean value indicating whether metadata is present:
  • `true` if `meta` is not nil.
  • `false` if `meta` is nil.

func (StreamingWrapper) IsPagingPresent 

func (w StreamingWrapper) IsPagingPresent() bool

IsPagingPresent checks whether pagination information is present in the `wrapper` instance.

This function checks if the `pagination` field of the `wrapper` is not nil, indicating that pagination details are included.

Returns:

  • A boolean value indicating whether pagination information is present:
  • `true` if `pagination` is not nil.
  • `false` if `pagination` is nil.

func (StreamingWrapper) IsRedirection 

func (w StreamingWrapper) IsRedirection() bool

IsRedirection checks whether the HTTP status code indicates a redirection response.

This function checks if the `statusCode` is between 300 and 399, inclusive, which indicates a redirection HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a redirection:
  • `true` if the status code is between 300 and 399 (inclusive).
  • `false` if the status code is outside of this range.

func (StreamingWrapper) IsServerError 

func (w StreamingWrapper) IsServerError() bool

IsServerError checks whether the HTTP status code indicates a server error.

This function checks if the `statusCode` is between 500 and 599, inclusive, which indicates a server error HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response is a server error:
  • `true` if the status code is between 500 and 599 (inclusive).
  • `false` if the status code is outside of this range.

func (StreamingWrapper) IsStatusCodePresent 

func (w StreamingWrapper) IsStatusCodePresent() bool

IsStatusCodePresent checks whether a valid status code is present in the `wrapper` instance.

This function checks if the `statusCode` field of the `wrapper` is greater than 0, indicating that a valid HTTP status code has been set.

Returns:

  • A boolean value indicating whether the status code is present:
  • `true` if `statusCode` is greater than 0.
  • `false` if `statusCode` is less than or equal to 0.

func (*StreamingWrapper) IsStreaming 

func (sw *StreamingWrapper) IsStreaming() bool

IsStreaming returns whether a streaming operation is currently in progress.

This function provides a thread-safe way to determine if the streaming process is actively running. It returns true only while the Start() method is executing and chunks are being processed; it returns false before streaming begins, after streaming completes successfully, after streaming is cancelled, or if an error terminates the operation. IsStreaming is useful for implementing timeouts, progress monitoring from external goroutines, implementing cancellation logic, and building interactive UIs that display transfer status. The function is non-blocking and performs a simple state check without acquiring expensive locks for resource operations. Multiple goroutines can safely call IsStreaming() concurrently without blocking each other. The return value reflects the streaming state at the moment of the call; subsequent calls may return different results if streaming status changes. This is the recommended method for querying streaming state without affecting the operation itself.

Returns:

  • true if streaming is currently active (Start() is executing, chunks being processed).
  • false if streaming has not started, has completed, was cancelled, or encountered an error.
  • false if the streaming wrapper is nil.
  • Thread-safe: multiple goroutines can call concurrently.
  • Non-blocking: returns immediately without waiting.
  • State snapshot: reflects state at call time; ongoing changes may alter result.

Streaming State Transitions: 

State Transition                         IsStreaming Before    IsStreaming After
──────────────────────────────────────────────────────────────────────────────────
New instance created                     N/A (not started)     false
WithStreaming() configured               false                 false (configured, not started)
Start() called                           false                 true (streaming begins)
First chunk read successfully            true                  true (streaming active)
Chunks processing mid-stream             true                  true (actively transferring)
Last chunk read (EOF)                    true                  true (processing final chunk)
Streaming completes successfully         true                  false (operation finished)
Cancel() called during streaming         true                  false (immediately stops)
Error during streaming                   true                  false (terminates on error)
Close() called (after streaming)         false                 false (no change to state)
New Start() after completion             false                 true (new streaming begins)

Streaming State Machine: 

     ┌─────────────────────┐
     │  NEW / CONFIGURED   │  IsStreaming: false
     │   (not started)     │
     └──────────┬──────────┘
                │ Start()
                ↓
     ┌─────────────────────┐
     │  STREAMING IN       │  IsStreaming: true
     │  PROGRESS           │
     └──────────┬──────────┘
                │
    ┌───────────┼───────────┐
    │           │           │
Cancel()    Error        EOF
    │           │           │
    ↓           ↓           ↓
┌──────────────────────────────────┐
│  STREAMING COMPLETED / STOPPED   │  IsStreaming: false
│  (result available in wrapper)   │
└──────────────────────────────────┘

IsStreaming vs Related State Checks: 

Method/Check                Returns          Purpose                          Cost
─────────────────────────────────────────────────────────────────────────────
IsStreaming()               bool             Is streaming currently active?   O(1)
HasErrors()                 bool             Did any errors occur?            O(1)
GetProgress()               *StreamProgress  What is current progress?        O(1)
GetStats()                  *StreamingStats  What are final statistics?       O(1)
GetWrapper().IsError()      bool             Did HTTP response error occur?   O(1)
GetWrapper().IsSuccess()    bool             Was response successful?         O(1)
Errors()                    []error          What were all errors?            O(n)

Use Cases and Patterns: 

Use Case                            Pattern                             Example
────────────────────────────────────────────────────────────────────────────────
Check if streaming active           if streaming.IsStreaming()          Monitoring
Wait for streaming to complete      for streaming.IsStreaming() { }    Polling loop
External timeout implementation     time.Sleep() + if not streaming()  Watchdog timer
UI progress indicator               while streaming.IsStreaming()      Progress display
Concurrent monitoring               go func() { isActive }             Background monitor
Graceful shutdown                   if streaming: cancel()             Service shutdown
State-aware error handling          if streaming: recover else: exit   Error recovery
Cancellation guard                  if streaming: cancel()             Safe cancellation

Example: 

// Example 1: Simple streaming state check
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024)

fmt.Printf("Before Start: IsStreaming = %v\n", streaming.IsStreaming())
// Output: Before Start: IsStreaming = false

result := streaming.Start(context.Background())

fmt.Printf("After Start: IsStreaming = %v\n", streaming.IsStreaming())
// Output: After Start: IsStreaming = false (completed)

// Example 2: Concurrent monitoring during streaming
dataExport := createDataReader()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/data").
    WithStreaming(dataExport, nil).
    WithChunkSize(512 * 1024).
    WithMaxConcurrentChunks(4)

// Start streaming in background
done := make(chan *wrapper)
go func() {
    result := streaming.Start(context.Background())
    done <- result
}()

// Monitor streaming from main goroutine
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()

for {
    select {
    case <-ticker.C:
        if streaming.IsStreaming() {
            progress := streaming.GetProgress()
            fmt.Printf("\rExporting: %.1f%% (%d chunks)",
                float64(progress.Percentage), progress.CurrentChunk)
        } else {
            fmt.Println("\nExport completed")
        }
    case result := <-done:
        if result.IsError() {
            fmt.Printf("Export failed: %s\n", result.Error())
        }
        return
    }
}

// Example 3: External timeout with IsStreaming check
func StreamWithTimeout(fileReader io.ReadCloser, timeout time.Duration) *wrapper {
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/timeout").
        WithStreaming(fileReader, nil).
        WithChunkSize(1024 * 1024)

    done := make(chan *wrapper)

    // Start streaming in background
    go func() {
        result := streaming.Start(context.Background())
        done <- result
    }()

    // Implement external timeout
    select {
    case result := <-done:
        // Streaming completed normally
        return result
    case <-time.After(timeout):
        // Timeout exceeded
        if streaming.IsStreaming() {
            fmt.Println("Timeout: streaming still active, cancelling...")
            streaming.Cancel()
            streaming.Close()
            return streaming.GetWrapper().
                WithStatusCode(408).
                WithMessage("Streaming timeout")
        }
        // Streaming already completed
        return <-done
    }
}

// Example 4: UI progress indicator (web/CLI)
type StreamingProgressUI struct {
    streaming *StreamingWrapper
    done      chan bool
}

func (ui *StreamingProgressUI) DisplayProgress() {
    ticker := time.NewTicker(100 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            // Check if still streaming (O(1) operation)
            if !ui.streaming.IsStreaming() {
                ui.FinalizeDisplay()
                ui.done <- true
                return
            }

            // Get progress (also O(1))
            progress := ui.streaming.GetProgress()

            // Render progress bar
            barLength := 30
            filled := int(float64(barLength) * float64(progress.Percentage) / 100)
            bar := strings.Repeat("█", filled) + strings.Repeat("░", barLength-filled)

            fmt.Printf("\r[%s] %.1f%% | %s",
                bar,
                float64(progress.Percentage),
                progress.EstimatedTimeRemaining.String())
        case <-ui.done:
            return
        }
    }
}

// Example 5: Graceful shutdown with IsStreaming guard
func GracefulShutdown(streaming *StreamingWrapper) {
    shutdownTimeout := 30 * time.Second
    shutdownDeadline := time.Now().Add(shutdownTimeout)

    // Check if streaming is active
    if streaming.IsStreaming() {
        fmt.Println("Streaming in progress, cancelling...")
        streaming.Cancel()

        // Wait for streaming to stop with timeout
        for time.Now().Before(shutdownDeadline) {
            if !streaming.IsStreaming() {
                fmt.Println("Streaming stopped")
                break
            }
            time.Sleep(100 * time.Millisecond)
        }

        if streaming.IsStreaming() {
            fmt.Println("Warning: streaming did not stop within timeout")
        }
    }

    // Cleanup
    streaming.Close()
    fmt.Println("Streaming resources released")
}

// Example 6: Safe cancellation with state guard
func SafeCancel(streaming *StreamingWrapper) *wrapper {
    // Guard: only cancel if actually streaming
    if streaming.IsStreaming() {
        return streaming.Cancel().
            WithMessage("Streaming cancelled by user").
            WithStatusCode(202) // 202 Accepted
    } else {
        return streaming.GetWrapper().
            WithMessage("Streaming is not active, nothing to cancel").
            WithStatusCode(400) // 400 Bad Request
    }
}

Polling Pattern for Waiting on Completion: 

// ❌ BAD: Busy-wait with no sleep (wastes CPU)
for streaming.IsStreaming() {
    // Spin loop - 100% CPU usage
}

// ⚠️  OKAY: Polling with fixed interval
for streaming.IsStreaming() {
    time.Sleep(100 * time.Millisecond)
}
// Cost: Periodic lock acquisition + context switch
// Use for: Simple cases, acceptable latency tolerance

// ✅ BETTER: Channel-based with callback
done := make(chan *wrapper)
go func() {
    result := streaming.Start(ctx)
    done <- result
}()
result := <-done
// Cost: Single context switch + goroutine
// Use for: Optimal, recommended approach

// ✅ BETTER: Context cancellation + timeout
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()
result := streaming.Start(ctx)
// Cost: Built-in timeout, integrates with context
// Use for: Timeout enforcement, recommended

Performance Characteristics: 

Operation                   Time Complexity    Space Complexity    Details
─────────────────────────────────────────────────────────────────────────
IsStreaming() call          O(1)               O(0)                Simple bool check
State machine lookup        <1μs               None                Immediate return
RWMutex read lock           O(1) amortized     None                Lock contention rare
Return value access         <1μs               None                Stack return
vs Errors() copy            100x faster        No allocation       Major advantage
Multiple concurrent calls   Parallel           None                No blocking

Thread-Safety and Concurrency: 

Scenario                                    Thread-Safe    Notes
──────────────────────────────────────────────────────────────────────
IsStreaming() during streaming              Yes            RWMutex read lock
Multiple concurrent IsStreaming()           Yes            Parallel reads allowed
IsStreaming() + Start() race                Yes            Predictable transition
IsStreaming() + Cancel() concurrently       Yes            Independent operations
IsStreaming() + Close() concurrently        Yes            Close doesn't change state
IsStreaming() in callback                   Yes            Called by streaming goroutine
High-frequency polling                      Safe           Lock contention minimal
Concurrent monitor goroutines               Yes            RWMutex prevents stale reads

State Consistency Guarantees: 

Guarantee                                   Behavior
──────────────────────────────────────────────────────────────────────
True when streaming is definitely active    Yes - can rely on true
False when streaming is definitely done     Yes - can rely on false
Immediate transition on Cancel()            Yes - false returned soon after
Consistent with GetProgress()               Yes - both read same state
Consistent with HasErrors()                 Maybe - different time calls
No false positives (says true but done)     Yes - guaranteed
No false negatives (says false but running) Yes - guaranteed

Common Patterns and Recommendations: 

Pattern                                 Recommendation        Use Case
─────────────────────────────────────────────────────────────────────
Simple status check                      Recommended ✓         "Is it still running?"
Polling loop with sleep                  Acceptable ⚠️         Simple monitoring
Busy-wait loop                           Bad ❌                 Wastes CPU
Channel-based completion                 Recommended ✓          Production systems
Context timeout                          Recommended ✓          Timeout enforcement
Concurrent monitoring goroutine          Recommended ✓          UI updates, logging
Progress indicator loop                  Recommended ✓          User feedback
Graceful shutdown logic                  Recommended ✓          Service shutdown

Related State Query Methods: 

Method                      Returns             When Streaming      When Completed
─────────────────────────────────────────────────────────────────────────────
IsStreaming()               bool                true                false
HasErrors()                 bool                maybe (any errors)  true/false
GetProgress()               *StreamProgress     Current progress    Final progress
GetStats()                  *StreamingStats     Partial stats       Complete stats
GetWrapper().IsError()      bool                maybe               true/false
GetWrapper().IsSuccess()    bool                maybe               true/false

See Also:

  • Start: Initiates streaming (sets IsStreaming to true)
  • Cancel: Stops streaming (sets IsStreaming to false)
  • Close: Releases resources (does not affect IsStreaming state)
  • GetProgress: Provides progress info (only meaningful if IsStreaming)
  • GetStats: Provides statistics (complete only after streaming done)
  • HasErrors: Checks for errors (independent of IsStreaming)
  • WithCallback: Receives updates during streaming (while IsStreaming true)

func (StreamingWrapper) IsSuccess 

func (w StreamingWrapper) IsSuccess() bool

IsSuccess checks whether the HTTP status code indicates a successful response.

This function checks if the `statusCode` is between 200 and 299, inclusive, which indicates a successful HTTP response.

Returns:

  • A boolean value indicating whether the HTTP response was successful:
  • `true` if the status code is between 200 and 299 (inclusive).
  • `false` if the status code is outside of this range.

func (StreamingWrapper) IsTotalPresent 

func (w StreamingWrapper) IsTotalPresent() bool

IsTotalPresent checks whether the total number of items is present in the `wrapper` instance.

This function checks if the `total` field of the `wrapper` is greater than or equal to 0, indicating that a valid total number of items has been set.

Returns:

  • A boolean value indicating whether the total is present:
  • `true` if `total` is greater than or equal to 0.
  • `false` if `total` is negative (indicating no total value).

func (StreamingWrapper) JSON 

func (w StreamingWrapper) JSON() string

JSON serializes the `wrapper` instance into a compact JSON string.

This function uses the `encoding.JSON` utility to generate a JSON representation of the `wrapper` instance. The output is a compact JSON string with no additional whitespace or formatting.

Returns:

  • A compact JSON string representation of the `wrapper` instance.

func (StreamingWrapper) JSONBodyContains 

func (w StreamingWrapper) JSONBodyContains(path, target string) bool

JSONBodyContains reports whether the value at the given path inside the body contains the target substring (case-sensitive).

Returns false when the path does not exist.

Example: 

w.JSONBodyContains("user.role", "admin")

func (StreamingWrapper) JSONBodyContainsMatch 

func (w StreamingWrapper) JSONBodyContainsMatch(path, pattern string) bool

JSONBodyContainsMatch reports whether the value at the given path inside the body matches the given wildcard pattern.

Returns false when the path does not exist.

Example: 

w.JSONBodyContainsMatch("user.email", "*@example.com")

func (StreamingWrapper) JSONBodyParser 

func (w StreamingWrapper) JSONBodyParser() fj.Context

JSONBodyParser parses the body of the wrapper as JSON and returns a fj.Context for the entire document. This is the entry point for all fj-based operations on the wrapper.

If the body is nil or cannot be serialized, a zero-value fj.Context is returned. Callers can check presence with ctx.Exists().

Example: 

ctx := w.JSONBodyParser()
fmt.Println(ctx.Get("user.name").String())

func (StreamingWrapper) JSONBytes 

func (w StreamingWrapper) JSONBytes() []byte

JSONBytes serializes the `wrapper` instance into a JSON byte slice.

This function first checks if the `wrapper` is available and if the body data is a valid JSON string using `IsJSONBody()`. If both conditions are met, it returns the JSON byte slice. Otherwise, it returns an empty byte slice.

Returns:

  • A byte slice containing the JSON representation of the `wrapper` instance.
  • An empty byte slice if the `wrapper` is not available or the body data is not a valid JSON string.

func (StreamingWrapper) JSONDebugging 

func (w StreamingWrapper) JSONDebugging() string

JSONDebugging retrieves the debugging information from the `wrapper` instance as a JSON string.

This function checks if the `wrapper` instance is available (non-nil) before returning the value of the `debug` field as a JSON string. If the `wrapper` is not available, it returns an empty string to ensure safe usage.

Returns:

  • A `string` containing the debugging information as a JSON string.
  • An empty string if the `wrapper` instance is not available.

func (StreamingWrapper) JSONDebuggingBool 

func (w StreamingWrapper) JSONDebuggingBool(path string, defaultValue bool) bool

JSONDebuggingBool retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A boolean value to return if the key is not available.

Returns:

  • The boolean value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingDuration 

func (w StreamingWrapper) JSONDebuggingDuration(path string, defaultValue time.Duration) time.Duration

JSONDebuggingDuration retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Duration value to return if the key is not available.

Returns:

  • The time.Duration value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingFloat32 

func (w StreamingWrapper) JSONDebuggingFloat32(path string, defaultValue float32) float32

JSONDebuggingFloat32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float32 value to return if the key is not available.

Returns:

  • The float32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingFloat64 

func (w StreamingWrapper) JSONDebuggingFloat64(path string, defaultValue float64) float64

JSONDebuggingFloat64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A float64 value to return if the key is not available.

Returns:

  • The float64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingInt 

func (w StreamingWrapper) JSONDebuggingInt(path string, defaultValue int) int

JSONDebuggingInt retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An integer value to return if the key is not available.

Returns:

  • The integer value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingInt8 

func (w StreamingWrapper) JSONDebuggingInt8(path string, defaultValue int8) int8

JSONDebuggingInt8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int8 value to return if the key is not available.

Returns:

  • The int8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingInt16 

func (w StreamingWrapper) JSONDebuggingInt16(path string, defaultValue int16) int16

JSONDebuggingInt16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int16 value to return if the key is not available.

Returns:

  • The int16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingInt32 

func (w StreamingWrapper) JSONDebuggingInt32(path string, defaultValue int32) int32

JSONDebuggingInt32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int32 value to return if the key is not available.

Returns:

  • The int32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingInt64 

func (w StreamingWrapper) JSONDebuggingInt64(path string, defaultValue int64) int64

JSONDebuggingInt64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: An int64 value to return if the key is not available.

Returns:

  • The int64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingString 

func (w StreamingWrapper) JSONDebuggingString(path string, defaultValue string) string

JSONDebuggingString retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A string value to return if the key is not available.

Returns:

  • The string value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingTime 

func (w StreamingWrapper) JSONDebuggingTime(path string, defaultValue time.Time) time.Time

JSONDebuggingTime retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A time.Time value to return if the key is not available.

Returns:

  • The time.Time value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingUint 

func (w StreamingWrapper) JSONDebuggingUint(path string, defaultValue uint) uint

JSONDebuggingUint retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint value to return if the key is not available.

Returns:

  • The uint value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingUint8 

func (w StreamingWrapper) JSONDebuggingUint8(path string, defaultValue uint8) uint8

JSONDebuggingUint8 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint8 value to return if the key is not available.

Returns:

  • The uint8 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingUint16 

func (w StreamingWrapper) JSONDebuggingUint16(path string, defaultValue uint16) uint16

JSONDebuggingUint16 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint16 value to return if the key is not available.

Returns:

  • The uint16 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingUint32 

func (w StreamingWrapper) JSONDebuggingUint32(path string, defaultValue uint32) uint32

JSONDebuggingUint32 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint32 value to return if the key is not available.

Returns:

  • The uint32 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONDebuggingUint64 

func (w StreamingWrapper) JSONDebuggingUint64(path string, defaultValue uint64) uint64

JSONDebuggingUint64 retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `defaultValue` to indicate the key is not available.

Parameters:

  • `path`: A string representing the debugging key to retrieve.
  • `defaultValue`: A uint64 value to return if the key is not available.

Returns:

  • The uint64 value associated with the specified debugging key if it exists.
  • `defaultValue` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) JSONPretty 

func (w StreamingWrapper) JSONPretty() string

JSONPretty serializes the `wrapper` instance into a prettified JSON string.

This function uses the `encoding.JSONPretty` utility to generate a JSON representation of the `wrapper` instance. The output is a human-readable JSON string with proper indentation and formatting for better readability.

Returns:

  • A prettified JSON string representation of the `wrapper` instance.

func (StreamingWrapper) MaxJSONBody 

func (w StreamingWrapper) MaxJSONBody(path string) (float64, bool)

MaxJSONBody returns the maximum numeric value at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

v, ok := w.MaxJSONBody("scores")

func (StreamingWrapper) Message 

func (w StreamingWrapper) Message() string

Message retrieves the message associated with the `wrapper` instance.

This function returns the `message` field of the `wrapper`, which typically provides additional context or a description of the operation's outcome.

Returns:

  • A string representing the message.

func (StreamingWrapper) Meta 

func (w StreamingWrapper) Meta() *meta

Meta retrieves the `meta` information from the `wrapper` instance.

This function returns the `meta` field, which contains metadata related to the response or data in the `wrapper` instance. If no `meta` information is set, it returns `nil`.

Returns:

  • A pointer to the `meta` instance associated with the `wrapper`.
  • `nil` if no `meta` information is available.

func (StreamingWrapper) MinJSONBody 

func (w StreamingWrapper) MinJSONBody(path string) (float64, bool)

MinJSONBody returns the minimum numeric value at the given path in the body. Returns (0, false) when no numeric values are found.

Example: 

v, ok := w.MinJSONBody("scores")

func (StreamingWrapper) MustHash 

func (w StreamingWrapper) MustHash() (uint64, *wrapper)

MustHash generates a hash value for the `wrapper` instance.

This method generates a hash value for the `wrapper` instance using the `MustHash` method. If the `wrapper` instance is not available or the hash generation fails, it returns an error.

Returns:

  • A uint64 representing the hash value.
  • An error if the `wrapper` instance is not available or the hash generation fails.

func (StreamingWrapper) MustHash256 

func (w StreamingWrapper) MustHash256() (string, *wrapper)

MustHash256 generates a hash string for the `wrapper` instance.

This method concatenates the values of the `statusCode`, `message`, `data`, and `meta` fields into a single string and then computes a hash of that string using the `strutil.MustHash256` function. The resulting hash string can be used for various purposes, such as caching or integrity checks.

func (StreamingWrapper) NormAll 

func (w StreamingWrapper) NormAll() *wrapper

NormAll performs a comprehensive normalization of the wrapper instance.

It sequentially calls the following normalization methods:

  • NormHSC
  • NormPaging
  • NormMeta
  • NormBody
  • NormMessage

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormBody 

func (w StreamingWrapper) NormBody() *wrapper

NormBody normalizes the data/body field in the wrapper.

This method ensures that the data field is properly handled:

  • If data is nil and status code indicates success with content, logs a warning (optional)
  • Validates that data type is consistent with the response type
  • For list/array responses, ensures total count is synchronized

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormDebug 

func (w StreamingWrapper) NormDebug() *wrapper

NormDebug normalizes the debug information in the wrapper.

This method removes any debug entries that have nil values to ensure the debug map only contains meaningful information.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormHSC 

func (w StreamingWrapper) NormHSC() *wrapper

NormHSC normalizes the relationship between the header and status code.

If the status code is not present but the header is, it sets the status code from the header's code. If the header is not present but the status code is, it creates a new header with the status code and its corresponding text.

If both the status code and header are present, it ensures the status code matches the header's code.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormMessage 

func (w StreamingWrapper) NormMessage() *wrapper

NormMessage normalizes the message field in the wrapper.

If the message is empty and a status code is present, it sets a default message based on the status code category (success, redirection, client error, server error).

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormMeta 

func (w StreamingWrapper) NormMeta() *wrapper

NormMeta normalizes the metadata in the wrapper.

If the meta object is not already initialized, it creates a new one using the `Meta` function. It then ensures that essential fields such as locale, API version, request ID, and requested time are set to default values if they are not already present.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) NormPaging 

func (w StreamingWrapper) NormPaging() *wrapper

NormPaging normalizes the pagination information in the wrapper.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. It then calls the `Normalize` method on the pagination instance to ensure its values are consistent.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) OnDebugging 

func (w StreamingWrapper) OnDebugging(key string) any

OnDebugging retrieves the value of a specific debugging key from the `wrapper` instance.

This function checks if the `wrapper` is available (non-nil) and if the specified debugging key is present in the `debug` map. If both conditions are met, it returns the value associated with the specified key. Otherwise, it returns `nil` to indicate the key is not available.

Parameters:

  • `key`: A string representing the debugging key to retrieve.

Returns:

  • The value associated with the specified debugging key if it exists.
  • `nil` if the `wrapper` is unavailable or the key is not present in the `debug` map.

func (StreamingWrapper) Pagination 

func (w StreamingWrapper) Pagination() *pagination

Pagination retrieves the `pagination` instance associated with the `wrapper`.

This function returns the `pagination` field of the `wrapper`, allowing access to pagination details such as the current page, total pages, and total items. If no pagination information is available, it returns `nil`.

Returns:

  • A pointer to the `pagination` instance if available.
  • `nil` if the `pagination` field is not set.

func (StreamingWrapper) PluckJSONBody 

func (w StreamingWrapper) PluckJSONBody(path string, fields ...string) []fj.Context

PluckJSONBody evaluates the given path in the body (expected: array of objects) and returns a new object for each element containing only the specified fields.

Example: 

rows := w.PluckJSONBody("users", "id", "email")

func (StreamingWrapper) QueryJSONBody 

func (w StreamingWrapper) QueryJSONBody(path string) fj.Context

QueryJSONBody retrieves the value at the given fj dot-notation path from the wrapper's body. The body is serialized to JSON on each call; for repeated queries on the same body, use BodyCtx() once and chain calls on the returned Context.

Parameters:

  • path: A fj dot-notation path (e.g. "user.name", "items.#.id", "roles.0").

Returns:

  • A fj.Context for the matched value. Call .Exists() to check presence.

Example: 

name := w.QueryJSONBody("user.name").String()

func (StreamingWrapper) QueryJSONBodyMulti 

func (w StreamingWrapper) QueryJSONBodyMulti(paths ...string) []fj.Context

QueryJSONBodyMulti evaluates multiple fj paths against the body in a single pass and returns one fj.Context per path in the same order.

Parameters:

  • paths: One or more fj dot-notation paths.

Returns:

  • A slice of fj.Context values, one per path.

Example: 

results := w.QueryJSONBodyMulti("user.id", "user.email", "roles.#")

func (StreamingWrapper) RandDeltaValue 

func (w StreamingWrapper) RandDeltaValue() *wrapper

RandDeltaValue generates and sets a random delta value in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `RandDeltaValue` method on the `meta` instance to generate and set a random delta value.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) RandRequestID 

func (w StreamingWrapper) RandRequestID() *wrapper

RandRequestID generates and sets a random request ID in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `RandRequestID` method on the `meta` instance to generate and set a random request ID.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) Reply 

func (w StreamingWrapper) Reply() R

R represents a wrapper around the main `wrapper` struct. It is used as a high-level abstraction to provide a simplified interface for handling API responses. The `R` type allows for easier manipulation of the wrapped data, metadata, and other response components, while maintaining the flexibility of the underlying `wrapper` structure.

Example usage: 

var response replify.R = replify.New().Reply()
fmt.Println(response.JSON())  // Prints the wrapped response details, including data, headers, and metadata.

func (StreamingWrapper) ReplyPtr 

func (w StreamingWrapper) ReplyPtr() *R

ReplyPtr returns a pointer to a new R instance that wraps the current `wrapper`.

This method creates a new `R` struct, initializing it with the current `wrapper` instance, and returns a pointer to this new `R` instance. This allows for easier manipulation of the wrapped data and metadata through the `R` abstraction.

Returns:

  • A pointer to an `R` struct that wraps the current `wrapper` instance.

Example usage: 

var responsePtr *replify.R = replify.New().ReplyPtr()
fmt.Println(responsePtr.JSON())  // Prints the wrapped response details, including data, headers, and metadata.

func (StreamingWrapper) Reset 

func (w StreamingWrapper) Reset() *wrapper

Reset resets the `wrapper` instance to its initial state.

This function sets the `wrapper` instance to its initial state by resetting the `statusCode`, `total`, `message`, `path`, `cacheHash`, `data`, `debug`, `header`, `errors`, `pagination`, and `cachedWrap` fields to their default values. It also resets the `meta` instance to its initial state.

Returns:

  • A pointer to the reset `wrapper` instance.
  • `nil` if the `wrapper` instance is not available.

func (StreamingWrapper) Respond 

func (w StreamingWrapper) Respond() map[string]any

Respond generates a map representation of the `wrapper` instance.

This method collects various fields of the `wrapper` (e.g., `data`, `header`, `meta`, etc.) and organizes them into a key-value map. Only non-nil or meaningful fields are added to the resulting map to ensure a clean and concise response structure.

Fields included in the response:

  • `data`: The primary data payload, if present.
  • `headers`: The structured header details, if present.
  • `meta`: Metadata about the response, if present.
  • `pagination`: Pagination details, if applicable.
  • `debug`: Debugging information, if provided.
  • `total`: Total number of items, if set to a valid non-negative value.
  • `status_code`: The HTTP status code, if greater than 0.
  • `message`: A descriptive message, if not empty.
  • `path`: The request path, if not empty.

Returns:

  • A `map[string]interface{}` containing the structured response data.

func (StreamingWrapper) SearchJSONBody 

func (w StreamingWrapper) SearchJSONBody(keyword string) []fj.Context

SearchJSONBody performs a full-tree scan of the body JSON and returns all scalar leaf values whose string representation contains the given keyword (case-sensitive substring match).

Parameters:

  • keyword: The substring to search for. An empty keyword matches every leaf.

Returns:

  • A slice of fj.Context values whose string representation contains keyword.

Example: 

hits := w.SearchJSONBody("admin")
for _, h := range hits {
    fmt.Println(h.String())
}

func (StreamingWrapper) SearchJSONBodyByKey 

func (w StreamingWrapper) SearchJSONBodyByKey(keys ...string) []fj.Context

SearchJSONBodyByKey performs a full-tree scan of the body JSON and returns all values stored under any of the given key names, regardless of nesting depth.

Parameters:

  • keys: One or more exact object key names to look up.

Example: 

emails := w.SearchJSONBodyByKey("email")

func (StreamingWrapper) SearchJSONBodyByKeyPattern 

func (w StreamingWrapper) SearchJSONBodyByKeyPattern(keyPattern string) []fj.Context

SearchJSONBodyByKeyPattern performs a full-tree wildcard scan of the body JSON and returns all values stored under object keys that match the given pattern.

Parameters:

  • keyPattern: A wildcard pattern applied to object key names.

Example: 

hits := w.SearchJSONBodyByKeyPattern("user*")

func (StreamingWrapper) SearchJSONBodyMatch 

func (w StreamingWrapper) SearchJSONBodyMatch(pattern string) []fj.Context

SearchJSONBodyMatch performs a full-tree wildcard scan of the body JSON and returns all scalar leaf values whose string representation matches the given pattern.

The pattern supports '*' (any sequence) and '?' (single character) wildcards.

Parameters:

  • pattern: A wildcard pattern applied to leaf string values.

Example: 

hits := w.SearchJSONBodyMatch("admin*")

func (StreamingWrapper) SortJSONBody 

func (w StreamingWrapper) SortJSONBody(path, keyField string, ascending bool) []fj.Context

SortJSONBody sorts the elements at the given path in the body by the value of keyField. Numeric fields are compared as float64; all others fall back to string comparison.

Parameters:

  • path: A fj path resolving to an array.
  • keyField: The field to sort by. Pass "" to sort scalar arrays.
  • ascending: Sort direction.

Example: 

sorted := w.SortJSONBody("products", "price", true)

func (*StreamingWrapper) Start 

func (sw *StreamingWrapper) Start(ctx context.Context) *wrapper

Start initiates streaming operation and returns *wrapper for consistency with replify API.

This function is the primary entry point for streaming operations. It validates prerequisites (streaming wrapper not nil, reader configured), prevents concurrent streaming on the same wrapper, selects and executes the configured streaming strategy (STRATEGY_DIRECT, STRATEGY_BUFFERED, or STRATEGY_CHUNKED), monitors operation completion, and returns a comprehensive response wrapping the result in the standard wrapper format. Start is the public API method that callers use to begin streaming; it handles all coordination, error management, and response formatting. The function sets up initial timestamps, manages the isStreaming state flag to prevent concurrent operations, executes the strategy-specific streaming function with the provided context, and populates the wrapper response with final statistics, metadata, and outcome information. Both success and failure paths return a *wrapper object with appropriate HTTP status codes, messages, and debugging information for client feedback and diagnostics. The streaming operation respects context cancellation, allowing caller-controlled shutdown. All per-chunk errors are accumulated; streaming continues when possible, enabling partial success scenarios. Final statistics include chunk counts, byte counts, compression metrics, timing information, and error tracking, providing comprehensive insight into streaming performance and health.

Parameters:

  • ctx: Context for cancellation, timeouts, and coordination. If nil, uses sw.ctx (context from streaming wrapper creation). Passed to streaming strategy function for deadline enforcement. Cancellation stops streaming immediately. Parent context may have deadline affecting overall operation.

Returns:

  • *wrapper: Response wrapper containing streaming result. HTTP status code (200, 400, 409, 500). Message describing outcome. Debugging information with statistics. Error information if operation failed. Always returns non-nil wrapper for consistency.

Behavior:

  • Validation: checks nil wrapper, reader configuration.
  • Mutual exclusion: prevents concurrent streaming on same wrapper.
  • Strategy selection: routes to appropriate streaming implementation.
  • Error accumulation: collects per-chunk errors without stopping.
  • Response building: wraps result in standard wrapper format.
  • Statistics: populates final metrics and timing data.
  • Status codes: HTTP codes reflecting outcome (200, 400, 409, 500).

Validation Stages: 

Stage                               Check                           Response if Failed
──────────────────────────────────────────────────────────────────────────────────────
1. Nil wrapper                      sw == nil                       Default bad request
2. Reader configured                sw.reader != nil                400 Bad Request
3. Not already streaming            !sw.isStreaming                 409 Conflict
4. Strategy known                   Valid STRATEGY_* constant       500 Internal Server Error

HTTP Status Code Mapping: 

Scenario                                    Status Code     Message
──────────────────────────────────────────────────────────────────────────
Streaming wrapper is nil                    400             (default response)
Reader not configured                       400             "reader not set for streaming"
Streaming already in progress               409             "streaming already in progress"
Unknown streaming strategy                  500             "unknown streaming strategy: ..."
Streaming operation failed (error)          500             "streaming error: ..."
Streaming completed successfully            200             "Streaming completed successfully"

Pre-Streaming Checks Flow: 

Input (sw, ctx)
    ↓
sw == nil?
    ├─ Yes → Return respondStreamBadRequestDefault()
    └─ No  → Continue
    ↓
sw.reader == nil?
    ├─ Yes → Return 400 "reader not set for streaming"
    └─ No  → Continue
    ↓
sw.isStreaming (with lock)?
    ├─ Yes → Return 409 "streaming already in progress"
    └─ No  → Set isStreaming = true, Continue
    ↓
Proceed to strategy selection

Streaming Lifecycle: 

Phase                               Action                          State
──────────────────────────────────────────────────────────────────────────
1. Initialization                   Lock and set isStreaming        Locked
2. Setup                            Create context (use or default) Ready
3. Logging                          Log start time in debugging KV  Tracked
4. Strategy dispatch                Call appropriate stream function Executing
5. Error collection                 Monitor for streamErr           In-flight
6. Finalization                     Lock and clear isStreaming      Cleanup
7. Response building (success)      Populate success statistics     Response ready
8. Response building (failure)      Populate error information      Error response ready
9. Return                           Return wrapper to caller        Complete

Context Handling: 

Scenario                                    Behavior                        Implication
──────────────────────────────────────────────────────────────────────────────
ctx provided and non-nil                    Use provided context            Caller controls deadline
ctx is nil                                  Use sw.ctx (if set)             Fallback to wrapper context
Both nil                                    Pass nil to strategy            No deadline enforcement
Parent context has deadline                 Inherited by strategy           Affects all operations
Cancellation via context                    Strategy responds to Done()     Responsive shutdown

Strategy Selection: 

Configuration                   Selected Function           Characteristics
──────────────────────────────────────────────────────────────────────────
STRATEGY_DIRECT                 streamDirect()              Sequential, simple
STRATEGY_BUFFERED               streamBuffered()            Concurrent, high throughput
STRATEGY_CHUNKED                streamChunked()             Sequential, detailed control
Unknown strategy                Error return                500 status, error message

State Management (isStreaming flag): 

Operation                           Lock Held    isStreaming Value    Purpose
──────────────────────────────────────────────────────────────────────────
Pre-check (initial state)           Yes          false                Prevent concurrent start
Set streaming active                Yes          true                 Mark operation in progress
Unlock after setting                No           true                 Allow other operations
Stream execution                    No           true                 Streaming active
Set streaming inactive              Yes          false                Streaming complete

Success Response Building: 

Field                           Source                      Format                  Purpose
────────────────────────────────────────────────────────────────────────────────────────
StatusCode                      Constant                    200 (HTTP OK)           Success indicator
Message                         Constant                    "Streaming completed..." User-facing message
completed_at                    sw.stats.EndTime.Unix()     Unix timestamp          When completed
total_chunks                    sw.stats.TotalChunks        int64                   Chunk count
total_bytes                     sw.stats.TotalBytes         int64                   Byte count
compressed_bytes                sw.stats.CompressedBytes    int64                   Compressed size
compression_ratio               sw.stats.CompressionRatio   "0.xx" format           Ratio display
duration_ms                     EndTime - StartTime         Milliseconds            Operation duration

Failure Response Building: 

Field                           Source                      Format                  Purpose
────────────────────────────────────────────────────────────────────────────────────────
StatusCode                      Constant                    500 (HTTP error)        Failure indicator
Error (via WithErrorAck)          streamErr                   Error message           Error details
failed_chunks                   sw.stats.FailedChunks       int64                   Failed chunk count
total_errors                    len(sw.errors)              int64                   Error count

Example: 

// Example 1: Simple streaming with default context
file, _ := os.Open("large_file.bin")
defer file.Close()

streaming := replify.New().
    WithStatusCode(200).
    WithPath("/api/stream/start").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithStreamingStrategy(STRATEGY_DIRECT).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 100 == 0 {
            fmt.Printf("Progress: %.1f%%\n", p.Percentage)
        }
    })

// Start streaming (uses nil context, falls back to wrapper's context)
result := streaming.Start(nil)

if result.IsError() {
    fmt.Printf("Error: %s\n", result.Error())
} else {
    fmt.Printf("Success: %s\n", result.Message())
    fmt.Printf("Chunks: %v\n", result.Debugging()["total_chunks"])
}

// Example 2: Streaming with cancellation context
func StreamWithTimeout(fileReader io.ReadCloser) *wrapper {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
    defer cancel()

    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/timeout").
        WithStreaming(fileReader, nil).
        WithChunkSize(512 * 1024).
        WithStreamingStrategy(STRATEGY_BUFFERED).
        WithMaxConcurrentChunks(4)

    // Start with context timeout
    result := streaming.Start(ctx)

    return result
}

// Example 3: Comprehensive error handling
func StreamWithCompleteErrorHandling(fileReader io.ReadCloser) {
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/errors").
        WithStreaming(fileReader, nil).
        WithChunkSize(256 * 1024).
        WithStreamingStrategy(STRATEGY_CHUNKED).
        WithCompressionType(COMP_GZIP).
        WithCallback(func(p *StreamProgress, err error) {
            if err != nil {
                fmt.Printf("Chunk %d failed: %v\n", p.CurrentChunk, err)
            }
        })

    result := streaming.Start(context.Background())

    // Analyze result
    if result.IsError() {
        fmt.Printf("Status: %d\n", result.StatusCode())
        fmt.Printf("Error: %s\n", result.Error())

        debugging := result.Debugging()
        fmt.Printf("Failed chunks: %v\n", debugging["failed_chunks"])
        fmt.Printf("Total errors: %v\n", debugging["total_errors"])
    } else {
        fmt.Printf("Status: %d\n", result.StatusCode())
        fmt.Printf("Message: %s\n", result.Message())

        debugging := result.Debugging()
        fmt.Printf("Total chunks: %v\n", debugging["total_chunks"])
        fmt.Printf("Total bytes: %v\n", debugging["total_bytes"])
        fmt.Printf("Compression ratio: %v\n", debugging["compression_ratio"])
        fmt.Printf("Duration: %vms\n", debugging["duration_ms"])
    }
}

// Example 4: Streaming with concurrent protection check
func DemonstrateConcurrencyProtection(fileReader io.ReadCloser) {
    streaming := replify.New().
        WithStatusCode(200).
        WithPath("/api/stream/concurrency").
        WithStreaming(fileReader, nil).
        WithChunkSize(1024 * 1024)

    // First call succeeds
    result1 := streaming.Start(context.Background())
    fmt.Printf("First start: %d\n", result1.StatusCode())  // 200

    // Second call (if first is slow) would get:
    // result2 := streaming.Start(context.Background())
    // fmt.Printf("Second start: %d\n", result2.StatusCode())  // 409 Conflict
}

// Example 5: All three strategies comparison
func CompareStreamingStrategies(fileReader io.ReadCloser) {
    strategies := []interface {}{
        STRATEGY_DIRECT,
        STRATEGY_CHUNKED,
        STRATEGY_BUFFERED,
    }

    for _, strategy := range strategies {
        fmt.Printf("\nTesting strategy: %v\n", strategy)

        // Create fresh streaming wrapper for each strategy
        newReader := createNewReader()  // Create fresh reader

        streaming := replify.New().
            WithStatusCode(200).
            WithPath("/api/stream/compare").
            WithStreaming(newReader, nil).
            WithChunkSize(512 * 1024).
            WithStreamingStrategy(strategy)

        if strategy == STRATEGY_BUFFERED {
            streaming = streaming.WithMaxConcurrentChunks(4)
        }

        start := time.Now()
        result := streaming.Start(context.Background())
        duration := time.Since(start)

        if result.IsError() {
            fmt.Printf("  Status: %d (ERROR)\n", result.StatusCode())
        } else {
            debugging := result.Debugging()
            fmt.Printf("  Status: %d (OK)\n", result.StatusCode())
            fmt.Printf("  Duration: %v\n", duration)
            fmt.Printf("  Chunks: %v\n", debugging["total_chunks"])
            fmt.Printf("  Bytes: %v\n", debugging["total_bytes"])
        }
    }
}

Mutual Exclusion Pattern: 

Scenario                            Behavior                            Response
────────────────────────────────────────────────────────────────────────────────
First Start() call                  Acquires lock, sets isStreaming    Proceeds normally
Concurrent Start() during streaming Checks isStreaming, finds true     409 Conflict
Start() after completion            isStreaming cleared, lock free    Proceeds normally
Rapid successive calls              Mutex serializes access           First waits, others get 409

Error Propagation: 

Error Origin                    Recorded?       Returned in Response?       Status Code
──────────────────────────────────────────────────────────────────────────────────
Reader validation               No              Yes (in message)            400
Concurrent streaming            No              Yes (in message)            409
Unknown strategy                Yes             Yes (via streamErr)         500
Strategy execution (streaming)  Yes             Yes (via streamErr)         500
Per-chunk errors                Yes             Yes (via failed_chunks)     200 or 500

Statistics Tracking: 

Metric                          Updated By                      When Updated
────────────────────────────────────────────────────────────────────────────
StartTime                       Start()                         At initialization
EndTime                         Start() after strategy returns   After streaming
TotalChunks                     updateProgress()                Per chunk
TotalBytes                      updateProgress()                Per chunk
CompressedBytes                 Strategy functions              Per chunk (if compressed)
CompressionRatio                GetStats() calculation          On query
FailedChunks                    Strategy on error               On chunk error
Errors list                     recordError()                   On any error

Best Practices:

  1. ALWAYS HANDLE RETURNED WRAPPER RESPONSE - Check status code for success/failure - Log or report error messages - Provide debugging info to caller - Pattern: result := streaming.Start(ctx) if result.IsError() { // Handle error } else { // Handle success }

  2. PROVIDE CONTEXT WITH DEADLINE WHEN POSSIBLE - Enables timeout enforcement - Allows caller-controlled shutdown - Prevents indefinite blocking - Pattern: ctx, cancel := context.WithTimeout(context.Background(), timeout) defer cancel() result := streaming.Start(ctx)

  3. USE CALLBACKS FOR PROGRESS MONITORING - Receive updates per chunk - Track errors in real-time - Update UI/logs continuously - Pattern: WithCallback(func(p *StreamProgress, err error) { // Handle progress or error })

  4. CHOOSE STRATEGY BASED ON USE CASE - STRATEGY_DIRECT: simplicity, small files - STRATEGY_CHUNKED: control, detailed tracking - STRATEGY_BUFFERED: throughput, large files - Pattern: WithStreamingStrategy(STRATEGY_BUFFERED)

  5. EXAMINE DEBUGGING INFO FOR DIAGNOSTICS - Check failed_chunks count - Review total_errors - Analyze compression_ratio - Track duration_ms for performance - Pattern: debugging := result.Debugging() if debugging["failed_chunks"] > 0 { // Investigate failures }

Related Methods and Lifecycle: 

Method                      Purpose                     Related To
──────────────────────────────────────────────────────────────────
Start()                     Initiate streaming (this)   Entry point
WithStreaming()             Configure reader/writer     Pre-streaming setup
WithStreamingStrategy()     Select strategy             Pre-streaming setup
streamDirect()              Direct execution            Called by Start
streamChunked()             Chunked execution           Called by Start
streamBuffered()            Buffered execution          Called by Start
GetStats()                  Query final statistics      Post-streaming
GetProgress()               Query current progress      During/after streaming
Cancel()                    Stop streaming              Control operation
Errors()                    Retrieve error list         Post-streaming analysis

See Also:

  • WithStreamingStrategy: Configure streaming approach before Start
  • WithStreaming: Set reader/writer configuration
  • WithChunkSize: Configure chunk size
  • GetStats: Query final statistics after Start completes
  • GetProgress: Query current progress during streaming
  • Cancel: Stop streaming operation
  • Errors: Retrieve accumulated error list
  • context.WithTimeout: Create context with deadline
  • context.WithCancel: Create cancellable context

func (StreamingWrapper) StatusCode 

func (w StreamingWrapper) StatusCode() int

StatusCode retrieves the HTTP status code associated with the `wrapper` instance.

This function returns the `statusCode` field of the `wrapper`, which represents the HTTP status code for the response, indicating the outcome of the request.

Returns:

  • An integer representing the HTTP status code.

func (StreamingWrapper) StatusText 

func (w StreamingWrapper) StatusText() string

StatusText returns a human-readable string representation of the HTTP status.

This function combines the status code with its associated status text, which is retrieved using the `http.StatusText` function from the `net/http` package. The returned string follows the format "statusCode (statusText)".

For example, if the status code is 200, the function will return "200 (OK)". If the status code is 404, it will return "404 (Not Found)".

Returns:

  • A string formatted as "statusCode (statusText)", where `statusCode` is the numeric HTTP status code and `statusText` is the corresponding textual description.

func (StreamingWrapper) Stream 

func (w StreamingWrapper) Stream() <-chan []byte

Stream retrieves a channel that streams the body data of the `wrapper` instance.

This function checks if the body data is present and, if so, streams the data in chunks. It creates a buffered channel to hold the streamed data, allowing for asynchronous processing of the response body. If the body is not present, it returns an empty channel. The streaming is done in a separate goroutine to avoid blocking the main execution flow. The body data is chunked into smaller parts using the `Chunk` function, which splits the response data into manageable segments for efficient streaming.

Returns:

  • A channel of byte slices that streams the body data.
  • An empty channel if the body data is not present.

This is useful for handling large responses in a memory-efficient manner, allowing the consumer to process each chunk as it becomes available. Note: The channel is closed automatically when the streaming is complete. If the body is not present, it returns an empty channel.

func (*StreamingWrapper) StreamingContext 

func (sw *StreamingWrapper) StreamingContext() context.Context

StreamingContext returns the context associated with the streaming operation.

This function provides access to the context.Context object that was used to initiate the streaming process. The returned context can be used for cancellation, deadlines, and passing request-scoped values throughout the streaming lifecycle. StreamingContext is useful for integrating with other context-aware components, propagating cancellation signals, and accessing metadata associated with the streaming operation. If the streaming wrapper is nil, StreamingContext returns a background context as a safe fallback. The returned context is read-only; modifications should be done on the original context passed into the Start() method. This function is thread-safe and can be called at any time during or after streaming.

func (StreamingWrapper) SumJSONBody 

func (w StreamingWrapper) SumJSONBody(path string) float64

SumJSONBody returns the sum of all numeric values at the given path in the body. Non-numeric elements are ignored. Returns 0 when no numbers are found.

Example: 

total := w.SumJSONBody("items.#.price")

func (StreamingWrapper) Total 

func (w StreamingWrapper) Total() int

Total retrieves the total number of items associated with the `wrapper` instance.

This function returns the `total` field of the `wrapper`, which indicates the total number of items available, often used in paginated responses.

Returns:

  • An integer representing the total number of items.

func (StreamingWrapper) ValidJSONBody 

func (w StreamingWrapper) ValidJSONBody() bool

ValidJSONBody reports whether the body of the wrapper is valid JSON.

Returns:

  • true if the body serializes to well-formed JSON; false otherwise.

Example: 

if !w.ValidJSONBody() {
    log.Println("body is not valid JSON")
}

func (StreamingWrapper) WithApiVersion 

func (w StreamingWrapper) WithApiVersion(v string) *wrapper

WithApiVersion sets the API version in the `meta` field of the `wrapper` instance.

This function checks if the `meta` information is present in the `wrapper`. If it is not, a new `meta` instance is created. Then, it calls the `WithApiVersion` method on the `meta` instance to set the API version.

Parameters:

  • `v`: A string representing the API version to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithApiVersionf 

func (w StreamingWrapper) WithApiVersionf(format string, args ...any) *wrapper

WithApiVersionf sets the API version in the `meta` field of the `wrapper` instance using a formatted string.

This function ensures that the `meta` field in the `wrapper` is initialized. If the `meta` field is not present, a new `meta` instance is created using the `NewMeta` function. Once the `meta` instance is ready, it updates the API version using the `WithApiVersionf` method on the `meta` instance. The API version is constructed by interpolating the provided `format` string with the variadic arguments (`args`).

Parameters:

  • format: A format string used to construct the API version.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (StreamingWrapper) WithBody 

func (w StreamingWrapper) WithBody(v any) *wrapper

WithBody sets the body data for the `wrapper` instance.

This function updates the `data` field of the `wrapper` with the provided value and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: The value to be set as the body data, which can be any type.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

Example: 

w, err := replify.New().WithBody(myStruct)

Notes:

  • This function does not validate or normalize the input value.
  • It simply assigns the value to the `data` field of the `wrapper`.
  • The value will be marshalled to JSON when the `wrapper` is converted to a string.
  • Consider using WithJSONBody instead if you need to normalize the input value.

func (*StreamingWrapper) WithBufferPooling 

func (sw *StreamingWrapper) WithBufferPooling(enabled bool) *wrapper

WithBufferPooling enables or disables buffer pooling for efficient memory reuse during streaming.

This function controls whether streaming operations reuse allocated buffers through a pool mechanism or allocate fresh buffers for each chunk. Buffer pooling reduces garbage collection pressure, improves memory allocation efficiency, and can provide 10-20% performance improvement for streaming operations. However, it adds minimal overhead (5-10%) when disabled for very small files or low-frequency operations. When enabled, buffers are allocated once and recycled across chunks, reducing GC pause times and memory fragmentation. The buffer pooling state is recorded in wrapper debugging information for performance analysis, optimization tracking, and resource management auditing.

Parameters:

  • enabled: Boolean flag controlling buffer pooling behavior.

- True: Enable buffer pooling (recommended for most scenarios).

- Pros:

  • 10-20% performance improvement on sustained transfers
  • Reduced garbage collection overhead and GC pause times
  • Lower memory fragmentation and allocation pressure
  • Stable memory usage over time (less heap churn)
  • Better for long-running servers and high-throughput scenarios

- Cons:

  • Minimal memory overhead (~4 buffers pooled)
  • Negligible overhead for single-request scenarios
  • Use case: Production servers, sustained transfers, high-concurrency scenarios

- False: Disable buffer pooling (allocation per chunk).

- Pros:

  • Slightly lower startup memory overhead
  • No pool management overhead for very small files
  • Pure Go standard library behavior

- Cons:

  • 10-20% slower for large transfers (GC overhead)

  • More garbage collection pressure

  • Higher memory fragmentation

  • GC pause times increase with file size

  • Use case: One-time transfers, small files (<10MB), memory-constrained environments

    Default: true (pooling enabled, recommended).

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • The function automatically records the buffer pooling state in wrapper debugging information under the key "buffer_pooling_enabled" for audit, performance profiling, and configuration tracking.

Performance Impact Analysis: 

Operation             Pooling Enabled    Pooling Disabled    Improvement
─────────────────────────────────────────────────────────────────────────
100MB transfer        1200ms             1400ms              14.3% faster
1GB transfer          12000ms            14000ms             14.3% faster
10GB transfer         120000ms           140000ms            14.3% faster
GC Pause Time (avg)   2ms                15ms                87.5% reduction
Memory Allocs/ops     1000               10000               90% fewer allocs
Heap Fragmentation    Low                High                Significant

Memory Usage Comparison: 

Scenario                  Pooling Enabled      Pooling Disabled
─────────────────────────────────────────────────────────────────
Single 10MB file          +2MB pool overhead   Minimal overhead
Multiple 10MB files       +2MB pool (reused)   10MB × files in RAM
1GB sustained transfer    Steady 2MB pool      Spikes to 50-100MB
Long-running server       Stable 2-5MB pool    Growing heap (GC lag)
Mobile app               +2MB pool            Better for short ops

Example: 

// Example 1: Production server with sustained transfers (pooling enabled - recommended)
file, _ := os.Open("large_file.bin")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithCustomFieldKV("environment", "production").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024). // 1MB chunks
    WithMaxConcurrentChunks(4).
    WithBufferPooling(true). // Enable for production
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 100 == 0 {
            fmt.Printf("Transferred: %.2f MB | Memory stable: %.2f MB\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 2: CLI tool with one-time large file (pooling enabled still better)
file, _ := os.Open("backup.tar.gz")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/backup").
    WithStreaming(file, nil).
    WithChunkSize(512 * 1024). // 512KB chunks
    WithBufferPooling(true). // Still recommended
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("\rProgress: %.1f%% | Speed: %.2f MB/s",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 3: Mobile app with limited resources (pooling enabled for better efficiency)
appData := bytes.NewReader(updatePackage)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/app-update").
    WithCustomFieldKV("platform", "ios").
    WithCustomFieldKV("device_memory", "2GB").
    WithStreaming(appData, nil).
    WithChunkSize(32 * 1024). // 32KB for mobile
    WithBufferPooling(true). // Enable for efficiency on mobile
    WithThrottleRate(512 * 1024). // 512KB/s throttling
    WithTotalBytes(int64(len(updatePackage))).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Memory efficient: %.1f%% | Speed: %.2f KB/s\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024)
        }
    }).
    Start(context.Background())

// Example 4: Minimal/embedded system (pooling disabled to save memory)
embeddedData := bytes.NewReader(firmwareUpdate)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/upload/firmware").
    WithCustomFieldKV("device_type", "iot-sensor").
    WithCustomFieldKV("available_memory", "512MB").
    WithStreaming(embeddedData, nil).
    WithChunkSize(16 * 1024). // 16KB for embedded
    WithBufferPooling(false). // Disable to minimize memory
    WithStreamingStrategy(STRATEGY_DIRECT).
    WithMaxConcurrentChunks(1). // Single-threaded
    WithCompressionType(COMP_DEFLATE). // More compression
    WithTotalBytes(int64(len(firmwareUpdate))).
    Start(context.Background())

// Example 5: Conditional pooling based on system resources
availableMemory := getSystemMemory() // Custom function
var enablePooling bool

if availableMemory > 1024 * 1024 * 1024 { // > 1GB
    enablePooling = true // Enable pooling for better performance
} else {
    enablePooling = false // Disable to save memory on constrained systems
}

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/adaptive").
    WithCustomFieldKV("available_memory_mb", availableMemory / 1024 / 1024).
    WithStreaming(fileReader, nil).
    WithChunkSize(256 * 1024).
    WithBufferPooling(enablePooling). // Conditional based on resources
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Pooling: %v | Progress: %.1f%% | Rate: %.2f MB/s\n",
                enablePooling,
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

System Behavior Recommendations: 

System Type              File Size       Recommendation    Reasoning
────────────────────────────────────────────────────────────────────────
Production Server        Any             true (enable)     Sustained performance
Development/Testing      < 100MB         false (disable)   Lower overhead
Development/Testing      > 100MB         true (enable)     Test real behavior
Mobile App               Any             true (enable)     Efficiency critical
Embedded/IoT             Any             false (disable)    Memory limited
High-Concurrency API     Any             true (enable)      GC impact significant
One-time CLI             < 10MB          false (disable)    No sustained benefit
One-time CLI             > 10MB          true (enable)      GC overhead matters
Microservice             Any             true (enable)      Container overhead
Batch Processing         Any             true (enable)      Server efficiency

GC Tuning Notes: 

When buffer pooling is ENABLED:
  - Reduces allocation pressure on Go's allocator
  - Decreases GC frequency (fewer objects to scan)
  - Lower GC pause times (critical for latency-sensitive APIs)
  - Recommended: Default GOGC=100 works well

When buffer pooling is DISABLED:
  - Higher allocation pressure
  - More frequent GC cycles
  - Longer GC pause times (can be 10-100ms on large transfers)
  - Consider: GOGC=200 to reduce GC frequency (trade CPU for latency)

See Also:

  • WithChunkSize: Larger chunks reduce pool efficiency
  • WithMaxConcurrentChunks: More concurrency benefits more from pooling
  • WithStreamingStrategy: STRATEGY_BUFFERED benefits most from pooling
  • GetStats: Retrieve memory and performance statistics
  • Start: Initiates streaming with configured buffer pooling

func (*StreamingWrapper) WithCallback 

func (sw *StreamingWrapper) WithCallback(callback StreamingCallback) *wrapper

WithCallback sets the callback function for streaming progress updates.

This function registers a callback that will be invoked during the streaming operation to provide real-time progress information and error notifications. The callback is called for each chunk processed, allowing consumers to track transfer progress, bandwidth usage, and estimated time remaining.

Parameters:

  • callback: A StreamingCallback function that receives progress updates and potential errors. The callback signature is: func(progress *StreamProgress, err error)
  • progress: Contains current progress metrics (bytes transferred, percentage, ETA, etc.)
  • err: Non-nil if an error occurred during chunk processing; otherwise nil.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.

Example: 

streaming := response.AsStreaming(reader).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Printf("Streaming error at chunk %d: %v", p.CurrentChunk, err)
            return
        }
        fmt.Printf("Progress: %.1f%% | Rate: %.2f MB/s | ETA: %s\n",
            float64(p.Percentage),
            float64(p.TransferRate) / 1024 / 1024,
            p.EstimatedTimeRemaining.String())
    }).
    Start(ctx)

func (*StreamingWrapper) WithChunkSize 

func (sw *StreamingWrapper) WithChunkSize(size int64) *wrapper

WithChunkSize sets the size of individual data chunks processed during streaming.

This function configures the buffer size for each streaming iteration, directly impacting memory usage, latency, and throughput characteristics. Smaller chunks reduce memory footprint and improve responsiveness but increase processing overhead; larger chunks maximize throughput but consume more memory and delay initial response. The optimal chunk size depends on file size, available memory, network bandwidth, and streaming strategy. Chunk size is recorded in wrapper debugging information for tracking and diagnostics.

Parameters:

  • size: The size of each chunk in bytes. Must be greater than 0.

Recommended sizes based on scenario:

- 32KB (32768 bytes): Mobile networks, IoT devices, low-memory environments.

  • Latency: ~5ms per chunk
  • Memory: Minimal
  • Overhead: High (frequent operations)
  • Use case: Mobile streaming, embedded systems

- 64KB (65536 bytes): Default, balanced for most scenarios.

  • Latency: ~10ms per chunk
  • Memory: Low
  • Overhead: Low-Medium
  • Use case: General-purpose file downloads, APIs

- 256KB (262144 bytes): High-bandwidth networks, video streaming.

  • Latency: ~50ms per chunk
  • Memory: Medium
  • Overhead: Very low
  • Use case: Video/audio streaming, LAN transfers

- 1MB (1048576 bytes): Database exports, large data transfer.

  • Latency: ~100ms per chunk
  • Memory: Medium-High
  • Overhead: Very low
  • Use case: Database exports, backups, bulk operations

- 10MB (10485760 bytes): High-performance servers, LAN-only scenarios.

  • Latency: ~500ms per chunk
  • Memory: High
  • Overhead: Minimal
  • Use case: Server-to-server transfer, data center operations Invalid values: Must be > 0; zero or negative values will return an error.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the chunk size is ≤ 0, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the chunk size in wrapper debugging information under the key "chunk_size" for audit, performance analysis, and diagnostics.

Example: 

// Example 1: Mobile client download with small chunks (responsive UI)
file, _ := os.Open("app-update.apk")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/app-update").
    WithCustomFieldKV("platform", "mobile").
    WithStreaming(file, nil).
    WithChunkSize(32 * 1024). // 32KB for responsive updates
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("\rDownloading: %.1f%% | Speed: %.2f MB/s",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 2: Standard file download with balanced chunk size (default)
file, _ := os.Open("document.pdf")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/document").
    WithStreaming(file, nil).
    WithChunkSize(64 * 1024). // 64KB balanced default
    WithTotalBytes(fileSize).
    Start(context.Background())

// Example 3: Video streaming with large chunks (high throughput)
videoFile, _ := os.Open("movie.mp4")
defer videoFile.Close()

result := replify.New().
    WithStatusCode(206).
    WithPath("/api/stream/video").
    WithCustomFieldKV("quality", "1080p").
    WithStreaming(videoFile, nil).
    WithChunkSize(256 * 1024). // 256KB for smooth video playback
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(4).
    WithTotalBytes(videoFileSize).
    Start(context.Background())

// Example 4: Database export with large chunks (bulk operation)
dbReader := createDatabaseReader("SELECT * FROM users")

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/users").
    WithCustomFieldKV("format", "csv").
    WithStreaming(dbReader, nil).
    WithChunkSize(1024 * 1024). // 1MB for bulk export
    WithCompressionType(COMP_GZIP).
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(8).
    WithTotalBytes(totalRecords * avgRecordSize).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 100 == 0 {
            fmt.Printf("Exported: %d records | Rate: %.2f MB/s\n",
                p.CurrentChunk * (1024 * 1024 / avgRecordSize),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 5: Server-to-server transfer with maximum throughput
sourceReader := getNetworkReader("http://source-server/data")

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/sync/data").
    WithStreaming(sourceReader, nil).
    WithChunkSize(10 * 1024 * 1024). // 10MB for maximum throughput
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(16).
    WithCompressionType(COMP_NONE). // Already optimized
    WithTotalBytes(totalDataSize).
    Start(context.Background())

Chunk Size Selection Guide: 

File Size        Recommended Chunk    Rationale
─────────────────────────────────────────────────────────────────
< 1MB            32KB - 64KB           Minimal overhead, single chunk
1MB - 100MB      64KB - 256KB          Balanced, few chunks, responsive
100MB - 1GB      256KB - 1MB           Good throughput, moderate chunks
1GB - 10GB       1MB - 5MB             Optimized throughput, manageable chunks
> 10GB           5MB - 10MB            Maximum throughput, many chunks

Memory Impact Calculation: 

Total Memory Used = ChunkSize × MaxConcurrentChunks × 2 (read/write buffers)

Examples:
  64KB × 4 × 2 = 512KB (minimal)
  256KB × 4 × 2 = 2MB (standard)
  1MB × 8 × 2 = 16MB (large transfer)
  10MB × 16 × 2 = 320MB (high-performance)

See Also:

  • WithStreamingStrategy: Selects transfer algorithm affecting chunk efficiency
  • WithMaxConcurrentChunks: Controls parallel chunk processing
  • WithCompressionType: Compression per chunk
  • WithThrottleRate: Bandwidth limiting independent of chunk size
  • GetProgress: Monitor chunk processing in real-time
  • GetStats: Retrieve chunk statistics after streaming
  • Start: Initiates streaming with configured chunk size

func (*StreamingWrapper) WithCompressionType 

func (sw *StreamingWrapper) WithCompressionType(comp CompressionType) *wrapper

WithCompressionType sets the compression algorithm applied to streamed data chunks.

This function enables data compression during streaming to reduce bandwidth consumption and transfer time. Compression algorithms trade CPU usage for reduced data size, with different algorithms optimized for different data types. Compression is applied per-chunk during streaming, allowing for progressive compression and decompression without loading entire dataset into memory. The selected compression type is recorded in wrapper debugging information for tracking and validation purposes.

Parameters:

  • comp: A CompressionType constant specifying the compression algorithm to apply.

Available Compression Types:

- COMP_NONE: No compression applied (passthrough mode).

  • Compression Ratio: 100% (no reduction)
  • CPU Overhead: None
  • Use case: Already-compressed data (video, images, archives)
  • Best for: Binary formats, encrypted data

- COMP_GZIP: GZIP compression algorithm (RFC 1952).

  • Compression Ratio: 20-30% (70-80% size reduction)
  • CPU Overhead: Medium (~500ms per 100MB)
  • Speed: Medium (balanced)
  • Use case: Text, JSON, logs, CSV exports
  • Best for: RESTful APIs, data exports, text-based protocols

- COMP_DEFLATE: DEFLATE compression algorithm (RFC 1951).

  • Compression Ratio: 25-35% (65-75% size reduction)
  • CPU Overhead: Low (~300ms per 100MB)
  • Speed: Fast (optimized)
  • Use case: Smaller files, time-sensitive operations
  • Best for: Quick transfers, embedded systems, IoT Cannot be empty; empty string will return an error.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the compression type is empty, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the selected compression type in wrapper debugging information under the key "compression_type" for audit, diagnostics, and response transparency.

Example: 

// Example 1: Export CSV data with GZIP compression (recommended for text)
csvFile, _ := os.Open("users.csv")
defer csvFile.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/users").
    WithCustomFieldKV("format", "csv").
    WithStreaming(csvFile, nil).
    WithCompressionType(COMP_GZIP).
    WithChunkSize(512 * 1024).
    WithTotalBytes(csvFileSize).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.Percentage % 10 == 0 {
            fmt.Printf("Exported: %.2f MB (compressed) | Original: %.2f MB\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TotalBytes) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 2: Stream video without compression (already compressed)
videoFile, _ := os.Open("movie.mp4")
defer videoFile.Close()

result := replify.New().
    WithStatusCode(206).
    WithPath("/api/stream/video").
    WithCustomFieldKV("codec", "h264").
    WithStreaming(videoFile, nil).
    WithCompressionType(COMP_NONE).
    WithChunkSize(256 * 1024).
    WithTotalBytes(videoFileSize).
    Start(context.Background())

// Example 3: Fast log transfer with DEFLATE (IoT device)
logData := bytes.NewReader(logBuffer)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/logs/upload").
    WithCustomFieldKV("device_id", "iot-sensor-001").
    WithStreaming(logData, nil).
    WithCompressionType(COMP_DEFLATE).
    WithChunkSize(64 * 1024).
    WithThrottleRate(256 * 1024). // 256KB/s for IoT
    WithTotalBytes(int64(len(logBuffer))).
    Start(context.Background())

// Example 4: Conditional compression based on content type
contentType := "application/json"
var compressionType CompressionType

switch contentType {
case "application/json", "text/csv", "text/plain":
    compressionType = COMP_GZIP // Text formats benefit from GZIP
case "video/mp4", "image/jpeg", "application/zip":
    compressionType = COMP_NONE // Already compressed formats
default:
    compressionType = COMP_DEFLATE // Default to fast DEFLATE
}

result := replify.New().
    WithStreaming(dataReader, nil).
    WithCompressionType(compressionType).
    Start(context.Background())

Performance Impact Summary: 

Data Type       GZIP Ratio    Time/100MB    Best Algorithm
─────────────────────────────────────────────────────────
JSON            15-20%        ~500ms        GZIP ✓
CSV             18-25%        ~500ms        GZIP ✓
Logs            20-30%        ~450ms        GZIP ✓
XML             10-15%        ~500ms        GZIP ✓
Binary          40-60%        ~600ms        DEFLATE
Video (MP4)     98-99%        ~2000ms       NONE ✓
Images (JPEG)   98-99%        ~2000ms       NONE ✓
Archives (ZIP)  100%          ~0ms          NONE ✓
Encrypted       100%          ~0ms          NONE ✓

See Also:

  • WithChunkSize: Configures chunk size for optimal compression
  • WithStreamingStrategy: Selects transfer algorithm
  • WithThrottleRate: Limits bandwidth usage
  • GetStats: Retrieve compression statistics after streaming
  • Start: Initiates streaming with compression enabled

func (StreamingWrapper) WithCustomFieldKV 

func (w StreamingWrapper) WithCustomFieldKV(key string, value any) *wrapper

WithCustomFieldKV sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance.

This function ensures that if the `meta` field is not already set, a new `meta` instance is created. It then adds the provided key-value pair to the custom fields of `meta` using the `WithCustomFieldKV` method.

Parameters:

  • `key`: A string representing the custom field key to set.
  • `value`: The value associated with the custom field key.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithCustomFieldKVf 

func (w StreamingWrapper) WithCustomFieldKVf(key string, format string, args ...any) *wrapper

WithCustomFieldKVf sets a specific custom field key-value pair in the `meta` field of the `wrapper` instance using a formatted value.

This function constructs a formatted string value using the provided `format` string and arguments (`args`). It then calls the `WithCustomFieldKV` method to add or update the custom field with the specified key and the formatted value. If the `meta` field of the `wrapper` instance is not initialized, it is created before setting the custom field.

Parameters:

  • key: A string representing the key for the custom field.
  • format: A format string to construct the value.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (StreamingWrapper) WithCustomFields 

func (w StreamingWrapper) WithCustomFields(values map[string]any) *wrapper

WithCustomFields sets the custom fields in the `meta` field of the `wrapper` instance.

This function checks if the `meta` field is present. If not, it creates a new `meta` instance and sets the provided custom fields using the `WithCustomFields` method.

Parameters:

  • `values`: A map representing the custom fields to set in the `meta`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithDebugging 

func (w StreamingWrapper) WithDebugging(v map[string]any) *wrapper

WithDebugging sets the debugging information for the `wrapper` instance.

This function updates the `debug` field of the `wrapper` with the provided map of debugging data and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A map containing debugging information to be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithDebuggingKV 

func (w StreamingWrapper) WithDebuggingKV(key string, value any) *wrapper

WithDebuggingKV adds a key-value pair to the debugging information in the `wrapper` instance.

This function checks if debugging information is already present. If it is not, it initializes an empty map. Then it adds the given key-value pair to the `debug` map and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `key`: The key for the debugging information to be added.
  • `value`: The value associated with the key to be added to the `debug` map.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithDebuggingKVf 

func (w StreamingWrapper) WithDebuggingKVf(key string, format string, args ...any) *wrapper

WithDebuggingKVf adds a formatted key-value pair to the debugging information in the `wrapper` instance.

This function creates a formatted string value using the provided `format` string and `args`, then delegates to `WithDebuggingKV` to add the resulting key-value pair to the `debug` map. It returns the modified `wrapper` instance for method chaining.

Parameters:

  • key: A string representing the key for the debugging information.
  • format: A format string for constructing the value.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (StreamingWrapper) WithError 

func (w StreamingWrapper) WithError(message string) *wrapper

WithError sets an error for the `wrapper` instance using a plain error message.

This function creates an error object from the provided message, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • message: A string containing the error message to be wrapped as an error object.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) WithErrorAck 

func (w StreamingWrapper) WithErrorAck(err error) *wrapper

WithErrorAck sets an error with a stack trace for the `wrapper` instance.

This function wraps the provided error with stack trace information, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • err: The error object to be wrapped with stack trace information.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) WithErrorAckf 

func (w StreamingWrapper) WithErrorAckf(err error, format string, args ...any) *wrapper

WithErrorAckf wraps an existing error with a formatted message and sets it for the `wrapper` instance.

This function adds context to the provided error by wrapping it with a formatted message. The resulting error is assigned to the `errors` field of the `wrapper`.

Parameters:

  • err: The original error to be wrapped.
  • format: A format string for constructing the contextual error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) WithErrorf 

func (w StreamingWrapper) WithErrorf(format string, args ...any) *wrapper

WithErrorf sets a formatted error for the `wrapper` instance.

This function uses a formatted string and arguments to construct an error object, assigns it to the `errors` field of the `wrapper`, and returns the modified instance.

Parameters:

  • format: A format string for constructing the error message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance to support method chaining.

func (StreamingWrapper) WithHeader 

func (w StreamingWrapper) WithHeader(v *header) *wrapper

WithHeader sets the header for the `wrapper` instance.

This function updates the `header` field of the `wrapper` with the provided `header` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `header` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (*StreamingWrapper) WithHook 

func (sw *StreamingWrapper) WithHook(callback StreamingHook) *wrapper

WithHook sets the callback function for streaming progress updates with read context.

This function registers a callback that will be invoked during the streaming operation to provide real-time progress information and error notifications. The callback is called for each chunk processed, allowing consumers to track transfer progress, bandwidth usage, and estimated time remaining. The callback also receives the read context for advanced scenarios where access to the read buffer is needed.

Parameters:

  • callback: A StreamingCallbackR function that receives progress updates, read context, and potential errors. The callback signature is: func(progress *StreamProgress, w *R)
  • progress: Contains current progress metrics (bytes transferred, percentage, ETA, etc.)
  • w: A pointer to the R struct containing read context for the current chunk.

func (StreamingWrapper) WithIsLast 

func (w StreamingWrapper) WithIsLast(v bool) *wrapper

WithIsLast sets whether the current page is the last one in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified boolean value is then applied to indicate whether the current page is the last.

Parameters:

  • v: A boolean indicating whether the current page is the last.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) WithJSONBody 

func (w StreamingWrapper) WithJSONBody(v any) (*wrapper, error)

WithJSONBody normalizes the input value and sets it as the body data for the `wrapper` instance.

The method accepts any Go value and handles it according to its dynamic type:

  • string – the string is passed through encoding.NormalizeJSON, which strips common JSON corruption artifacts (BOM, null bytes, escaped structural quotes, trailing commas) before setting the result as the body.
  • []byte – treated as a raw string; the same NormalizeJSON pipeline is applied after converting to string.
  • json.RawMessage – validated directly; if invalid, an error is returned.
  • any other type – marshaled to JSON via encoding.JSONToken and set as the body, which is by definition already valid JSON.
  • nil – returns an error; nil cannot be normalized.

If normalization succeeds, the cleaned value is stored as the body and the method returns the updated wrapper and nil. If it fails, the body is left unchanged and a descriptive error is returned.

Parameters:

  • v: The value to normalize and set as the body.

Returns:

  • A pointer to the modified `wrapper` instance and nil on success.
  • The unchanged `wrapper` instance and an error if normalization fails.

Example: 

// From a raw-string with escaped structural quotes:
w, err := replify.New().WithJSONBody(`{\"key\": "value"}`)

// From a struct:
w, err := replify.New().WithJSONBody(myStruct)

func (StreamingWrapper) WithLocale 

func (w StreamingWrapper) WithLocale(v string) *wrapper

WithLocale sets the locale in the `meta` field of the `wrapper` instance.

This function ensures the `meta` field is present, creating a new instance if needed, and sets the locale in the `meta` using the `WithLocale` method.

Parameters:

  • `v`: A string representing the locale to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (*StreamingWrapper) WithMaxConcurrentChunks 

func (sw *StreamingWrapper) WithMaxConcurrentChunks(count int) *wrapper

WithMaxConcurrentChunks sets the maximum number of data chunks processed concurrently during streaming.

This function configures the level of parallelism for chunk processing, directly impacting throughput, CPU utilization, and memory consumption. Higher concurrency enables better bandwidth utilization and faster overall transfer by processing multiple chunks simultaneously; however, it increases CPU load and memory overhead. The optimal concurrency level depends on available CPU cores, memory constraints, network capacity, and the streaming strategy employed. This is particularly effective with STRATEGY_BUFFERED where read and write operations can overlap. The concurrency level is recorded in wrapper debugging information for performance analysis and resource monitoring.

Parameters:

  • count: The maximum number of chunks to process in parallel. Must be greater than 0.

Recommended values based on scenario:

- 1: Single-threaded sequential processing (no parallelism).

  • Throughput: Low (50-100 MB/s)
  • CPU Usage: Minimal (~25% single core)
  • Memory: Minimal (1 chunk buffer)
  • Latency: Highest (~100ms between chunks)
  • Use case: Single-core systems, extremely limited resources, ordered processing
  • Best with: STRATEGY_DIRECT (matches sequential nature)

- 2: Minimal parallelism (read ahead 1 chunk).

  • Throughput: Medium (100-200 MB/s)
  • CPU Usage: Low-Medium (~50% two cores)
  • Memory: Low (2 chunk buffers)
  • Latency: Medium (~50ms between chunks)
  • Use case: Mobile devices, low-resource environments
  • Best with: STRATEGY_BUFFERED

- 4: Standard parallelism (balanced default).

  • Throughput: High (200-500 MB/s)
  • CPU Usage: Medium (~100% four cores)
  • Memory: Medium (4 chunk buffers)
  • Latency: Low (~25ms between chunks)
  • Use case: Most general-purpose scenarios, typical servers
  • Best with: STRATEGY_BUFFERED (recommended)

- 8: High parallelism (aggressive read-ahead).

  • Throughput: Very High (500-1000 MB/s)
  • CPU Usage: High (~100% eight cores)
  • Memory: High (8 chunk buffers)
  • Latency: Very Low (~10ms between chunks)
  • Use case: Multi-core servers, high-bandwidth networks, database exports
  • Best with: STRATEGY_BUFFERED or STRATEGY_CHUNKED

- 16+: Extreme parallelism (maximum throughput).

  • Throughput: Maximum (1000+ MB/s potential)
  • CPU Usage: Very High (all cores maxed)
  • Memory: Very High (16+ chunk buffers in flight)
  • Latency: Minimal (~1ms between chunks)
  • Use case: Data center operations, 10 Gigabit networks, bulk transfer servers
  • Best with: STRATEGY_BUFFERED with large chunk sizes (1MB+)

Invalid values: Must be > 0; zero or negative values will return an error.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the concurrent chunk count is ≤ 0, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the max concurrent chunks in wrapper debugging information under the key "max_concurrent_chunks" for audit, performance profiling, and resource tracking.

Memory Impact Calculation: 

Total Streaming Memory = ChunkSize × MaxConcurrentChunks × 2 + Overhead

Formula Explanation:
  - ChunkSize: Size of individual chunk in bytes
  - MaxConcurrentChunks: Number of concurrent chunks in flight
  - 2: Read buffer + Write buffer (input and output streams)
  - Overhead: ~1-5MB for data structures, compression buffers, etc.

Memory Examples (with 64KB chunks):
  1 concurrent:  64KB × 1 × 2 = 128KB + 2MB overhead = ~2.1MB total
  2 concurrent:  64KB × 2 × 2 = 256KB + 2MB overhead = ~2.3MB total
  4 concurrent:  64KB × 4 × 2 = 512KB + 2MB overhead = ~2.5MB total
  8 concurrent:  64KB × 8 × 2 = 1MB + 2MB overhead = ~3.0MB total
  16 concurrent: 64KB × 16 × 2 = 2MB + 2MB overhead = ~4.0MB total

Memory Examples (with 1MB chunks):
  1 concurrent:  1MB × 1 × 2 = 2MB + 2MB overhead = ~4MB total
  2 concurrent:  1MB × 2 × 2 = 4MB + 2MB overhead = ~6MB total
  4 concurrent:  1MB × 4 × 2 = 8MB + 2MB overhead = ~10MB total
  8 concurrent:  1MB × 8 × 2 = 16MB + 2MB overhead = ~18MB total
  16 concurrent: 1MB × 16 × 2 = 32MB + 2MB overhead = ~34MB total

Example: 

// Example 1: Single-threaded processing for ordered/sequential requirement
csvFile, _ := os.Open("ordered-data.csv")
defer csvFile.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/process/ordered-csv").
    WithStreaming(csvFile, nil).
    WithChunkSize(64 * 1024).
    WithStreamingStrategy(STRATEGY_DIRECT).
    WithMaxConcurrentChunks(1). // Sequential processing
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 100 == 0 {
            fmt.Printf("Chunk %d: Processed in order\n", p.CurrentChunk)
        }
    }).
    Start(context.Background())

// Example 2: Mobile client with minimal concurrency (low memory)
appData := bytes.NewReader(mobileUpdate)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/mobile-app").
    WithCustomFieldKV("platform", "ios").
    WithStreaming(appData, nil).
    WithChunkSize(32 * 1024). // 32KB chunks
    WithMaxConcurrentChunks(2). // Low memory footprint
    WithCompressionType(COMP_GZIP).
    WithThrottleRate(512 * 1024). // 512KB/s
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithTotalBytes(int64(len(mobileUpdate))).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Memory efficient: %.1f%% | Speed: %.2f KB/s\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024)
        }
    }).
    Start(context.Background())

// Example 3: Standard server download with balanced concurrency (recommended)
file, _ := os.Open("document.iso")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/document").
    WithStreaming(file, nil).
    WithChunkSize(256 * 1024). // 256KB chunks
    WithMaxConcurrentChunks(4). // Balanced (most scenarios)
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithCompressionType(COMP_GZIP).
    WithTotalBytes(fileSize).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.ElapsedTime.Seconds() > 0 {
            fmt.Printf("Progress: %.1f%% | Bandwidth: %.2f MB/s | ETA: %s\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

// Example 4: High-performance server with aggressive parallelism
dbExport := createDatabaseStreamReader("SELECT * FROM transactions", 10000)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/transactions").
    WithCustomFieldKV("format", "parquet").
    WithStreaming(dbExport, nil).
    WithChunkSize(1024 * 1024). // 1MB chunks
    WithMaxConcurrentChunks(8). // High parallelism
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(8). // Process 8 chunks in parallel
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Error at chunk %d: %v\n", p.CurrentChunk, err)
            return
        }
        if p.CurrentChunk % 50 == 0 {
            stats := fmt.Sprintf(
                "Exported: %.2f MB | Rate: %.2f MB/s | ETA: %s",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TransferRate) / 1024 / 1024,
                p.EstimatedTimeRemaining.String(),
            )
            fmt.Println(stats)
        }
    }).
    Start(context.Background())

// Example 5: Data center bulk transfer with maximum parallelism
sourceServer := getNetworkStreamReader("http://backup-server/full-backup")

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/sync/full-backup").
    WithCustomFieldKV("source", "backup-server").
    WithStreaming(sourceServer, nil).
    WithChunkSize(10 * 1024 * 1024). // 10MB chunks for high throughput
    WithMaxConcurrentChunks(16). // Maximum parallelism for datacenter
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithCompressionType(COMP_NONE). // Already optimized
    WithMaxConcurrentChunks(16). // 16 chunks in parallel
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 100 == 0 {
            throughput := float64(p.TransferRate) / 1024 / 1024 / 1024
            fmt.Printf("Bulk transfer: %.2f GB/s | %.1f%% complete\n",
                throughput, float64(p.Percentage))
        }
    }).
    Start(context.Background())

Concurrency Selection Matrix: 

System Type          Available Cores    Recommended Count    Throughput
─────────────────────────────────────────────────────────────────────────
Single-core          1                  1                    50-100 MB/s
Mobile (2-4 cores)   2-4                2-4                  100-500 MB/s
Standard Server      8 cores            4-8                  200-1000 MB/s
High-end Server      16+ cores          8-16                 500-2000 MB/s
Data Center          32+ cores          16-32                1000+ MB/s

CPU & Memory Trade-off: 

Count    CPU Load    Memory (64KB)    Memory (1MB)    Throughput    Best For
─────────────────────────────────────────────────────────────────────────────────
1        25%         ~2MB            ~4MB            100 MB/s      Sequential
2        50%         ~2.3MB          ~6MB            200 MB/s      Mobile
4        100%        ~2.5MB          ~10MB           500 MB/s      Standard (✓)
8        100%        ~3MB            ~18MB           1000 MB/s     High-perf
16       100%        ~4MB            ~34MB           2000 MB/s     Datacenter

See Also:

  • WithChunkSize: Chunk size affects memory per concurrent chunk
  • WithStreamingStrategy: Strategy affects concurrency efficiency (BUFFERED best)
  • WithCompressionType: Compression affects CPU usage with high concurrency
  • WithThrottleRate: Throttling independent of concurrency level
  • GetProgress: Monitor actual concurrency effect in real-time
  • GetStats: Retrieve throughput metrics after streaming
  • Start: Initiates streaming with parallel chunk processing

func (StreamingWrapper) WithMessage 

func (w StreamingWrapper) WithMessage(message string) *wrapper

WithMessage sets a message for the `wrapper` instance.

This function updates the `message` field of the `wrapper` with the provided string and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `message`: A string message to be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithMessagef 

func (w StreamingWrapper) WithMessagef(message string, args ...any) *wrapper

WithMessagef sets a formatted message for the `wrapper` instance.

This function constructs a formatted string using the provided format string and arguments, assigns it to the `message` field of the `wrapper`, and returns the modified instance.

Parameters:

  • message: A format string for constructing the message.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (StreamingWrapper) WithMeta 

func (w StreamingWrapper) WithMeta(v *meta) *wrapper

WithMeta sets the metadata for the `wrapper` instance.

This function updates the `meta` field of the `wrapper` with the provided `meta` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `meta` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithPage 

func (w StreamingWrapper) WithPage(v int) *wrapper

WithPage sets the current page number in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified page number is then applied to the pagination instance.

Parameters:

  • v: The page number to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) WithPagination 

func (w StreamingWrapper) WithPagination(v *pagination) *wrapper

WithPagination sets the pagination information for the `wrapper` instance.

This function updates the `pagination` field of the `wrapper` with the provided `pagination` instance and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A pointer to a `pagination` struct that will be set in the `wrapper`.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithPath 

func (w StreamingWrapper) WithPath(v string) *wrapper

WithPath sets the request path for the `wrapper` instance.

This function updates the `path` field of the `wrapper` with the provided string and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `v`: A string representing the request path.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithPathf 

func (w StreamingWrapper) WithPathf(v string, args ...any) *wrapper

WithPathf sets a formatted request path for the `wrapper` instance.

This function constructs a formatted string using the provided format string `v` and arguments `args`, assigns the resulting string to the `path` field of the `wrapper`, and returns the modified instance.

Parameters:

  • v: A format string for constructing the request path.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, enabling method chaining.

func (StreamingWrapper) WithPerPage 

func (w StreamingWrapper) WithPerPage(v int) *wrapper

WithPerPage sets the number of items per page in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified items-per-page value is then applied to the pagination instance.

Parameters:

  • v: The number of items per page to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (*StreamingWrapper) WithReadTimeout 

func (sw *StreamingWrapper) WithReadTimeout(timeout int64) *wrapper

WithReadTimeout sets the read operation timeout for streaming data acquisition.

This function configures the maximum duration allowed for individual read operations on the input stream. The read timeout acts as a circuit breaker to prevent indefinite blocking when data sources become unresponsive, disconnected, or stalled. Each chunk read attempt must complete within the specified timeout; if exceeded, the read operation fails and streaming is interrupted. This is critical for production systems where network failures, slow clients, or hung connections could otherwise freeze the entire streaming operation indefinitely. Read timeout is independent of write timeout and total operation timeout. The timeout value is recorded in wrapper debugging information for audit, performance tracking, and troubleshooting.

Parameters:

  • timeout: The maximum duration for read operations in milliseconds. Must be greater than 0.

Recommended values based on scenario:

- 1000-5000ms (1-5 seconds): Very fast networks, local transfers, LAN.

  • Use case: File downloads on gigabit LAN, local API calls
  • Network: Sub-millisecond latency (<1ms typical round-trip)
  • Best for: High-speed, predictable connections
  • Example: 2000 (2 seconds)

- 5000-15000ms (5-15 seconds): Standard networks, normal internet.

  • Use case: Most REST API downloads, web servers, typical internet transfers
  • Network: 10-100ms latency (typical broadband)
  • Best for: General-purpose APIs and services
  • Example: 10000 (10 seconds) - RECOMMENDED DEFAULT

- 15000-30000ms (15-30 seconds): Slow/congested networks, mobile networks.

  • Use case: Mobile clients (3G/4G), congested WiFi, distant servers
  • Network: 100-500ms latency (cellular networks)
  • Best for: Mobile apps, unreliable connections
  • Example: 20000 (20 seconds)

- 30000-60000ms (30-60 seconds): Very slow networks, satellite, WAN.

  • Use case: Satellite connections, international transfers, dial-up
  • Network: 500ms-2s latency (very slow links)
  • Best for: Challenging network conditions
  • Example: 45000 (45 seconds)

- 60000+ms (60+ seconds): Extremely slow/unreliable connections only.

  • Use case: Satellite uplink, emergency networks, extreme edge cases
  • Network: 2s+ latency
  • Best for: Last-resort scenarios with critical data
  • Example: 120000 (120 seconds)

Invalid values: Must be > 0; zero or negative values will return an error. Note: Very large timeouts (>120s) can mask real connection problems; consider implementing application-level heartbeats instead for better reliability.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the read timeout is ≤ 0, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the read timeout in wrapper debugging information under the key "read_timeout_ms" for audit, performance analysis, and troubleshooting.

Timeout Behavior Semantics: 

Scenario                        Behavior with ReadTimeout
───────────────────────────────────────────────────────────────────────
Data arrives before timeout     Chunk processed immediately
Data arrives after timeout      Read fails, streaming terminates
Connection stalled              Read blocks until timeout, then fails
EOF reached                     Streaming completes normally
Network disconnect              Read fails immediately (OS-level)
Slow source (< timeout rate)    Streaming continues, each chunk waits
Source sends partial data       Waits for complete chunk or timeout

Read Timeout vs Write Timeout Comparison: 

Aspect                  ReadTimeout         WriteTimeout
─────────────────────────────────────────────────────────────
Controls                Data input delay    Data output delay
Fails when              Source is slow      Destination is slow
Typical cause           Slow upload         Slow client/network
Recovery                Retry from chunk    Chunk lost (retry)
Recommendation          10-30 seconds       10-30 seconds
Relationship            Independent         Independent
Combined max            Sum of both         Sequential impact

Example: 

// Example 1: LAN file transfer with fast timeout (2 seconds)
file, _ := os.Open("data.bin")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/lan-transfer").
    WithCustomFieldKV("network", "gigabit-lan").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024). // 1MB chunks
    WithReadTimeout(2000). // 2 seconds for fast LAN
    WithWriteTimeout(2000). // Match read timeout
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(8).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Transfer failed: %v\n", err)
            return
        }
        if p.CurrentChunk % 100 == 0 {
            fmt.Printf("Progress: %.1f%% | Speed: %.2f MB/s\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 2: Standard internet download with typical timeout (10 seconds)
httpResp, _ := http.Get("https://api.example.com/download/document")
defer httpResp.Body.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/from-internet").
    WithCustomFieldKV("source", "api.example.com").
    WithStreaming(httpResp.Body, nil).
    WithChunkSize(256 * 1024). // 256KB chunks
    WithReadTimeout(10000). // 10 seconds standard
    WithWriteTimeout(10000).
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(4).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Warnf("Download stalled: %v", err)
            return
        }
        if p.ElapsedTime.Seconds() > 0 {
            fmt.Printf("ETA: %s | Speed: %.2f MB/s\n",
                p.EstimatedTimeRemaining.String(),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 3: Mobile client with extended timeout (20 seconds)
mobileStream, _ := os.Open("app-update.apk")
defer mobileStream.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/mobile-app").
    WithCustomFieldKV("platform", "android").
    WithCustomFieldKV("network", "4g-lte").
    WithStreaming(mobileStream, nil).
    WithChunkSize(32 * 1024). // 32KB small chunks
    WithReadTimeout(20000). // 20 seconds for mobile
    WithWriteTimeout(20000). // Account for slow client
    WithThrottleRate(512 * 1024). // 512KB/s
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(2).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Errorf("Mobile download failed: %v", err)
            // Could implement retry logic here
            return
        }
        if p.CurrentChunk % 50 == 0 {
            fmt.Printf("Mobile: %.1f%% | Speed: %.2f KB/s | Signal: Good\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024)
        }
    }).
    Start(context.Background())

// Example 4: Slow/unreliable network with long timeout (45 seconds)
satelliteReader := createSatelliteStreamReader() // Custom reader

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/satellite").
    WithCustomFieldKV("source", "satellite-link").
    WithCustomFieldKV("network_quality", "poor").
    WithStreaming(satelliteReader, nil).
    WithChunkSize(64 * 1024). // 64KB for stability
    WithReadTimeout(45000). // 45 seconds for satellite
    WithWriteTimeout(45000).
    WithStreamingStrategy(STRATEGY_DIRECT). // Sequential for reliability
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Satellite link error: %v (chunk %d)\n",
                err, p.CurrentChunk)
            return
        }
        if p.CurrentChunk % 20 == 0 {
            fmt.Printf("Satellite: Chunk %d received | ETA: %s\n",
                p.CurrentChunk,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

// Example 5: Adaptive timeout based on network detection
networkType := detectNetworkType() // Custom function: "lan", "internet", "mobile", "satellite"
var readTimeoutMs int64

switch networkType {
case "lan":
    readTimeoutMs = 3000 // 3 seconds for LAN
case "internet":
    readTimeoutMs = 10000 // 10 seconds for internet
case "mobile":
    readTimeoutMs = 20000 // 20 seconds for mobile
case "satellite":
    readTimeoutMs = 60000 // 60 seconds for satellite
default:
    readTimeoutMs = 15000 // 15 seconds default
}

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/adaptive").
    WithCustomFieldKV("detected_network", networkType).
    WithStreaming(fileReader, nil).
    WithChunkSize(256 * 1024).
    WithReadTimeout(readTimeoutMs).
    WithWriteTimeout(readTimeoutMs).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Warnf("Network: %s | Error: %v | Chunk: %d",
                networkType, err, p.CurrentChunk)
            return
        }
        if p.CurrentChunk % 50 == 0 {
            fmt.Printf("[%s] %.1f%% | Speed: %.2f MB/s | ETA: %s\n",
                networkType,
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

Network-Based Timeout Selection Guide: 

Network Type           Latency      Timeout (ms)    Rationale
─────────────────────────────────────────────────────────────────────
Gigabit LAN            <1ms         2,000-5,000     Very fast, predictable
Fast Internet (>50Mbps) 10-50ms     5,000-10,000    Good connectivity
Standard Internet      50-100ms     10,000-15,000   Typical broadband
Mobile (4G/LTE)        100-500ms    15,000-20,000   Variable but acceptable
Mobile (3G)            500-2000ms   20,000-30,000   Slower, less reliable
Satellite              1000-2000ms  45,000-60,000   Very slow, high latency
Dial-up/Extreme        2000+ms      60,000+         Only last resort

Error Handling Strategy: 

When ReadTimeout is triggered:
  1. Current chunk read fails
  2. Streaming operation is terminated
  3. Error is passed to callback (if set)
  4. Wrapper records error in debugging information
  5. Application should implement retry logic at higher level

Best Practice:
  - Set ReadTimeout and WriteTimeout to same value
  - Choose timeout 2-3× longer than worst-case expected latency
  - Implement application-level retry/resume for critical transfers
  - Log timeout events for monitoring and debugging
  - Consider circuit breaker pattern for repeated failures

See Also:

  • WithWriteTimeout: Sets timeout for write operations
  • WithChunkSize: Smaller chunks may need shorter timeouts
  • WithStreamingStrategy: Strategy affects timeout sensitivity
  • WithCallback: Receives timeout errors for handling
  • GetProgress: Monitor actual transfer rate vs timeout
  • Start: Initiates streaming with configured read timeout

func (*StreamingWrapper) WithReceiveMode 

func (sw *StreamingWrapper) WithReceiveMode(isReceiving bool) *wrapper

WithReceiveMode sets the streaming mode to receiving or sending.

This function configures the streaming wrapper to operate in either receiving mode (reading data from the reader) or sending mode (writing data to the writer).

Parameters:

  • isReceiving: A boolean flag indicating the mode.

  • true: Set to receiving mode (reading from reader).

  • false: Set to sending mode (writing to writer).

Returns:

  • A pointer to the `wrapper` instance, allowing for method chaining.

func (StreamingWrapper) WithRequestID 

func (w StreamingWrapper) WithRequestID(v string) *wrapper

WithRequestID sets the request ID in the `meta` field of the `wrapper` instance.

This function ensures that if `meta` information is not already set in the `wrapper`, a new `meta` instance is created. Then, it calls the `WithRequestID` method on the `meta` instance to set the request ID.

Parameters:

  • `v`: A string representing the request ID to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithRequestIDf 

func (w StreamingWrapper) WithRequestIDf(format string, args ...any) *wrapper

WithRequestIDf sets the request ID in the `meta` field of the `wrapper` instance using a formatted string.

This function ensures that the `meta` field in the `wrapper` is initialized. If the `meta` field is not already present, a new `meta` instance is created using the `NewMeta` function. Once the `meta` instance is ready, it updates the request ID by calling the `WithRequestIDf` method on the `meta` instance. The request ID is constructed using the provided `format` string and the variadic `args`.

Parameters:

  • format: A format string used to construct the request ID.
  • args: A variadic list of arguments to be interpolated into the format string.

Returns:

  • A pointer to the modified `wrapper` instance, allowing for method chaining.

func (StreamingWrapper) WithRequestedTime 

func (w StreamingWrapper) WithRequestedTime(v time.Time) *wrapper

WithRequestedTime sets the requested time in the `meta` field of the `wrapper` instance.

This function ensures that the `meta` field exists, and if not, creates a new one. It then sets the requested time in the `meta` using the `WithRequestedTime` method.

Parameters:

  • `v`: A `time.Time` value representing the requested time.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithStatusCode 

func (w StreamingWrapper) WithStatusCode(code int) *wrapper

WithStatusCode sets the HTTP status code for the `wrapper` instance. Ensure that code is between 100 and 599, defaults to 500 if invalid value.

This function updates the `statusCode` field of the `wrapper` and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `code`: An integer representing the HTTP status code to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (StreamingWrapper) WithStreaming 

func (w StreamingWrapper) WithStreaming(reader io.Reader, config *StreamConfig) *StreamingWrapper

WithStreaming enables streaming mode for the wrapper and returns a streaming wrapper for enhanced data transfer capabilities.

This function is the primary entry point for activating streaming functionality on an existing wrapper instance. It creates a new StreamingWrapper that preserves the metadata and context of the original wrapper while adding streaming-specific features such as chunk-based transfer, compression, progress tracking, and bandwidth throttling. The returned StreamingWrapper allows for method chaining to configure streaming parameters before initiating transfer.

Parameters:

  • reader: An io.Reader implementation providing the source data stream (e.g., *os.File, *http.Response.Body, *bytes.Buffer). Cannot be nil; streaming will fail if no valid reader is provided.
  • config: A *StreamConfig containing streaming configuration options (chunk size, compression, strategy, concurrency). If nil, a default configuration is automatically created with sensible defaults:
  • ChunkSize: 65536 bytes (64KB)
  • Strategy: STRATEGY_BUFFERED (balanced throughput and memory)
  • Compression: COMP_NONE
  • MaxConcurrentChunks: 4

Returns:

  • A pointer to a new StreamingWrapper instance that wraps the original wrapper.
  • The StreamingWrapper preserves all metadata from the original wrapper.
  • If the receiver wrapper is nil, creates a new default wrapper before enabling streaming.
  • The returned StreamingWrapper can be chained with configuration methods before calling Start().

Example: 

file, _ := os.Open("large_file.bin")
defer file.Close()

// Simple streaming with defaults
result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithChunkSize(1024 * 1024).
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Transferred: %.2f MB / %.2f MB\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TotalBytes) / 1024 / 1024)
        }
    }).
    Start(context.Background()).
    WithMessage("File transfer completed")

See Also:

  • AsStreaming: Simplified version with default configuration
  • Start: Initiates the streaming operation
  • WithChunkSize: Configures chunk size
  • WithCompressionType: Enables data compression

func (*StreamingWrapper) WithStreamingStrategy 

func (sw *StreamingWrapper) WithStreamingStrategy(strategy StreamingStrategy) *wrapper

WithStreamingStrategy sets the streaming algorithm strategy for data transfer.

This function configures how the streaming operation processes and transfers data chunks. Different strategies optimize for different scenarios: STRATEGY_DIRECT for simplicity and low memory, STRATEGY_BUFFERED for balanced throughput and responsiveness, and STRATEGY_CHUNKED for explicit control in advanced scenarios. The chosen strategy affects latency, memory usage, and overall throughput characteristics. The strategy is recorded in wrapper debugging information for tracking and diagnostics.

Parameters:

  • strategy: A StreamingStrategy constant specifying the transfer algorithm.

Available Strategies:

- STRATEGY_DIRECT: Sequential blocking read-write without buffering.

  • Throughput: 50-100 MB/s
  • Latency: ~10ms per chunk
  • Memory: Single chunk + overhead (minimal)
  • Use case: Small files (<100MB), simple scenarios

- STRATEGY_BUFFERED: Concurrent read and write with internal buffering.

  • Throughput: 100-500 MB/s
  • Latency: ~50ms per chunk
  • Memory: Multiple chunks in flight (medium)
  • Use case: Most scenarios (100MB-10GB)

- STRATEGY_CHUNKED: Explicit chunk-by-chunk processing with full control.

  • Throughput: 100-500 MB/s
  • Latency: ~100ms per chunk
  • Memory: Medium
  • Use case: Large files (>10GB), specialized processing

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the strategy is empty, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the selected strategy in wrapper debugging information under the key "streaming_strategy" for audit and diagnostic purposes.

Example: 

file, _ := os.Open("large_file.bin")
defer file.Close()

// Use buffered strategy for most scenarios (recommended)
result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/file").
    WithStreaming(file, nil).
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithChunkSize(1024 * 1024).
    WithMaxConcurrentChunks(4).
    WithTotalBytes(fileSize).
    Start(context.Background())

// Use direct strategy for small files with minimal overhead
result := replify.New().
    WithStreaming(smallFile, nil).
    WithStreamingStrategy(STRATEGY_DIRECT).
    WithChunkSize(65536).
    Start(context.Background())

// Use chunked strategy for very large files with explicit control
result := replify.New().
    WithStreaming(hugeFile, nil).
    WithStreamingStrategy(STRATEGY_CHUNKED).
    WithChunkSize(10 * 1024 * 1024).
    WithCallback(func(p *StreamProgress, err error) {
        fmt.Printf("Chunk %d: %.2f MB | Rate: %.2f MB/s\n",
            p.CurrentChunk,
            float64(p.Size) / 1024 / 1024,
            float64(p.TransferRate) / 1024 / 1024)
    }).
    Start(context.Background())

See Also:

  • WithChunkSize: Configures the size of data chunks
  • WithMaxConcurrentChunks: Sets parallel processing level
  • WithCompressionType: Enables data compression
  • Start: Initiates the streaming operation with chosen strategy

func (*StreamingWrapper) WithThrottleRate 

func (sw *StreamingWrapper) WithThrottleRate(bytesPerSecond int64) *wrapper

WithThrottleRate sets the bandwidth throttling rate to limit streaming speed in bytes per second.

This function constrains the data transfer rate during streaming to manage bandwidth consumption, prevent network congestion, and ensure fair resource allocation in multi-client environments. Throttling is applied by introducing controlled delays between chunk transfers, maintaining a consistent throughput rate. This is particularly useful for mobile networks, satellite connections, and shared infrastructure where preventing upstream saturation is critical. A rate of 0 means unlimited bandwidth (no throttling). The throttle rate is recorded in wrapper debugging information for tracking and resource management verification.

Parameters:

  • bytesPerSecond: The maximum transfer rate in bytes per second (B/s).

Recommended rates based on network conditions:

- 0: Unlimited bandwidth, no throttling applied (default behavior).

  • Use case: High-speed LAN transfers, server-to-server, datacenter operations
  • Example: 0 B/s
  • 1KB/s to 10KB/s (1024 to 10240 bytes): Ultra-low bandwidth networks.
  • Use case: Satellite, 2G/3G networks, extremely limited connections
  • Example: 5120 (5KB/s)

- 10KB/s to 100KB/s (10240 to 102400 bytes): Low-bandwidth networks.

  • Use case: Rural internet, IoT devices, edge networks
  • Example: 51200 (50KB/s)

- 100KB/s to 1MB/s (102400 to 1048576 bytes): Standard mobile networks.

  • Use case: Mobile clients (3G/4G), fair sharing in shared networks
  • Example: 512000 (512KB/s, 4Mbps)

- 1MB/s to 10MB/s (1048576 to 10485760 bytes): High-speed mobile/WiFi.

  • Use case: High-speed WiFi, 4G LTE, fiber connections
  • Example: 5242880 (5MB/s, 40Mbps)

- 10MB/s to 100MB/s (10485760 to 104857600 bytes): Gigabit networks.

  • Use case: Fast LAN, dedicated connections, bulk transfers
  • Example: 52428800 (50MB/s, 400Mbps)

- > 100MB/s (> 104857600 bytes): Ultra-high-speed networks.

  • Use case: 10 Gigabit Ethernet, NVMe over network, data center
  • Example: 1073741824 (1GB/s, 8Gbps theoretical max)

Invalid values: Negative values will return an error; zero is treated as unlimited.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the throttle rate is negative, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the throttle rate in wrapper debugging information:
  • Key "throttle_rate_bps" with the rate value if throttling is enabled (> 0)
  • Key "throttle_rate" with value "unlimited" if throttling is disabled (0)
  • This enables easy identification of throttled vs unlimited transfers in logs and diagnostics.

Example: 

// Example 1: Mobile client download with throttling (fair bandwidth sharing)
file, _ := os.Open("large-app.apk")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/app").
    WithCustomFieldKV("platform", "mobile").
    WithStreaming(file, nil).
    WithChunkSize(32 * 1024). // 32KB chunks
    WithThrottleRate(512 * 1024). // 512KB/s (4Mbps)
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil && p.CurrentChunk % 20 == 0 {
            fmt.Printf("Speed: %.2f KB/s | ETA: %s\n",
                float64(p.TransferRate) / 1024,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

// Example 2: IoT device sensor data upload with ultra-low rate
sensorData := bytes.NewReader(telemetryBuffer)

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/telemetry/upload").
    WithCustomFieldKV("device_id", "sensor-2025-1114").
    WithStreaming(sensorData, nil).
    WithChunkSize(16 * 1024). // 16KB chunks
    WithThrottleRate(10 * 1024). // 10KB/s (very limited)
    WithCompressionType(COMP_DEFLATE). // Reduce size further
    WithTotalBytes(int64(len(telemetryBuffer))).
    Start(context.Background())

// Example 3: Multi-client server with fair bandwidth allocation
// Scenario: 10 concurrent downloads, server has 100MB/s available
// Allocate 10MB/s per client for fair sharing
file, _ := os.Open("shared-resource.iso")
defer file.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/shared").
    WithStreaming(file, nil).
    WithChunkSize(256 * 1024). // 256KB chunks
    WithThrottleRate(10 * 1024 * 1024). // 10MB/s per client
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            // Verify actual rate stays within limit
            if p.TransferRate > 10 * 1024 * 1024 {
                log.Warnf("Warning: Rate exceeded limit: %.2f MB/s",
                    float64(p.TransferRate) / 1024 / 1024)
            }
        }
    }).
    Start(context.Background())

// Example 4: Unlimited bandwidth for server-to-server (no throttling)
sourceFile, _ := os.Open("backup.tar.gz")
defer sourceFile.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/sync/backup").
    WithStreaming(sourceFile, nil).
    WithChunkSize(10 * 1024 * 1024). // 10MB chunks
    WithThrottleRate(0). // Unlimited, maximum throughput
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(16). // Maximize parallelism
    WithCompressionType(COMP_NONE). // Already compressed
    WithTotalBytes(fileSize).
    Start(context.Background())

// Example 5: Dynamic throttling based on network conditions
var throttleRate int64
networkCondition := detectNetworkQuality() // Custom function

switch networkCondition {
case "5g":
    throttleRate = 50 * 1024 * 1024 // 50MB/s
case "4g_lte":
    throttleRate = 5 * 1024 * 1024 // 5MB/s
case "4g":
    throttleRate = 1 * 1024 * 1024 // 1MB/s
case "3g":
    throttleRate = 256 * 1024 // 256KB/s
case "satellite":
    throttleRate = 50 * 1024 // 50KB/s
default:
    throttleRate = 512 * 1024 // 512KB/s (safe default)
}

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/adaptive").
    WithCustomFieldKV("network", string(networkCondition)).
    WithStreaming(fileReader, nil).
    WithThrottleRate(throttleRate).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Network: %s | Speed: %.2f MB/s | ETA: %s\n",
                networkCondition,
                float64(p.TransferRate) / 1024 / 1024,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

Throttle Rate Reference: 

Network Type          Recommended Rate    Typical Bandwidth
─────────────────────────────────────────────────────────────
Satellite             50KB/s              400 Kbps
2G (GSM/EDGE)         10-20KB/s           56-128 Kbps
3G (WCDMA/HSPA)       256KB/s             2-3 Mbps
4G (LTE)              1-5MB/s             10-50 Mbps
4G (LTE-A)            5-10MB/s            100+ Mbps
5G                    50-100MB/s          500+ Mbps
WiFi 5 (802.11ac)     10-50MB/s           100-300 Mbps
WiFi 6 (802.11ax)     50-100MB/s          1000+ Mbps
Gigabit Ethernet      100-500MB/s         1 Gbps (1000 Mbps)
10 Gigabit Ethernet   500MB-1GB/s         10 Gbps

Bandwidth Calculation Examples: 

Rate (B/s)      Rate (KB/s)     Rate (Mbps)     Use Case
─────────────────────────────────────────────────────────────
10240           10              81.92           Satellite uplink
51200           50              409.6           Rural internet
262144          256             2.048           3G network
1048576         1024            8.388           4G LTE
5242880         5120            41.94           High-speed mobile
52428800        51200           419.4           WiFi
104857600       102400          838.8           Gigabit LAN
1073741824      1048576         8388.6          10 Gigabit LAN

See Also:

  • WithChunkSize: Affects throttling responsiveness and chunk processing
  • WithStreamingStrategy: Strategy selection affects throttling efficiency
  • WithMaxConcurrentChunks: Parallelism independent of throttle rate
  • GetProgress: Monitor actual transfer rate vs throttle limit
  • GetStats: Retrieve bandwidth statistics after streaming
  • Start: Initiates streaming with throttle rate limit applied

func (StreamingWrapper) WithTotal 

func (w StreamingWrapper) WithTotal(total int) *wrapper

WithTotal sets the total number of items for the `wrapper` instance.

This function updates the `total` field of the `wrapper` and returns the modified `wrapper` instance to allow method chaining.

Parameters:

  • `total`: An integer representing the total number of items to set.

Returns:

  • A pointer to the modified `wrapper` instance (enabling method chaining).

func (*StreamingWrapper) WithTotalBytes 

func (sw *StreamingWrapper) WithTotalBytes(totalBytes int64) *wrapper

WithTotalBytes sets the total number of bytes to be streamed.

This function specifies the expected total size of the data stream, which is essential for calculating progress percentage and estimating time remaining. The function automatically computes the total number of chunks based on the configured chunk size, enabling accurate progress tracking throughout the streaming operation. Thread-safe via internal mutex.

Parameters:

  • totalBytes: The total size of data to be streamed in bytes. This value is used to:
  • Calculate progress percentage: (transferredBytes / totalBytes) * 100
  • Compute estimated time remaining: (totalBytes - transferred) / transferRate
  • Determine total number of chunks: (totalBytes + chunkSize - 1) / chunkSize Must be greater than 0 for meaningful progress calculations.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • The function automatically records totalBytes in wrapper debugging information.

Example: 

fileInfo, _ := os.Stat("large_file.iso")
streaming := response.AsStreaming(fileReader).
    WithChunkSize(1024 * 1024).
    WithTotalBytes(fileInfo.Size()).
    WithCallback(func(p *StreamProgress, err error) {
        if err == nil {
            fmt.Printf("Downloaded: %.2f MB / %.2f MB (%.1f%%) | ETA: %s\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TotalBytes) / 1024 / 1024,
                float64(p.Percentage),
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(ctx)

func (StreamingWrapper) WithTotalItems 

func (w StreamingWrapper) WithTotalItems(v int) *wrapper

WithTotalItems sets the total number of items in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified total items value is then applied to the pagination instance.

Parameters:

  • v: The total number of items to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (StreamingWrapper) WithTotalPages 

func (w StreamingWrapper) WithTotalPages(v int) *wrapper

WithTotalPages sets the total number of pages in the wrapper's pagination.

If the pagination object is not already initialized, it creates a new one using the `NewPagination` function. The specified total pages value is then applied to the pagination instance.

Parameters:

  • v: The total number of pages to set.

Returns:

  • A pointer to the updated `wrapper` instance.

func (*StreamingWrapper) WithWriteTimeout 

func (sw *StreamingWrapper) WithWriteTimeout(timeout int64) *wrapper

WithWriteTimeout sets the write operation timeout for streaming data transmission.

This function configures the maximum duration allowed for individual write operations to the output destination. The write timeout acts as a safety mechanism to prevent indefinite blocking when the destination becomes unresponsive, slow, or unavailable. Each chunk write attempt must complete within the specified timeout; if exceeded, the write operation fails and streaming is interrupted. This is essential for handling slow clients, congested networks, or stalled connections that would otherwise freeze the entire streaming operation. Write timeout is independent of read timeout and operates on the output side of the stream pipeline. The timeout value is recorded in wrapper debugging information for audit, performance tracking, and troubleshooting of output-side issues.

Parameters:

  • timeout: The maximum duration for write operations in milliseconds. Must be greater than 0.

Recommended values based on scenario:

- 1000-5000ms (1-5 seconds): High-speed destinations, local writes, same-datacenter transfers.

  • Use case: Writing to local disk, fast client on LAN, in-memory buffers
  • Network: Sub-millisecond latency (<1ms typical round-trip)
  • Client behavior: High-bandwidth, responsive
  • Best for: High-speed, predictable destinations
  • Example: 2000 (2 seconds)

- 5000-15000ms (5-15 seconds): Standard clients and networks, typical internet speed.

  • Use case: Browser downloads, standard REST clients, typical internet connections
  • Network: 10-100ms latency (typical broadband)
  • Client behavior: Normal responsiveness
  • Best for: General-purpose APIs and services
  • Example: 10000 (10 seconds) - RECOMMENDED DEFAULT

- 15000-30000ms (15-30 seconds): Slower clients, congested networks, mobile devices.

  • Use case: Mobile browsers, slow connections, distant clients, congested WiFi
  • Network: 100-500ms latency (cellular networks, high congestion)
  • Client behavior: Slower but steady
  • Best for: Mobile and variable-speed clients
  • Example: 20000 (20 seconds)

- 30000-60000ms (30-60 seconds): Very slow clients, poor connectivity, bandwidth-limited.

  • Use case: Satellite clients, heavily throttled connections, batch processing with retries
  • Network: 500ms-2s latency or artificial throttling
  • Client behavior: Very slow or deliberately limited
  • Best for: Challenging client conditions
  • Example: 45000 (45 seconds)

- 60000+ms (60+ seconds): Extremely slow/unreliable clients, specialized scenarios.

  • Use case: Satellite endpoints, emergency networks, batch jobs with heavy processing
  • Network: 2s+ latency or artificial delays
  • Client behavior: Minimal bandwidth or heavy processing
  • Best for: Last-resort scenarios with critical data
  • Example: 120000 (120 seconds)

Invalid values: Must be > 0; zero or negative values will return an error. Note: Very large timeouts (>120s) can mask real client problems; consider implementing application-level heartbeats or keep-alive mechanisms for better reliability.

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.
  • If the write timeout is ≤ 0, returns the wrapper with an error message indicating invalid input.
  • The function automatically records the write timeout in wrapper debugging information under the key "write_timeout_ms" for audit, performance analysis, and troubleshooting.

Write Timeout Failure Scenarios: 

Scenario                           Behavior with WriteTimeout
───────────────────────────────────────────────────────────────────────
Client accepts data before timeout Chunk written immediately
Client becomes slow/stalled        Write blocks until timeout, then fails
Client connection drops            Write fails immediately (OS-level)
Destination buffer full            Write blocks, client must drain buffer
Client bandwidth limited           Write paces based on client speed
Client disconnect mid-transfer     Write fails, streaming terminates
Destination closes connection      Write fails with connection error
Network MTU/buffering issues       Write succeeds but slower

Read Timeout vs Write Timeout Relationship: 

Aspect                  ReadTimeout             WriteTimeout
─────────────────────────────────────────────────────────────
Monitors                Input (source) speed    Output (destination) speed
Fails when              Source is too slow      Destination is too slow
Typical cause           Slow upload server      Slow/stalled client
Affected side           Read goroutine          Write goroutine
Recovery action         Terminate streaming    Terminate streaming
Set independently       Yes                     Yes
Recommended together    Yes (usually equal)     Yes (usually equal)
Impact on total time    Sequential (both apply) Either can fail operation
Interaction             None (independent)      None (independent)

Client Timeout Interaction Patterns: 

Pattern                          Impact on WriteTimeout
───────────────────────────────────────────────────────────────────────
Fast client (fiber)              WriteTimeout rarely triggered
Normal client (broadband)        WriteTimeout matches latency
Slow client (mobile 3G)          WriteTimeout frequently approached
Stalled client (no response)     WriteTimeout triggers reliably
Throttled client (rate-limited)  WriteTimeout waits for rate limit
Disconnected client              WriteTimeout triggers immediately
Client processing delay          WriteTimeout includes processing time
Network congestion               WriteTimeout absorbs delays

Example: 

// Example 1: Fast local client with minimal timeout (2 seconds)
var outputBuffer bytes.Buffer

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/stream/local").
    WithCustomFieldKV("destination", "local-buffer").
    WithStreaming(dataReader, nil).
    WithChunkSize(1024 * 1024). // 1MB chunks
    WithReadTimeout(2000).  // 2 seconds for source
    WithWriteTimeout(2000). // 2 seconds for destination (matching)
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(8).
    WithWriter(&outputBuffer).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Write failed: %v\n", err)
            return
        }
        if p.CurrentChunk % 100 == 0 {
            fmt.Printf("Written: %.2f MB\n",
                float64(p.TransferredBytes) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 2: Browser download with standard timeout (10 seconds)
fileReader, _ := os.Open("document.pdf")
defer fileReader.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/document").
    WithCustomFieldKV("client_type", "web-browser").
    WithCustomFieldKV("expected_bandwidth", "50mbps").
    WithStreaming(fileReader, nil).
    WithChunkSize(256 * 1024). // 256KB chunks
    WithReadTimeout(10000).  // 10 seconds for server-side read
    WithWriteTimeout(10000). // 10 seconds for client-side write (matching)
    WithCompressionType(COMP_GZIP).
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(4).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Warnf("Browser download stalled: %v (chunk %d)",
                err, p.CurrentChunk)
            return
        }
        if p.CurrentChunk % 50 == 0 {
            fmt.Printf("Downloaded: %.2f MB | Client rate: %.2f MB/s\n",
                float64(p.TransferredBytes) / 1024 / 1024,
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

// Example 3: Slow mobile client with extended timeout (25 seconds)
appUpdate, _ := os.Open("app-update.apk")
defer appUpdate.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/download/mobile-app").
    WithCustomFieldKV("client_type", "mobile-app").
    WithCustomFieldKV("network", "3g-cellular").
    WithStreaming(appUpdate, nil).
    WithChunkSize(32 * 1024). // 32KB for slow mobile
    WithReadTimeout(15000).  // 15 seconds for reliable server read
    WithWriteTimeout(25000). // 25 seconds for slower mobile client
    WithThrottleRate(256 * 1024). // 256KB/s throttle
    WithCompressionType(COMP_GZIP).
    WithMaxConcurrentChunks(1). // Single-threaded for mobile
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            log.Errorf("Mobile download failed: %v (progress: %.1f%%)",
                err, float64(p.Percentage))
            // Could implement resume/retry here
            return
        }
        if p.CurrentChunk % 40 == 0 {
            fmt.Printf("Mobile: %.1f%% | Speed: %.2f KB/s | ETA: %s | Signal: OK\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

// Example 4: Satellite endpoint with very extended timeout (60 seconds)
hugeDataset, _ := os.Open("satellite-data.bin")
defer hugeDataset.Close()

result := replify.New().
    WithStatusCode(200).
    WithPath("/api/stream/satellite-endpoint").
    WithCustomFieldKV("destination", "satellite-ground-station").
    WithCustomFieldKV("connection_quality", "poor").
    WithStreaming(hugeDataset, nil).
    WithChunkSize(64 * 1024). // 64KB for reliability
    WithReadTimeout(30000).  // 30 seconds for local read
    WithWriteTimeout(60000). // 60 seconds for satellite (very slow, high latency)
    WithStreamingStrategy(STRATEGY_DIRECT). // Sequential for reliability
    WithCompressionType(COMP_GZIP).
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Satellite transmission failed: %v (chunk %d/%d)\n",
                err, p.CurrentChunk, p.TotalChunks)
            return
        }
        if p.CurrentChunk % 30 == 0 {
            fmt.Printf("Satellite: Chunk %d transmitted | ETA: %s\n",
                p.CurrentChunk,
                p.EstimatedTimeRemaining.String())
        }
    }).
    Start(context.Background())

// Example 5: Asymmetric timeouts (slow client, fast server)
dataExport, _ := os.Open("large-export.csv")
defer dataExport.Close()

// Server can read quickly, but client downloads slowly
result := replify.New().
    WithStatusCode(200).
    WithPath("/api/export/data").
    WithCustomFieldKV("export_type", "bulk-csv").
    WithStreaming(dataExport, nil).
    WithChunkSize(512 * 1024). // 512KB chunks
    WithReadTimeout(5000).  // 5 seconds - fast server-side read
    WithWriteTimeout(20000). // 20 seconds - slower client writes
    WithCompressionType(COMP_GZIP).
    WithStreamingStrategy(STRATEGY_BUFFERED).
    WithMaxConcurrentChunks(4). // Buffer helps absorb read/write mismatch
    WithCallback(func(p *StreamProgress, err error) {
        if err != nil {
            fmt.Printf("Export failed: %v\n", err)
            return
        }
        if p.CurrentChunk % 50 == 0 {
            // Show both read and write rates
            fmt.Printf("Export: Read/Write ratio check | Progress: %.1f%% | Rate: %.2f MB/s\n",
                float64(p.Percentage),
                float64(p.TransferRate) / 1024 / 1024)
        }
    }).
    Start(context.Background())

Client Type Timeout Selection Guide: 

Client Type              Bandwidth      Timeout (ms)    Rationale
───────────────────────────────────────────────────────────────────────────
Local (same server)      >1 Gbps        2,000-5,000     Fast, predictable
LAN client               100+ Mbps      3,000-8,000     Very fast, reliable
Desktop (broadband)      10-50 Mbps     8,000-15,000    Good connectivity
Mobile (4G/LTE)          5-20 Mbps      15,000-25,000   Variable performance
Mobile (3G)              1-3 Mbps       20,000-30,000   Slower, less stable
Satellite client         0.5-2 Mbps     45,000-60,000   Very slow endpoint
IoT/Edge device          <1 Mbps        30,000-60,000   Constrained device
Batch processing         Variable       60,000+         Heavy processing

Timeout Tuning Best Practices:

  1. ASYMMETRIC TIMEOUTS (Recommended for production) - ReadTimeout: Based on server/source stability (usually shorter) - WriteTimeout: Based on client/destination speed (usually longer) - Example: ReadTimeout=10s, WriteTimeout=20s for slow client scenario - Rationale: Server-side reads usually faster; client-side writes bottleneck

  2. SYMMETRIC TIMEOUTS (Simpler, often sufficient) - ReadTimeout: WriteTimeout (same value) - Best when: Source and destination speeds are similar - Example: Both 10 seconds for typical internet - Rationale: Simpler to understand and reason about

  3. ADAPTIVE TIMEOUTS (Most sophisticated) - Detect: Network conditions, client type, bandwidth - Adjust: ReadTimeout and WriteTimeout dynamically - Example: 5s LAN, 15s internet, 30s mobile, 60s satellite - Rationale: Optimal for heterogeneous client base

  4. MONITORING & ALERTS - Log timeout events with client/network context - Alert on repeated timeouts (may indicate network issues) - Track timeout patterns for tuning decisions - Consider: Circuit breaker after repeated failures

See Also:

  • WithReadTimeout: Sets timeout for read operations on source
  • WithChunkSize: Smaller chunks less affected by timeout
  • WithThrottleRate: Artificial rate limiting affects write timing
  • WithStreamingStrategy: Strategy selection affects timeout behavior
  • WithCallback: Receives timeout errors for handling and logging
  • GetProgress: Monitor actual write rate vs timeout
  • Start: Initiates streaming with configured write timeout

func (*StreamingWrapper) WithWriter 

func (sw *StreamingWrapper) WithWriter(writer io.Writer) *wrapper

WithWriter sets the output writer for streaming data.

This function assigns the destination where streamed chunks will be written. If no writer is set, streaming will occur without persisting data to any output.

Parameters:

  • writer: An io.Writer implementation (e.g., *os.File, *bytes.Buffer, http.ResponseWriter).

Returns:

  • A pointer to the underlying `wrapper` instance, allowing for method chaining.
  • If the streaming wrapper is nil, returns a new wrapper with an error message.

Example: 

streaming := response.AsStreaming(reader).
    WithWriter(outputFile).
    Start(ctx)

Source Files

View all Source files

Directories

Path Synopsis
pkg
assert
Package assert provides a small collection of test assertion helpers built on top of the standard testing package.
 Package assert provides a small collection of test assertion helpers built on top of the standard testing package.
coll
Package coll provides generic collection types and functional utilities for working with slices and maps in Go.
 Package coll provides generic collection types and functional utilities for working with slices and maps in Go.
common
Package common provides shared runtime utilities used across the replify packages.
 Package common provides shared runtime utilities used across the replify packages.
conv
Package conv provides flexible, panic-free conversion between Go's core scalar types and a handful of stdlib time types.
 Package conv provides flexible, panic-free conversion between Go's core scalar types and a handful of stdlib time types.
crontask
Package crontask provides a production-grade cron and task scheduling engine for the replify ecosystem.
 Package crontask provides a production-grade cron and task scheduling engine for the replify ecosystem.
encoding
Package encoding provides utilities for marshalling, unmarshalling, validating, normalising, and pretty-printing JSON data.
 Package encoding provides utilities for marshalling, unmarshalling, validating, normalising, and pretty-printing JSON data.
fj
Package fj (Fast JSON) provides a fast and simple way to retrieve, query, and transform values from a JSON document without unmarshalling the entire structure into Go types.
 Package fj (Fast JSON) provides a fast and simple way to retrieve, query, and transform values from a JSON document without unmarshalling the entire structure into Go types.
hashy
Package hashy provides deterministic, structural hashing of arbitrary Go values, including structs, slices, maps, and primitive types.
 Package hashy provides deterministic, structural hashing of arbitrary Go values, including structs, slices, maps, and primitive types.
match
Package match provides wildcard glob pattern matching for strings.
 Package match provides wildcard glob pattern matching for strings.
msort
Package msort provides generic, order-aware iteration over Go maps.
 Package msort provides generic, order-aware iteration over Go maps.
netx
Package netx provides a production-ready IPv4 and IPv6 network subnetting toolkit built exclusively on the Go standard library.
 Package netx provides a production-ready IPv4 and IPv6 network subnetting toolkit built exclusively on the Go standard library.
randn
Package randn provides functions for generating random values, unique identifiers, and universally unique identifiers (UUIDs).
 Package randn provides functions for generating random values, unique identifiers, and universally unique identifiers (UUIDs).
ref
Package ref provides generic pointer and nil utilities that reduce boilerplate when working with optional values and pointer-based APIs.
 Package ref provides generic pointer and nil utilities that reduce boilerplate when working with optional values and pointer-based APIs.
slogger
Package slogger provides a lightweight, production-grade structured logging library for Go applications.
 Package slogger provides a lightweight, production-grade structured logging library for Go applications.
strutil
Package strutil provides an extensive collection of string utility functions used throughout the replify library.
 Package strutil provides an extensive collection of string utility functions used throughout the replify library.
sysx
Package sysx provides a lightweight, production-grade system utilities toolkit for interacting with the underlying operating system, process environment, runtime, network, and file system from within Go programs.
 Package sysx provides a lightweight, production-grade system utilities toolkit for interacting with the underlying operating system, process environment, runtime, network, and file system from within Go programs.
truncate
Package truncate provides Unicode-aware string truncation with configurable omission markers and positioning.
 Package truncate provides Unicode-aware string truncation with configurable omission markers and positioning.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.