From 7e327826326ab3ae8d8904857db8f6d29cc1d492 Mon Sep 17 00:00:00 2001
From: Chris Duncan <veqryn@hotmail.com>
Date: Tue, 3 Oct 2023 03:29:24 -0600
Subject: [PATCH] Add package docs

---
 .github/workflows/build_and_test.yml |  2 +-
 README.md                            |  2 +-
 doc.go                               | 80 ++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 doc.go

diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml
index 8c4bec0..c0c63ea 100644
--- a/.github/workflows/build_and_test.yml
+++ b/.github/workflows/build_and_test.yml
@@ -1,7 +1,7 @@
 # This workflow will build a golang project
 # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
 
-name: Build And Test
+name: Tests
 
 on:
   push:
diff --git a/README.md b/README.md
index 7303430..acf738c 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ The main impetus behind this package is because most JSON tools do not like dupl
 
 Unfortunately the default behavior of the stdlib slog handlers is to allow duplicate keys:
 ```go
-// This make json tools unhappy    :(
+// This makes json tools unhappy    :(
 slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))
 slog.Info("this is the stdlib json handler by itself",
     slog.String("duplicated", "zero"),
diff --git a/doc.go b/doc.go
new file mode 100644
index 0000000..bee4523
--- /dev/null
+++ b/doc.go
@@ -0,0 +1,80 @@
+/*
+Package dedup provides structured logging (slog) deduplication for use with json logging
+(or any other format where duplicates are not appreciated).
+The main impetus behind this package is because most JSON tools do not like duplicate keys for their member
+properties/fields. Some of them will give errors or fail to parse the log line, and some may even crash.
+Unfortunately the default behavior of the stdlib slog handlers is to allow duplicate keys.
+
+Usage:
+
+	// OverwriteHandler
+	overwriter := dedup.NewOverwriteHandler(slog.NewJSONHandler(os.Stdout, nil), nil)
+	slog.SetDefault(slog.New(overwriter))
+
+	// {
+	//   "time": "2023-10-03T01:30:00Z",
+	//   "level": "INFO",
+	//   "msg": "this is the dedup overwrite handler",
+	//   "duplicated": "two"
+	// }
+	slog.Info("this is the dedup overwrite handler",
+		slog.String("duplicated", "zero"),
+		slog.String("duplicated", "one"),
+		slog.String("duplicated", "two"),
+	)
+
+	// IgnoreHandler
+	ignorer := dedup.NewIgnoreHandler(slog.NewJSONHandler(os.Stdout, nil), nil)
+	slog.SetDefault(slog.New(ignorer))
+
+	// {
+	//   "time": "2023-10-03T01:30:00Z",
+	//   "level": "INFO",
+	//   "msg": "this is the dedup ignore handler",
+	//   "duplicated": "zero"
+	// }
+	slog.Info("this is the dedup ignore handler",
+		slog.String("duplicated", "zero"),
+		slog.String("duplicated", "one"),
+		slog.String("duplicated", "two"),
+	)
+
+	// IncrementHandler
+	incrementer := dedup.NewIncrementHandler(slog.NewJSONHandler(os.Stdout, nil), nil)
+	slog.SetDefault(slog.New(incrementer))
+
+	// {
+	//   "time": "2023-10-03T01:30:00Z",
+	//   "level": "INFO",
+	//   "msg": "this is the dedup incrementer handler",
+	//   "duplicated": "zero",
+	//   "duplicated#01": "one",
+	//   "duplicated#02": "two"
+	// }
+	slog.Info("this is the dedup incrementer handler",
+		slog.String("duplicated", "zero"),
+		slog.String("duplicated", "one"),
+		slog.String("duplicated", "two"),
+	)
+
+	// AppendHandler
+	appender := dedup.NewAppendHandler(slog.NewJSONHandler(os.Stdout, nil), nil)
+	slog.SetDefault(slog.New(appender))
+
+	// {
+	//   "time": "2023-10-03T01:30:00Z",
+	//   "level": "INFO",
+	//   "msg": "this is the dedup appender handler",
+	//   "duplicated": [
+	//     "zero",
+	//     "one",
+	//     "two"
+	//   ]
+	// }
+	slog.Info("this is the dedup appender handler",
+		slog.String("duplicated", "zero"),
+		slog.String("duplicated", "one"),
+		slog.String("duplicated", "two"),
+	)
+*/
+package dedup