formalize: writers, and exports

Author: chase-moskal

README.md

@@ -1,6 +1,8 @@
 
-# 🧪 @e280/sten
-- logging utilities
+![](https://i.imgur.com/TTZbq3k.jpeg)
+
+# 🖋️ @e280/sten
+- logging utility
 - zero dependencies
 - *an https://e280.org/ project*
 
@@ -11,24 +13,42 @@
   ```sh
   npm install @e280/sten
   ```
-- make a logger and do some logging
+- make your logger
   ```ts
   import {Logger} from "@e280/sten"
 
-  const logger = new Logger()
-    .target(Logger.node)
-    .palette(Logger.colorful)
-    .transform(Logger.timestamp)
+  export const logger = new Logger()
+    .setWriter(Logger.writers.auto())
+    .setColors(Logger.colors.auto())
+    .addShaper(Logger.shapers.timestamp())
   ```
 - log a happy message
   ```ts
-  logger.log("hello world!")
+  await logger.log("hello world!")
   ```
 - log an angry message
   ```ts
-  logger.error("something bad happened")
+  await logger.error("something bad happened")
   ```
 
+### writers
+the logger ultimately emits to stdout or stderr via a logger — the available writers are:
+- `auto` — *(default)* automatically chooses `deno`, `node`, or `console`
+- `console` — outputs to console.log and console.error
+- `node` — outputs to process.stdout and process.stderr
+- `deno` — outputs to Deno.stdout and Deno.stderr
+- `void` — outputs nothing
+
+### colors
+determines what happens when colors are used — available colors are:
+- `auto` — *(default)* use color if it looks like we're in a color-supporting environment
+- `colorful` — full ansi color support
+- `colorless` — no color support (all color fns are duds)
+
+### shapers
+a shaper is a fn that transforms the content before it is logged — you can attach any number of shapers, they are executed in order — by default, no shapers are used — the available shapers are:
+- `timestamp` — attaches a timestamp prefix to every message
+
 <br/>
 
 ## 💖 made with open source love

package.json

@@ -11,10 +11,12 @@
 		"s"
 	],
 	"scripts": {
-		"build": "tsc",
+		"build": "run-s _clean _tsc",
+		"_tsc": "tsc",
+		"_clean": "rm -rf x",
 		"build-watch": "tsc -w",
-		"test": "node x/example.test.js --verbose",
-		"test-watch": "node --watch x/example.test.js --verbose",
+		"test": "node x/tests.test.js",
+		"test-watch": "node --watch x/tests.test.js",
 		"start": "run-p build-watch test-watch",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},

s/colors/auto.ts

@@ -0,0 +1,11 @@
+
+import {colorless} from "./colorless.js"
+import {colorful, Colors} from "./colorful.js"
+import {isColorSupported} from "../utils/supports.js"
+
+export const autoColors = (): Colors => {
+	return isColorSupported()
+		? colorful
+		: colorless
+}
+

s/index.ts

@@ -1 +1,6 @@
 
+export {Logger} from "./logger.js"
+export {Writer} from "./writers/writer.js"
+export {Colors} from "./colors/colorful.js"
+export {Shaper, ShaperContext, ShaperFns} from "./shapers/shaper.js"
+

s/logger.ts

@@ -1,56 +1,58 @@
 
-import {Target} from "./targets/target.js"
+import {Writer} from "./writers/writer.js"
 import {Shaper} from "./shapers/shaper.js"
-import {denoTarget} from "./targets/deno.js"
-import {nodeTarget} from "./targets/node.js"
+import {autoColors} from "./colors/auto.js"
+import {denoWriter} from "./writers/deno.js"
+import {nodeWriter} from "./writers/node.js"
+import {voidWriter} from "./writers/void.js"
+import {autoWriter} from "./writers/auto.js"
 import {colorless} from "./colors/colorless.js"
