Merge pull request #1 from NeutrinoCorp/beta

Beta Release

Author: aruizeac

.github/workflows/publish.yml

@@ -0,0 +1,14 @@
+name: Publish Go Module
+
+on:
+  push:
+    tags:
+      - '*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Force Go package publishing
+        run: make publish-pkg version="${{github.ref_name}}" module_name=streams

.github/workflows/test-build.yml

@@ -0,0 +1,76 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+env:
+  GO111MODULE: 'on'
+
+permissions:
+  contents: read
+  pull-requests: read
+  checks: write
+
+jobs:
+  lint:
+    name: Run Go Linter
+    strategy:
+      matrix:
+        os: ['ubuntu-latest']
+        go-version: ['1.21', '1.22']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+
+      - name: Run linter
+        uses: golangci/golangci-lint-action@v6
+        with:
+          version: v1.58
+
+  unit-testing:
+    name: Run Unit Tests
+    strategy:
+      matrix:
+        os: [ 'ubuntu-latest' ]
+        go-version: ['1.21', '1.22' ]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+
+      - name: Run Unit Testing
+        run: go test ./... -cover
+
+  integration-testing:
+    name: Run Integration Tests
+    strategy:
+      matrix:
+        os: [ 'ubuntu-latest' ]
+        go-version: ['1.21', '1.22' ]
+    runs-on: ${{ matrix.os }}
+    needs: ['unit-testing']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+
+      - name: Run Integration Testing
+        run: go test ./... -tags=integration -cover

.golangci.yml

@@ -0,0 +1,41 @@
+# Refer to golangci-lint's example config file for more options and information:
+# https://github.com/golangci/golangci-lint/blob/master/.golangci.reference.yml
+
+run:
+  tests: true
+  timeout: 5m
+  allow-parallel-runners: true
+  modules-download-mode: readonly
+
+output:
+  formats:
+    - format: github-actions
+
+linters:
+  enable:
+    - goimports
+  presets:
+    - bugs
+    - comment
+    - complexity
+    - error
+    - metalinter
+    - module
+    - performance
+    - style
+    - test
+    - unused
+
+#linters:
+#  enable:
+#    - errcheck
+#    - goimports
+#    - golint
+#    - govet
+#    - staticcheck
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  fix: true

Makefile

@@ -0,0 +1,2 @@
+run-test:
+	go test ./... -cover

README.md

