feat: replace Unicode delimiters with newline-based metadata separation

Author: ReinsBrain

README.md

@@ -20,23 +20,24 @@ npm install strog
 
 ## How It Works
 
-Strog appends structured metadata to your log messages using invisible Unicode characters as delimiters. This approach keeps logs human-readable while making them machine-parsable.
+Strog appends structured metadata to your log messages on a separate line, making logs both human-readable and machine-parsable.
 
-### The Magic: Unicode Delimiters
+### The Magic: Newline Separation
 
-When you create a structured log, Strog appends metadata after your message using special Unicode characters:
+When you create a structured log, Strog appends metadata after your message on a new line:
 
 ```typescript
 const EndpointMetric = StructuredTag('endpoint-metric', ['method', 'endpoint'], false);
 const log = EndpointMetric`GET /users`;
 
-// What you see: "GET /users"  
-// What's actually there: "GET /users\u2009{\"type\":\"endpoint-metric\",\"metadata\":{\"method\":\"GET\",\"endpoint\":\"/users\"}}"
+// What you see: 
+// GET /users
+// {"type":"endpoint-metric","metadata":{"method":"GET","endpoint":"/users"}}
 ```
 
 **Two modes:**
-- **Development** (`encode: false`): Uses **Thin Space** (`\u2009`) - metadata is visible in console output
-- **Production** (`encode: true`): Uses **Zero-Width Space** (`\u200B`) - metadata is hidden from console output, base64 encoded and still available to log processors (tails)
+- **Development** (`encode: false`): Metadata appears as readable JSON on the next line
+- **Production** (`encode: true`): Metadata is base64 encoded and prefixed with zero-width space (`\u200B`) for identification
 
 ### Log Processing & Tail Workers
 
@@ -47,7 +48,7 @@ The same library can be used in log processors to extract the structured data:
 import { parseStructured, parseMeta } from 'strog';
 
 // Parse a log message that came through your system
-const incomingLog = "GET /users completed in 150ms\u2009{...metadata...}";
+const incomingLog = "GET /users completed in 150ms\n{...metadata...}";
 
 const parsed = parseStructured(incomingLog);
 console.log(parsed.raw);     // "GET /users completed in 150ms" (clean message)
@@ -89,13 +90,14 @@ const logMessage = EndpointMetric`${method} ${endpoint} time: ${time_ms}ms code:
 console.info(logMessage);
 
 /* Output in development:
- * GET /users time: 150ms code: 200\u2009{"method":"get","endpoint":"/users","time_ms":150,"status_code":200}
+ * GET /users time: 150ms code: 200
+ * {"type":"endpoint-metric","metadata":{"method":"GET","endpoint":"/users","time_ms":150,"status_code":200}}
  */
 
 /* Output in production:
- * GET /users/123 time: 150ms code: 200\u200B[hidden-base64-json-metadata]
- * or more simply:
- * GET /users/123 time: 150ms code: 200
+ * GET /users time: 150ms code: 200
+ * [zero-width-space]eyJhYmMiOi4uLn0=  (base64 encoded metadata)
+ */
 ```
 
 ## API Reference
@@ -196,8 +198,8 @@ import { StructuredTag } from 'strog';
 
 const isProduction = process.env.NODE_ENV === 'production';
 
-// In development: metadata visible as JSON
-// In production: metadata base64 encoded and hidden
+// In development: metadata visible as JSON on separate line
+// In production: metadata base64 encoded on separate line
 const ApiCall = StructuredTag('api-call', ['method', 'url', 'status'], isProduction);
 
 const logMessage = ApiCall`${method} ${url} returned ${status}`;
@@ -206,12 +208,12 @@ console.info(logMessage);
 
 ## Metadata Encoding
 
-Strog uses Unicode characters to separate log messages from metadata:
+Strog separates log messages from metadata using newlines:
 
-- **Thin Space (\\u2009)**: Visible metadata for development
-- **Zero-Width Space (\\u200B)**: Hidden, base64-encoded metadata for production
+- **Development mode**: Metadata appears as readable JSON on the next line
+- **Production mode**: Metadata is base64 encoded and prefixed with zero-width space (`\u200B`) for identification
 
-This approach ensures logs remain readable while enabling automated parsing.
+This approach ensures logs remain readable while enabling automated parsing by log processors.
 
 ## Framework Integration
 

src/index.ts