-import {consoleTarget} from "./targets/console.js"
-import {isColorSupported} from "./utils/supports.js"
+import {consoleWriter} from "./writers/console.js"
 import {colorful, Colors} from "./colors/colorful.js"
 import {timestampShaper} from "./shapers/timestamp.js"
 
 export class Logger {
-	static targets = {
-		deno: denoTarget,
-		node: nodeTarget,
-		console: consoleTarget,
+	static writers = {
+		auto: autoWriter,
+		void: voidWriter,
+		deno: denoWriter,
+		node: nodeWriter,
+		console: consoleWriter,
 	}
 
 	static colors = {
+		auto: autoColors,
 		colorful: () => colorful,
 		colorless: () => colorless,
-		auto: () => isColorSupported()
-			? colorful
-			: colorless,
 	}
 
 	static shapers = {
 		timestamp: timestampShaper,
 	}
 
 	colors: Colors = Logger.colors.auto()
-	target = consoleTarget()
+	writer: Writer = Logger.writers.auto()
 	shapers: Shaper[] = []
 
 	async log(...items: any[]) {
 		for (const transform of this.shapers)
 			items = transform(this).stdout(items)
-		await this.target.stdout(items)
+		await this.writer.stdout(items)
 	}
 
 	async error(...items: any[]) {
 		for (const transform of this.shapers)
 			items = transform(this).stderr(items)
-		await this.target.stderr(items)
+		await this.writer.stderr(items)
 	}
 
 	setColors(colors: Colors) {
 		this.colors = colors
 		return this
 	}
 
-	setTarget(target: Target) {
-		this.target = target
+	setWriter(writer: Writer) {
+		this.writer = writer
 		return this
 	}
 

s/shapers/shaper.ts

@@ -5,9 +5,9 @@ export type ShaperContext = {
 	colors: Colors
 }
 
-export type Shaper = (context: ShaperContext) => ShapeFns
+export type Shaper = (context: ShaperContext) => ShaperFns
 
-export type ShapeFns = {
+export type ShaperFns = {
 	stdout: (items: any[]) => any[]
 	stderr: (items: any[]) => any[]
 }

s/tests.test.ts

@@ -1,6 +1,6 @@
 
 import {Logger} from "./logger.js"
-import {MockTarget} from "./targets/mock.js"
+import {MockWriter} from "./writers/mock.js"
 import {Science, test, expect} from "@e280/science"
 
 await Science.run({
@@ -9,21 +9,21 @@ await Science.run({
 			void new Logger()
 		}),
 		"logger with mock": test(async() => {
-			const mock = new MockTarget()
-			void new Logger().setTarget(mock)
+			const mock = new MockWriter()
+			void new Logger().setWriter(mock)
 		}),
 		"logger stdout": test(async() => {
-			const mock = new MockTarget()
-			const logger = new Logger().setTarget(mock)
+			const mock = new MockWriter()
+			const logger = new Logger().setWriter(mock)
 			expect(mock.stdout.spy.calls.length).is(0)
 			await logger.log("hello world!")
 			expect(mock.stdout.spy.calls.length).is(1)
 			expect(mock.getSpyStdout(0)).is("hello world!")
 			expect(mock.stderr.spy.calls.length).is(0)
 		}),
 		"logger stderr": test(async() => {
-			const mock = new MockTarget()
-			const logger = new Logger().setTarget(mock)
+			const mock = new MockWriter()
+			const logger = new Logger().setWriter(mock)
 			expect(mock.stderr.spy.calls.length).is(0)
 			await logger.error("hello world!")
 			expect(mock.stderr.spy.calls.length).is(1)
@@ -34,9 +34,9 @@ await Science.run({
 
 	"shapers": Science.suite({
 		"custom prefix": test(async() => {
-			const mock = new MockTarget()
+			const mock = new MockWriter()
 			const logger = new Logger()
-				.setTarget(mock)
+				.setWriter(mock)
 				.addShaper(() => ({
 					stdout: items => ["stdout:", ...items],
 					stderr: items => ["stderr:", ...items],

s/targets/mock.ts renamed to s/utils/spy.ts

@@ -1,6 +1,4 @@
 
-import {Target} from "./target.js"
-
 export function spy<Fn extends (...args: any[]) => any>(fn: Fn) {
 	const calls: {args: Parameters<Fn>, ret: ReturnType<Fn>}[] = []
 
@@ -30,18 +28,3 @@ export function spy<Fn extends (...args: any[]) => any>(fn: Fn) {
 	return spyFn
 }
 
-export class MockTarget implements Target {
-	stdout = spy((_items: any[]) => {})
-	stderr = spy((_items: any[]) => {})
-
-	getSpyStdout(index: number) {
-		const [items] = this.stdout.spy.args.at(index)!
-		return items.join(" ")
-	}
-
-	getSpyStderr(index: number) {
-		const [items] = this.stderr.spy.args.at(index)!
-		return items.join(" ")
-	}
-}
-

s/writers/auto.ts

@@ -0,0 +1,13 @@
+
+import {Writer} from "./writer.js"
+import {denoWriter} from "./deno.js"
+import {nodeWriter} from "./node.js"
+import {consoleWriter} from "./console.js"
+import {isDeno, isNode} from "../utils/supports.js"
+
+export const autoWriter = (): Writer => {
+	if (isDeno()) return denoWriter()
+	else if (isNode()) return nodeWriter()
+	else return consoleWriter()
+}
+

s/targets/console.ts renamed to s/writers/console.ts

@@ -1,7 +1,7 @@
 
-import {Target} from "./target.js"
+import {Writer} from "./writer.js"
 
-export const consoleTarget = (): Target => ({
+export const consoleWriter = (): Writer => ({
 	stdout: async(items: any[]) => console.log(...items),
 	stderr: async(items: any[]) => console.error(...items),
 })