@@ -1,2 +1,126 @@
-# nolan
-Neutrino core libraries for Go
+# Nolan
+
+Welcome `nolan`, a comprehensive toolkit designed to enhance the development of Golang applications by providing a range of modules and utilities that streamline common programming tasks.
+
+## Features
+
+This library includes a variety of modules that offer functionalities such as:
+
+- **Data Manipulation**: Tools for handling and transforming data structures.
+- **Concurrency Utilities**: Enhancements for Go's native concurrency model, making goroutine management easier.
+- **Process Utilities**: Easy-to-use modules for process scheduling and management.
+
+## Getting Started
+
+To use this library, you need to have Go installed on your machine. You can install Go by following the instructions on the [official Go website](https://golang.org/dl/).
+
+### Installation
+
+Install the library with the following Go command:
+
+```bash
+go get github.com/neutrinocorp/nolan
+```
+
+### Usage
+
+Here's a simple example of how to use a module from this library:
+
+#### Data Structures
+
+```go
+package main
+
+import (
+	"fmt"
+
+	"github.com/neutrinocorp/nolan"
+	"github.com/neutrinocorp/nolan/collection/list"
+	"github.com/neutrinocorp/nolan/collection/queue"
+)
+
+func main() {
+	ls := list.NewDoublyLinkedList[int]()
+	ls.Add(1)
+	ls.Add(2)
+	ls.Add(3)
+	fmt.Println(ls.ToSlice())
+	
+	deque := queue.NewDequeList[int](ls)
+	fmt.Println(deque.PollLast()) // 3
+	fmt.Println(deque.PollLast()) // 2
+	fmt.Println(deque.PollLast()) // 1
+}
+```
+
+#### Processing
+
+```go
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/neutrinocorp/nolan"
+	"github.com/neutrinocorp/nolan/collection/list"
+	"github.com/neutrinocorp/nolan/collection/queue"
+	"github.com/neutrinocorp/nolan/function"
+	"github.com/neutrinocorp/nolan/proc"
+)
+
+func main() {
+	var delegateFunc function.DelegateSafeFuncWithContext[string] = func(ctx context.Context, args string) error {
+		log.Printf("some args %s", args)
+		return nil
+	}
+
+	sched := proc.NewTaskScheduler[string](delegateFunc)
+	go func() {
+		if err := sched.Start(); err != nil {
+			panic(err)
+		}
+	}()
+
+	if err := sched.SubmitWork("some job"); err != nil {
+		panic(err) // this will return an error if the process is already closed
+	}
+	if err := sched.SubmitWork("some job"); err != nil {
+		panic(err)
+	}
+
+	// ... os.Stdout will print jobs as delegate will get executed
+
+	// execute graceful shutdown
+	ctx, cancelFunc := context.WithTimeout(context.Background(), time.Second * 30)
+	defer cancelFunc()
+	if err := sched.Stop(ctx); err != nil {
+		panic(err) // will return error if context reaches deadline before actual process termination (i.e., interrupted)
+    }
+}
+```
+
+## Documentation
+
+For more detailed documentation on each module and its functions, visit the [Documentation](https://github.com/neutrinocorp/nolan/wiki) section of this repository.
+
+## Contributing
+
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+
+## Contact
+
+Your Name - [@neutrinocorp](https://twitter.com/neuntrinocorp) - oss@neutrinocorp.org
+
+Project Link: [https://github.com/neuntrinocorp/nolan](https://github.com/neuntrinocorp/nolan)

collection/bag/bag.go

@@ -0,0 +1,3 @@
+package bag
+
+// TODO: IMPLEMENT ME

collection/bag/hash.go

@@ -0,0 +1,3 @@
+package bag
+
+// TODO: IMPLEMENT ME

collection/collection.go

@@ -1,26 +1,25 @@
 package collection
 
-// Collection A collection represents a group of objects, known as its elements. Some collections allow duplicate
-// elements and others do not. Some are ordered and others unordered.
+// Collection a collection represents a group of objects, known as its elements.
+// Some collections allow duplicate elements and others do not.
+// Some are ordered and others unordered.
 type Collection[T any] interface {
 	Iterable[T]
-	// Add Ensures that this collection contains the specified element.
+	// Add adds an element into this collection.
 	Add(v T) bool
-	// AddAll Adds all the elements in the specified collection to this collection.
+	// AddAll adds all the elements into this collection.
 	AddAll(src Collection[T]) bool
-	// Clear Removes all the elements from this collection.
+	// AddSlice adds all the elements in the specified slice (variadic) to this collection.
+	AddSlice(items ...T) bool
+	// Clear removes all the elements from this collection.
 	Clear()
-	// Len Returns the number of elements in this collection.
+	// Len returns the number of elements in this collection.
 	Len() int
-	// IsEmpty Returns true if this collection contains no elements.
+	// IsEmpty returns true if this collection contains no elements.
 	IsEmpty() bool
-	// ToSlice Returns all the elements from this collection as a slice of T.
+	// ToSlice returns all the elements from this collection as a slice of T.
 	ToSlice() []T
-}
-
-type ComparableCollection[T comparable] interface {
-	// Contains Returns true if this collection contains the specified element.
-	Contains(v T) bool
-	// ContainsAll Returns true if this collection contains all the elements in the specified collection.
-	ContainsAll(src Collection[T]) bool
+	// ForEach traverses through all the elements from this collection.
+	// Use predicate's return value to indicate a break of the iteration, TRUE meaning a break.
+	ForEach(predicateFunc IterablePredicateFunc[T])
 }

collection/compare.go

@@ -0,0 +1,69 @@
+package collection
+
+import (
+	"github.com/neutrinocorp/nolan/function"
+)
+
+// ComparatorFunc a functional interface used to indicate if the first argument is greater, less or equals than
+// the second.
+// If equals, this will return 0, if less -1 and if greater, then it returns 1.
+type ComparatorFunc[T any] function.DelegateBiFunc[T, T, int]
+
+// ComparableCollection a kind of Collection for comparable types.
+// Note that nolan offers a functional way to operate with Collection and comparable types
+// without the need of this interface (e.g., Contains, ContainsAll, ContainsSlice).
+type ComparableCollection[T comparable] interface {
+	Collection[T]
+	// Contains returns true if this collection contains the specified element.
+	Contains(v T) bool
+	// ContainsAll returns true if this collection contains all the elements in the specified collection.
+	ContainsAll(src Collection[T]) bool
+	// ContainsSlice returns true if this collection contains all the elements in the specified slice.
+	ContainsSlice(src ...T) bool
+}
+
+// NOTE: This is used internally to share iterator instances.
+// This helps to reduce malloc as we can reuse iterator instances.
+func containsWithIterator[T comparable](iter Iterator[T], v T) bool {
+	for iter.HasNext() {
+		if val := iter.Next(); val == v {
+			return true
+		}
+	}
+	return false
+}
+
+// Contains returns true if this collection contains the specified element.
+func Contains[T comparable](src Collection[T], v T) bool {
+	iter := src.NewIterator()
+	return containsWithIterator[T](iter, v)
+}
+
+// ContainsAll returns true if this collection contains all the elements in the specified collection.
+func ContainsAll[T comparable](src Collection[T], cmpColl Collection[T]) bool {
+	// Time complexity of O(mn)
+	srcIter := src.NewIterator()
+	cmpCollIter := cmpColl.NewIterator()
+	for cmpCollIter.HasNext() {
+		item := cmpCollIter.Next()
+		wasFound := containsWithIterator[T](srcIter, item)
+		if !wasFound {
+			return false
+		}
+		srcIter.Reset()
+	}
+	return true
+}
+
+// ContainsSlice returns true if this collection contains all the elements in the specified slice.
+func ContainsSlice[T comparable](src Collection[T], cmpSlice []T) bool {
+	iter := src.NewIterator()
+	for _, item := range cmpSlice {
+		wasFound := containsWithIterator[T](iter, item)
+		if !wasFound {
+			return false
+		}
+		iter.Reset()
+	}
+	return true
+}

collection/doc.go

@@ -0,0 +1,7 @@
+// Package collection is a robust package meticulously crafted to provide a rich assortment of
+// general-purpose data structures and algorithms. Whether you're working with lists, sets, maps, or more complex
+// data types, this package equips you with versatile tools to manage and manipulate data efficiently.
+//
+// From sorting and search algorithms to key data structures like arrays, linked lists, stacks, and queues,
+// 'Collection' offers a comprehensive suite to streamline your development workflow.
+package collection