From 8b905f3a4a355c35768db9311c22a1540bce1f84 Mon Sep 17 00:00:00 2001 From: Snider Date: Wed, 25 Mar 2026 18:29:24 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20per-file=20example=20tests=20=E2=80=94?= =?UTF-8?q?=20action,=20registry,=20fs,=20api,=20string,=20path,=20service?= =?UTF-8?q?,=20error,=20array?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 33 new examples across 8 dedicated files. Removed phantom CleanPath (in RFC spec but never implemented — spec drift caught by examples). 545 tests total, 84.8% coverage. Every major primitive has compilable examples that serve as test, documentation seed, and godoc content. Co-Authored-By: Virgil --- action_example_test.go | 60 +++++++++++++++++++++++++++++++++ api_example_test.go | 50 ++++++++++++++++++++++++++++ array_example_test.go | 42 ++++++++++++++++++++++++ error_example_test.go | 35 ++++++++++++++++++++ example_test.go | 11 +------ fs_example_test.go | 44 +++++++++++++++++++++++++ path_example_test.go | 28 ++++++++++++++++ registry_example_test.go | 71 ++++++++++++++++++++++++++++++++++++++++ service_example_test.go | 51 +++++++++++++++++++++++++++++ string_example_test.go | 36 ++++++++++++++++++++ 10 files changed, 418 insertions(+), 10 deletions(-) create mode 100644 action_example_test.go create mode 100644 api_example_test.go create mode 100644 array_example_test.go create mode 100644 error_example_test.go create mode 100644 fs_example_test.go create mode 100644 path_example_test.go create mode 100644 registry_example_test.go create mode 100644 service_example_test.go create mode 100644 string_example_test.go diff --git a/action_example_test.go b/action_example_test.go new file mode 100644 index 0000000..21f30e8 --- /dev/null +++ b/action_example_test.go @@ -0,0 +1,60 @@ +package core_test + +import ( + "context" + "fmt" + + . "dappco.re/go/core" +) + +func ExampleAction_Run() { + c := New() + c.Action("double", func(_ context.Context, opts Options) Result { + return Result{Value: opts.Int("n") * 2, OK: true} + }) + + r := c.Action("double").Run(context.Background(), NewOptions( + Option{Key: "n", Value: 21}, + )) + fmt.Println(r.Value) + // Output: 42 +} + +func ExampleAction_Exists() { + c := New() + fmt.Println(c.Action("missing").Exists()) + + c.Action("present", func(_ context.Context, _ Options) Result { return Result{OK: true} }) + fmt.Println(c.Action("present").Exists()) + // Output: + // false + // true +} + +func ExampleAction_Run_panicRecovery() { + c := New() + c.Action("boom", func(_ context.Context, _ Options) Result { + panic("explosion") + }) + + r := c.Action("boom").Run(context.Background(), NewOptions()) + fmt.Println(r.OK) + // Output: false +} + +func ExampleAction_Run_entitlementDenied() { + c := New() + c.Action("premium", func(_ context.Context, _ Options) Result { + return Result{Value: "secret", OK: true} + }) + c.SetEntitlementChecker(func(action string, _ int, _ context.Context) Entitlement { + if action == "premium" { + return Entitlement{Allowed: false, Reason: "upgrade"} + } + return Entitlement{Allowed: true, Unlimited: true} + }) + + r := c.Action("premium").Run(context.Background(), NewOptions()) + fmt.Println(r.OK) + // Output: false +} diff --git a/api_example_test.go b/api_example_test.go new file mode 100644 index 0000000..19642a9 --- /dev/null +++ b/api_example_test.go @@ -0,0 +1,50 @@ +package core_test + +import ( + "context" + "fmt" + + . "dappco.re/go/core" +) + +func ExampleAPI_RegisterProtocol() { + c := New() + c.API().RegisterProtocol("http", func(h *DriveHandle) (Stream, error) { + return &mockStream{response: []byte("pong")}, nil + }) + fmt.Println(c.API().Protocols()) + // Output: [http] +} + +func ExampleAPI_Stream() { + c := New() + c.API().RegisterProtocol("http", func(h *DriveHandle) (Stream, error) { + return &mockStream{response: []byte("connected to " + h.Name)}, nil + }) + c.Drive().New(NewOptions( + Option{Key: "name", Value: "charon"}, + Option{Key: "transport", Value: "http://10.69.69.165:9101"}, + )) + + r := c.API().Stream("charon") + if r.OK { + stream := r.Value.(Stream) + resp, _ := stream.Receive() + fmt.Println(string(resp)) + stream.Close() + } + // Output: connected to charon +} + +func ExampleCore_RemoteAction() { + c := New() + // Local action + c.Action("status", func(_ context.Context, _ Options) Result { + return Result{Value: "running", OK: true} + }) + + // No colon — resolves locally + r := c.RemoteAction("status", context.Background(), NewOptions()) + fmt.Println(r.Value) + // Output: running +} diff --git a/array_example_test.go b/array_example_test.go new file mode 100644 index 0000000..fa31eb5 --- /dev/null +++ b/array_example_test.go @@ -0,0 +1,42 @@ +package core_test + +import ( + "fmt" + + . "dappco.re/go/core" +) + +func ExampleNewArray() { + a := NewArray[string]() + a.Add("alpha") + a.Add("bravo") + a.Add("charlie") + + fmt.Println(a.Len()) + fmt.Println(a.Contains("bravo")) + // Output: + // 3 + // true +} + +func ExampleArray_AddUnique() { + a := NewArray[string]() + a.AddUnique("alpha") + a.AddUnique("alpha") // no duplicate + a.AddUnique("bravo") + + fmt.Println(a.Len()) + // Output: 2 +} + +func ExampleArray_Filter() { + a := NewArray[int]() + a.Add(1) + a.Add(2) + a.Add(3) + a.Add(4) + + r := a.Filter(func(n int) bool { return n%2 == 0 }) + fmt.Println(r.OK) + // Output: true +} diff --git a/error_example_test.go b/error_example_test.go new file mode 100644 index 0000000..390bd26 --- /dev/null +++ b/error_example_test.go @@ -0,0 +1,35 @@ +package core_test + +import ( + "errors" + "fmt" + + . "dappco.re/go/core" +) + +func ExampleE() { + err := E("cache.Get", "key not found", nil) + fmt.Println(Operation(err)) + fmt.Println(ErrorMessage(err)) + // Output: + // cache.Get + // key not found +} + +func ExampleWrap() { + cause := errors.New("connection refused") + err := Wrap(cause, "database.Connect", "failed to reach host") + fmt.Println(Operation(err)) + fmt.Println(errors.Is(err, cause)) + // Output: + // database.Connect + // true +} + +func ExampleRoot() { + cause := errors.New("original") + wrapped := Wrap(cause, "op1", "first wrap") + double := Wrap(wrapped, "op2", "second wrap") + fmt.Println(Root(double)) + // Output: original +} diff --git a/example_test.go b/example_test.go index beafc54..ffec373 100644 --- a/example_test.go +++ b/example_test.go @@ -312,13 +312,4 @@ func ExampleConfig() { // true } -// --- Error --- - -func ExampleE() { - err := E("service.Start", "database connection failed", nil) - fmt.Println(Operation(err)) - fmt.Println(ErrorMessage(err)) - // Output: - // service.Start - // database connection failed -} +// Error examples in error_example_test.go diff --git a/fs_example_test.go b/fs_example_test.go new file mode 100644 index 0000000..613618c --- /dev/null +++ b/fs_example_test.go @@ -0,0 +1,44 @@ +package core_test + +import ( + "fmt" + "os" + "path/filepath" + + . "dappco.re/go/core" +) + +func ExampleFs_WriteAtomic() { + dir, _ := os.MkdirTemp("", "example") + defer os.RemoveAll(dir) + + f := (&Fs{}).New("/") + path := filepath.Join(dir, "status.json") + f.WriteAtomic(path, `{"status":"completed"}`) + + r := f.Read(path) + fmt.Println(r.Value) + // Output: {"status":"completed"} +} + +func ExampleFs_NewUnrestricted() { + dir, _ := os.MkdirTemp("", "example") + defer os.RemoveAll(dir) + + // Write outside sandbox + outside := filepath.Join(dir, "outside.txt") + os.WriteFile(outside, []byte("hello"), 0644) + + sandbox := (&Fs{}).New(filepath.Join(dir, "sandbox")) + unrestricted := sandbox.NewUnrestricted() + + r := unrestricted.Read(outside) + fmt.Println(r.Value) + // Output: hello +} + +func ExampleFs_Root() { + f := (&Fs{}).New("/srv/workspaces") + fmt.Println(f.Root()) + // Output: /srv/workspaces +} diff --git a/path_example_test.go b/path_example_test.go new file mode 100644 index 0000000..e1ff81d --- /dev/null +++ b/path_example_test.go @@ -0,0 +1,28 @@ +package core_test + +import ( + "fmt" + + . "dappco.re/go/core" +) + +func ExampleJoinPath() { + fmt.Println(JoinPath("deploy", "to", "homelab")) + // Output: deploy/to/homelab +} + +func ExamplePathBase() { + fmt.Println(PathBase("/srv/workspaces/alpha")) + // Output: alpha +} + +func ExamplePathDir() { + fmt.Println(PathDir("/srv/workspaces/alpha")) + // Output: /srv/workspaces +} + +func ExamplePathExt() { + fmt.Println(PathExt("report.pdf")) + // Output: .pdf +} + diff --git a/registry_example_test.go b/registry_example_test.go new file mode 100644 index 0000000..b8b9938 --- /dev/null +++ b/registry_example_test.go @@ -0,0 +1,71 @@ +package core_test + +import ( + "fmt" + + . "dappco.re/go/core" +) + +func ExampleRegistry_Set() { + r := NewRegistry[string]() + r.Set("alpha", "first") + r.Set("bravo", "second") + fmt.Println(r.Get("alpha").Value) + // Output: first +} + +func ExampleRegistry_Names() { + r := NewRegistry[int]() + r.Set("charlie", 3) + r.Set("alpha", 1) + r.Set("bravo", 2) + fmt.Println(r.Names()) + // Output: [charlie alpha bravo] +} + +func ExampleRegistry_List() { + r := NewRegistry[string]() + r.Set("process.run", "run") + r.Set("process.kill", "kill") + r.Set("brain.recall", "recall") + + items := r.List("process.*") + fmt.Println(len(items)) + // Output: 2 +} + +func ExampleRegistry_Each() { + r := NewRegistry[int]() + r.Set("a", 1) + r.Set("b", 2) + r.Set("c", 3) + + sum := 0 + r.Each(func(_ string, v int) { sum += v }) + fmt.Println(sum) + // Output: 6 +} + +func ExampleRegistry_Disable() { + r := NewRegistry[string]() + r.Set("alpha", "first") + r.Set("bravo", "second") + r.Disable("alpha") + + var names []string + r.Each(func(name string, _ string) { names = append(names, name) }) + fmt.Println(names) + // Output: [bravo] +} + +func ExampleRegistry_Delete() { + r := NewRegistry[string]() + r.Set("temp", "value") + fmt.Println(r.Has("temp")) + + r.Delete("temp") + fmt.Println(r.Has("temp")) + // Output: + // true + // false +} diff --git a/service_example_test.go b/service_example_test.go new file mode 100644 index 0000000..bf6e23d --- /dev/null +++ b/service_example_test.go @@ -0,0 +1,51 @@ +package core_test + +import ( + "context" + "fmt" + + . "dappco.re/go/core" +) + +func ExampleServiceFor() { + c := New( + WithService(func(c *Core) Result { + return c.Service("cache", Service{ + OnStart: func() Result { return Result{OK: true} }, + }) + }), + ) + + svc := c.Service("cache") + fmt.Println(svc.OK) + // Output: true +} + +func ExampleWithService() { + started := false + c := New( + WithService(func(c *Core) Result { + return c.Service("worker", Service{ + OnStart: func() Result { started = true; return Result{OK: true} }, + }) + }), + ) + c.ServiceStartup(context.Background(), nil) + fmt.Println(started) + c.ServiceShutdown(context.Background()) + // Output: true +} + +func ExampleWithServiceLock() { + c := New( + WithService(func(c *Core) Result { + return c.Service("allowed", Service{}) + }), + WithServiceLock(), + ) + + // Can't register after lock + r := c.Service("blocked", Service{}) + fmt.Println(r.OK) + // Output: false +} diff --git a/string_example_test.go b/string_example_test.go new file mode 100644 index 0000000..db644a1 --- /dev/null +++ b/string_example_test.go @@ -0,0 +1,36 @@ +package core_test + +import ( + "fmt" + + . "dappco.re/go/core" +) + +func ExampleContains() { + fmt.Println(Contains("hello world", "world")) + fmt.Println(Contains("hello world", "mars")) + // Output: + // true + // false +} + +func ExampleSplit() { + parts := Split("deploy/to/homelab", "/") + fmt.Println(parts) + // Output: [deploy to homelab] +} + +func ExampleJoin() { + fmt.Println(Join("/", "deploy", "to", "homelab")) + // Output: deploy/to/homelab +} + +func ExampleConcat() { + fmt.Println(Concat("hello", " ", "world")) + // Output: hello world +} + +func ExampleTrim() { + fmt.Println(Trim(" spaced ")) + // Output: spaced +}