Merge pull request #5 from Oudwins/import-refactor

feat: better support & docs for providing a custom configuration or cache

Author: Oudwins

README.md

@@ -10,7 +10,7 @@ Utility function to efficiently merge Tailwind CSS classes in Golang without sty
 import (
 	"fmt"
 
-	"github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+	twmerge "github.com/Oudwins/tailwind-merge-go"
 )
 
 func main() {
@@ -34,15 +34,74 @@ func main() {
 
 - See [tailwind-merge](https://github.com/dcastil/tailwind-merge/blob/v2.2.1/docs/limitations.md)
 
+## Advanced Examples
+
+You might also want to check out the advanced example at `/cmd/examples/advanced`
+
+### Provide Your Own or Extend Default Config
+
+```go
+import (
+		// Note the import path here is different from the default path. This is so you have access to all the custom functions, structs, etc that are used to build the twmerge config
+		twmerge "github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+)
+var TwMerger twmerge.TwMergeFn
+func main() {
+	// get the default config
+	config := twmerge.MakeDefaultConfig()
+
+	// do your modifications here
+
+	// create the merger
+	TwMerger = twmerge.CreateTwMerge(config, nil) // config, cache (if nil default will be used)
+
+
+	// example usage
+	m := TwMerger("px-4 px-10", "p-20")
+	fmt.Println(m) // output: "p-20"
+}
+```
+
+### Provide your own Cache
+
+The default cache is a LRU Cache and should be acceptable for most use cases. However, you might want to provide your own cache or modify the default creation parameters. Your cache must implement the interface defined at `/pkg/cache/cache.go`
+
+```go
+type ICache interface {
+	Get(string) string
+	Set(string, string) // key, value
+}
+```
+
+Here is an example of manually creating the default cache with a custom max capacity
+
+```go
+import (
+		twmerge "github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+		lru "github.com/Oudwins/tailwind-merge-go/pkg/lru"
+)
+var TwMerger twmerge.TwMergeFn
+func main() {
+	customCapacity := 10000
+	cache := lru.make(customCapacity)
+
+
+	// create the merger
+	TwMerger = twmerge.CreateTwMerge(nil, cache) // config, cache (if nil default will be used)
+
+	// example usage
+	m := TwMerger("px-4 px-10", "p-20")
+	fmt.Println(m) // output: "p-20"
+}
+```
+
 ## Contributing
 
 Checkout the [contributing docs](./CONTRIBUTING.md)
 
 ## Roadmap
 
-- Improve current docs
 - Improve cache concurrent performance by locking on a per key basis -> https://github.com/EagleChen/mapmutex
-- Split code into multiple pkgs so in the twmerge pkg there is only the Merge & CreateTailwindMerge functions
 - Build the class map on initialization and have a simple config style
 - replace regex with more performant solution
 - Move arbitrary value delimeters '[' & ']' to config somehow?

cmd/examples/advanced/withCustomConfig.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"fmt"
+
+	lru "github.com/Oudwins/tailwind-merge-go/pkg/lru"
+	twmerge "github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+)
+
+var TwMerger twmerge.TwMergeFn
+
+func main() {
+	// get the default config
+	config := twmerge.MakeDefaultConfig()
+
+	// make cache
+	cache := lru.Make(10000)
+
+	// do your modifications here
+
+	// create the merger
+	TwMerger = twmerge.CreateTwMerge(config, cache)
+
+	// example usage
+	m := TwMerger("px-4 px-10", "p-20")
+	fmt.Println(m) // output: "p-20"
+}

cmd/examples/default/main.go

@@ -0,0 +1,15 @@
+package main
+
+import (
+	"fmt"
+
+	twmerge "github.com/Oudwins/tailwind-merge-go"
+)
+
+func main() {
+	// mainly used for manual tests
+
+	// example usage
+	m := twmerge.Merge("px-4 px-10", "p-20")
+	fmt.Println(m)
+}

cmd/main/main.go

@@ -3,7 +3,7 @@ package main
 import (
 	"fmt"
 
-	"github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+	twmerge "github.com/Oudwins/tailwind-merge-go"
 )
 
 func main() {

pkg/cache/cache.go

@@ -0,0 +1,6 @@
+package cache
+
+type ICache interface {
+	Get(string) string
+	Set(string, string)
+}

pkg/cache/lru.go renamed to pkg/lru/lru.go

@@ -1,6 +1,10 @@
 package lru
 
-import "sync"
+import (
+	"sync"
+
+	"github.com/Oudwins/tailwind-merge-go/pkg/cache"
+)
 
 type node struct {
 	key  string
@@ -9,11 +13,6 @@ type node struct {
 	next *node
 }
 
-type Cache interface {
-	Get(string) string
-	Set(string, string)
-}
-
 type LRU struct {
 	maxCapacity int
 	capacity    int
@@ -81,7 +80,7 @@ func (lru *LRU) remove(n *node) {
 	lru.capacity--
 }
 
-func Make(maxCapacity int) Cache {
+func Make(maxCapacity int) cache.ICache {
 	head := &node{}
 	tail := &node{}
 	tail.next = head

pkg/twmerge/create-tailwind-merge.go

@@ -3,24 +3,20 @@ package twmerge
 import (
 	"strings"
 
-	lru "github.com/Oudwins/tailwind-merge-go/pkg/cache"
+	cache "github.com/Oudwins/tailwind-merge-go/pkg/cache"
+	lru "github.com/Oudwins/tailwind-merge-go/pkg/lru"
 )
 
-func CreateTwMerge(config *TwMergeConfig, cache lru.Cache) func(args ...string) string {
-	if config == nil {
-		config = MakeDefaultConfig()
-	}
-	if cache == nil {
-		cache = lru.Make(config.MaxCacheSize)
-	}
+type TwMergeFn func(args ...string) string
 
-	splitModifiers := MakeSplitModifiers(config)
+func CreateTwMerge(config *TwMergeConfig, cache cache.ICache) TwMergeFn {
 
-	getClassGroupId := MakeGetClassGroupId(config)
+	var fnToCall TwMergeFn
+	var splitModifiers SplitModifiersFn
+	var getClassGroupId GetClassGroupIdfn
+	var mergeClassList func(classList string) string
 
-	mergeClassList := MakeMergeClassList(config, splitModifiers, getClassGroupId)
-
-	return func(args ...string) string {
+	merger := func(args ...string) string {
 		classList := strings.Join(args, " ")
 		cached := cache.Get(classList)
 		if cached != "" {
@@ -31,6 +27,29 @@ func CreateTwMerge(config *TwMergeConfig, cache lru.Cache) func(args ...string)
 		cache.Set(classList, merged)
 		return merged
 	}
+
+	init := func(args ...string) string {
+		if config == nil {
+			config = MakeDefaultConfig()
+		}
+		if cache == nil {
+			cache = lru.Make(config.MaxCacheSize)
+		}
+
+		splitModifiers = MakeSplitModifiers(config)
+
+		getClassGroupId = MakeGetClassGroupId(config)
+
+		mergeClassList = MakeMergeClassList(config, splitModifiers, getClassGroupId)
+
+		fnToCall = merger
+		return fnToCall(args...)
+	}
+
+	fnToCall = init
+	return func(args ...string) string {
+		return fnToCall(args...)
+	}
 }
 
 var Merge = CreateTwMerge(nil, nil)

twmerge.go

@@ -0,0 +1,7 @@
+package twmerge
+
+import (
+	twmerge "github.com/Oudwins/tailwind-merge-go/pkg/twmerge"
+)
+
+var Merge = twmerge.Merge