@@ -29,7 +29,7 @@ export function buildParsedMetadata(type: string, placeholders: any[], keys: str
 export function buildStringifiedMetadata(type: string, placeholders: any[], keys: string[], encode = false): string {
 	const parsed = buildParsedMetadata(type, placeholders, keys);
 	const stringified = JSON.stringify(parsed);
-	return encode ? `\u200B${btoa(stringified)}` : `\u2009${stringified}`;
+	return encode ? `\n\u200B${btoa(stringified)}` : `\n${stringified}`;
 }
 
 export function StructuredTag(type: string, keys: string[], encode = false) {
@@ -54,23 +54,18 @@ export function safeJsonParse<T>(json: string): T | void {
 
 export function parseStructured(structuredLogMessage: string): ParsedStructuredLog {
 	let decoded: string | undefined;
-	let raw: string;
-	
-	if (structuredLogMessage.includes('\u200B')) {
-		const parts = structuredLogMessage.split('\u200B');
-		raw = parts[0] || '';
-		const encoded = parts[1];
-		try {
-			decoded = encoded ? atob(encoded) : undefined;
-		} catch {
-			decoded = undefined;
-		}
-	} else if (structuredLogMessage.includes('\u2009')) {
-		const parts = structuredLogMessage.split('\u2009');
-		raw = parts[0] || '';
-		decoded = parts[1];
-	} else {
-		raw = structuredLogMessage;
+	//let raw: string;
+
+	const [ raw, encoded ] = structuredLogMessage.split('\n');
+
+	if ( encoded ) {
+		if ( encoded.startsWith('\u200B') ) {
+			try {
+				decoded = atob ( encoded.substring(1) );
+			} catch {
+				decoded = undefined;
+			}
+		} else decoded = encoded;
 	}
 
 	const parsed = decoded ? safeJsonParse<ParsedMetadata>(decoded) : undefined;

tests/index.test.ts

@@ -74,18 +74,18 @@ describe('buildParsedMetadata', () => {
 });
 
 describe('buildStringifiedMetadata', () => {
-	test('should stringify metadata with thin space', () => {
+	test('should stringify metadata with newline', () => {
 		const stringified = buildStringifiedMetadata('test-type', ['value1', 42], ['key1', 'key2'], false);
 		const expectedJson = JSON.stringify({ type: 'test-type', metadata: { key1: 'value1', key2: 42 } });
 
-		assert.equal(stringified, `\u2009${expectedJson}`);
+		assert.equal(stringified, `\n${expectedJson}`);
 	});
 
 	test('should stringify metadata with encoding', () => {
 		const stringified = buildStringifiedMetadata('test-type', ['value1'], ['key1'], true);
 		const expectedEncoded = btoa(JSON.stringify({ type: 'test-type', metadata: { key1: 'value1' } }));
 
-		assert.equal(stringified, `\u200B${expectedEncoded}`);
+		assert.equal(stringified, `\n\u200B${expectedEncoded}`);
 	});
 });
 
@@ -101,15 +101,15 @@ describe('StructuredTag', () => {
 		const expectedBase = 'GET /users/123 time: 150ms code: 200';
 
 		assert.ok(logMessage.startsWith(expectedBase));
-		assert.ok(logMessage.includes('\u2009'));
+		assert.ok(logMessage.includes('\n'));
 	});
 
 	test('should work with encoding', () => {
 		const EncodedMetric = StructuredTag('encoded-metric', ['key'], true);
 		const encodedMessage = EncodedMetric`Test: ${'test-value'}`;
 
 		assert.ok(encodedMessage.startsWith('Test: test-value'));
-		assert.ok(encodedMessage.includes('\u200B'));
+		assert.ok(encodedMessage.includes('\n\u200B'));
 	});
 });
 
@@ -130,8 +130,8 @@ describe('safeJsonParse', () => {
 });
 
 describe('parseStructured', () => {
-	test('should extract raw message and parse metadata from thin space format', () => {
-		const testMessage = 'Hello world\u2009{"type":"test","metadata":{"key":"value"}}';
+	test('should extract raw message and parse metadata from newline format', () => {
+		const testMessage = 'Hello world\n{"type":"test","metadata":{"key":"value"}}';
 		const parsed = parseStructured(testMessage);
 
 		assert.equal(parsed.raw, 'Hello world');
@@ -141,7 +141,7 @@ describe('parseStructured', () => {
 	test('should extract raw message and decode metadata from encoded format', () => {
 		const testMetadata = { type: 'test', metadata: { key: 'encoded' } };
 		const encoded = btoa(JSON.stringify(testMetadata));
-		const testMessage = `Hello encoded\u200B${encoded}`;
+		const testMessage = `Hello encoded\n\u200B${encoded}`;
 		const parsed = parseStructured(testMessage);
 
 		assert.equal(parsed.raw, 'Hello encoded');
@@ -157,7 +157,7 @@ describe('parseStructured', () => {
 	});
 
 	test('should handle malformed encoded data gracefully', () => {
-		const malformedEncoded = 'Test\u200Binvalid-base64!';
+		const malformedEncoded = 'Test\n\u200Binvalid-base64!';
 		const parsed = parseStructured(malformedEncoded);
 
 		assert.equal(parsed.raw, 'Test');
@@ -167,7 +167,7 @@ describe('parseStructured', () => {
 
 describe('parseMeta', () => {
 	test('should extract metadata', () => {
-		const testMessage = 'Hello world\u2009{"type":"test","metadata":{"key":"value"}}';
+		const testMessage = 'Hello world\n{"type":"test","metadata":{"key":"value"}}';
 		const meta = parseMeta(testMessage);
 
 		assert.deepEqual(meta, { type: 'test', metadata: { key: 'value' } });
@@ -183,7 +183,7 @@ describe('parseMeta', () => {
 
 describe('extractLog', () => {
 	test('should extract raw message', () => {
-		const testMessage = 'Hello world\u2009{"type":"test","metadata":{"key":"value"}}';
+		const testMessage = 'Hello world\n{"type":"test","metadata":{"key":"value"}}';
 		const log = extractLog(testMessage);
 
 		assert.equal(log, 'Hello world');