Feature/fetch (#54)

* relocated request.library to common folder

* add Tempo.epoch

* add shorthand to set, add, until, since

* ready for review

* PR 1st review

* tighten hh|mi|ss upper boundaries

Author: magmacomputing

CHANGELOG.md

@@ -28,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Ticker Plugin Licensing**: The `Ticker` plugin has transitioned to a licensed model. It remains completely free to use, but now requires validation via the Tempo Registry ecosystem.
 - **Robust License Validation**: Hardened runtime integrity for Tempo Pro plugins to enhance state security and prevent tampering.
 - **Edition Boundaries**: Added proactive runtime warnings for unlicensed attempts, establishing strict boundaries between the Community and Proprietary editions.
-- **Extension Resolution**: Stabilized module resolution for plugins by migrating to `defineExtension` and correcting internal export paths.
+- **Extension Resolution**: Stabilized module resolution for plugins by migrating to `definePlugin` and correcting internal export paths.
 - **Logging Subsystem Decoupling**: Fully decoupled the internal parsing and error boundaries from the legacy `Logify` architecture, enabling zero-cost trace instrumentation.
 - **Diagnostic Consistency**: Standardized fatal exceptions by introducing the `TempoError` class for internal invariant violations, and unified all console output through the centralized diagnostic bus (`logWarn`).
 - **Documentation**: Clarified API behavior for the Duration engine (especially `.since()` return types) and relative time math. Improved visibility and navigation for the Tempo License Registry and installation guides.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "private": true,
   "engines": {
     "node": ">=20.0.0"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/library",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Shared utility library for Tempo",
   "author": "Magma Computing Solutions",
   "license": "MIT",

packages/library/package.json

@@ -18,6 +18,7 @@ export * from './common/object.library.js';
 export * from './common/pledge.class.js';
 export * from './common/proxy.library.js';
 export * from './common/reflection.library.js';
+export * from './common/request.library.js';
 export * from './common/serialize.library.js';
 export * from './common/storage.library.js';
 export * from './common/string.library.js';

packages/library/src/common.index.ts

@@ -74,7 +74,10 @@ export const isDuration = (obj: unknown): obj is Temporal.Duration => isType<Tem
 export const isDurationLike = (obj: unknown): obj is Temporal.DurationLike | string | Temporal.Duration => isString(obj) || isDuration(obj) || (isObject(obj) && (
 	'years' in obj || 'months' in obj || 'weeks' in obj || 'days' in obj ||
 	'hours' in obj || 'minutes' in obj || 'seconds' in obj ||
-	'milliseconds' in obj || 'microseconds' in obj || 'nanoseconds' in obj
+	'milliseconds' in obj || 'microseconds' in obj || 'nanoseconds' in obj ||
+	'yy' in obj || 'mm' in obj || 'ww' in obj || 'dd' in obj ||
+	'hh' in obj || 'mi' in obj || 'ss' in obj ||
+	'ms' in obj || 'us' in obj || 'ns' in obj
 ));
 export const isZonedDateTimeLike = (obj: unknown): obj is Temporal.ZonedDateTimeLike | string | Temporal.ZonedDateTime => isString(obj) || isZonedDateTime(obj) || (isObject(obj) && (
 	'year' in obj || 'month' in obj || 'day' in obj || 'hour' in obj || 'minute' in obj || 'second' in obj ||

packages/library/src/common/assertion.library.ts

@@ -1,6 +1,6 @@
 import type { ValueOf } from '#library/type.library.js';
 
-const TWO_SECONDS = 2000;																	// default time-out for requests, in milliseconds
+const TWO_SECONDS = 2_000;																	// default time-out for requests, in milliseconds
 
 export const HTTP = {
 	Ok: 200,
@@ -25,8 +25,19 @@ type Config = {
 	/** response wrapper (eg.  "alert({hello:'there'})" */		prefix?: string;
 }
 
+export class HttpError extends Error {
+	constructor(
+		public status: number,
+		public statusText: string,
+		public body: any
+	) {
+		super(`${status}: ${statusText}`);
+		this.name = 'HttpError';
+	}
+}
+
 /** get data from a resource-url */
-export const httpRequest = <T>(url: string | URL, init = {} as RequestInit, config = {} as Config) => {
+export const fetchRequest = <T>(url: string | URL, init = {} as RequestInit, config = {} as Config) => {
 	const signallingInit = {
 		...init,
 		signal: init.signal
@@ -37,28 +48,38 @@ export const httpRequest = <T>(url: string | URL, init = {} as RequestInit, conf
 	return fetch(url, signallingInit)													// caller will handle the 'catch' if error
 		.then(async res => {
 			if (res.ok) {
+				const contentType = res.headers.get('Content-Type') || '';
+				const isJson = contentType.includes('application/json');
+
 				if (config.prefix) {
-					const text = await res.text();										// read raw text first
-					const json = text.startsWith(config.prefix)				// if it starts with the specified prefix
-						? text.substring(config.prefix.length).replace(/\);?$/, '')	// then strip the prefix AND any trailing closure
-						: text;
+					const rawPrefixText = await res.text();						// read raw text first
+					const json = rawPrefixText.startsWith(config.prefix)				// if it starts with the specified prefix
+						? rawPrefixText.substring(config.prefix.length).replace(/\);?$/, '')	// then strip the prefix AND any trailing closure
+						: rawPrefixText;
 
 					return JSON.parse(json) as T;											// parse the unwrapped string
 				}
 
-				const json = await res.json();											// default JSON parsing
-				return json as T;
+				return await (isJson
+					? res.json()																			// default JSON parsing
+					: res.text()) as T;
 			}
 
-			throw new Error(`${res.status}: ${res.statusText}`);	// fetch not successful
+			let errorBody: any = null;
+			try {
+				const errorText = await res.text();
+				try { errorBody = JSON.parse(errorText); } catch { errorBody = errorText; }
+			} catch { }
+
+			throw new HttpError(res.status, res.statusText, errorBody);	// fetch not successful
 		})
 }
 
 /**
  * get Response headers only (no data).  
  * useful for just checking that a URL exists  
  */
-export const headRequest = (url: string | URL) => {
+export const fetchHead = (url: string | URL) => {
 	const signal = AbortSignal.timeout(TWO_SECONDS);
 	const init = { method: METHOD.Head, signal }							// only interested in verifying that url responds
 
@@ -67,6 +88,6 @@ export const headRequest = (url: string | URL) => {
 			if (ok || status === HTTP.Forbidden)									// forbidden, but at least we know url responds
 				return { status, headers }
 
-			throw new Error(`${status}: ${statusText}`);					// fetch not successful
+			throw new HttpError(status, statusText, null);				// fetch not successful
 		})
 }

…es/library/src/server/request.library.ts …es/library/src/common/request.library.tspackages/library/src/server/request.library.ts renamed to packages/library/src/common/request.library.ts packages/library/src/server/request.library.ts renamed to packages/library/src/common/request.library.ts

@@ -177,6 +177,7 @@ export type OneKey<K extends keyof any, V, KK extends keyof any = K> =
 		{ [Q in keyof O]: O[Q] } : never
 	}[K]
 
+/** @deprecated natively supported by modern IDEs via hover verbosity. Slated for removal in v4.0.0 */
 export type Prettify<T> = { [K in keyof T]: T[K]; } & {}
 export type ParseInt<T> = T extends `${infer N extends number}` ? N : never
 export type Plural<T extends string> = `${T}s`;
@@ -402,15 +403,14 @@ export type Secure<T> = T extends Primitive | Function | Date | RegExp | Error |
 	? SecureObject<T>
 	: T
 export interface SecureArray<T> extends ReadonlyArray<Secure<T>> { }
-export type SecureObject<T> = { readonly [K in keyof T]: Secure<T[K]> };
+export type SecureObject<T> = { readonly [K in keyof T]: Secure<T[K]> }
 
 type LooseString = (string & {})
-type LooseSymbol = (symbol & {})
 type LooseProperty = (PropertyKey & {})
 
 // https://www.youtube.com/watch?v=lraHlXpuhKs&t=43s
 /** Loose union */
-export type LooseUnion<T extends string> = T | LooseString
+export type LooseUnion<T> = T | LooseString
 /** Loose property key */
 export type LooseKey<K extends PropertyKey = string> = K | LooseProperty
 // /** Loose auto-complete */

packages/library/src/common/type.library.ts

@@ -4,4 +4,3 @@
 
 export * from './server/auth.library.js';
 export * from './server/file.library.js';
-export * from './server/request.library.js';

packages/library/src/server.index.ts

@@ -0,0 +1,129 @@
+import { fetchRequest, fetchHead, HttpError } from '../../src/common/request.library.js';
+
+describe('request.library', () => {
+	const mockFetch = vi.fn();
+
+	beforeEach(() => {
+		globalThis.fetch = mockFetch;
+	});
+
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	describe('fetchRequest', () => {
+		it('should parse JSON when Content-Type is application/json', async () => {
+			const mockData = { message: 'hello' };
+			mockFetch.mockResolvedValueOnce({
+				ok: true,
+				headers: new Headers({ 'Content-Type': 'application/json; charset=utf-8' }),
+				json: async () => mockData
+			} as unknown as Response);
+
+			const result = await fetchRequest('https://example.com/api');
+			expect(result).toEqual(mockData);
+		});
+
+		it('should return raw text when Content-Type is not JSON', async () => {
+			const mockText = 'hello world';
+			mockFetch.mockResolvedValueOnce({
+				ok: true,
+				headers: new Headers({ 'Content-Type': 'text/plain' }),
+				text: async () => mockText
+			} as unknown as Response);
+
+			const result = await fetchRequest('https://example.com/text');
+			expect(result).toEqual(mockText);
+		});
+
+		it('should strip prefix if provided', async () => {
+			const prefix = ')]}\'\n';
+			const rawText = `${prefix}{"a":1}`;
+			mockFetch.mockResolvedValueOnce({
+				ok: true,
+				headers: new Headers({ 'Content-Type': 'application/json' }),
+				text: async () => rawText
+			} as unknown as Response);
+
+			const result = await fetchRequest('https://example.com/data', {}, { prefix });
+			expect(result).toEqual({ a: 1 });
+		});
+
+		it('should throw HttpError with JSON body on 400', async () => {
+			const errorBody = { error: 'Bad request' };
+			mockFetch.mockResolvedValueOnce({
+				ok: false,
+				status: 400,
+				statusText: 'Bad Request',
+				text: async () => JSON.stringify(errorBody)
+			} as unknown as Response);
+
+			try {
+				await fetchRequest('https://example.com/api');
+				expect.fail('Should have thrown HttpError');
+			} catch (err: any) {
+				expect(err).toBeInstanceOf(HttpError);
+				expect(err.status).toBe(400);
+				expect(err.statusText).toBe('Bad Request');
+				expect(err.body).toEqual(errorBody);
+			}
+		});
+
+		it('should throw HttpError with text body on 500 when JSON parsing fails', async () => {
+			const errorText = 'Internal Server Error Occurred';
+			mockFetch.mockResolvedValueOnce({
+				ok: false,
+				status: 500,
+				statusText: 'Server Error',
+				text: async () => errorText
+			} as unknown as Response);
+
+			try {
+				await fetchRequest('https://example.com/api');
+				expect.fail('Should have thrown HttpError');
+			} catch (err: any) {
+				expect(err).toBeInstanceOf(HttpError);
+				expect(err.status).toBe(500);
+				expect(err.body).toBe(errorText);
+			}
+		});
+	});
+
+	describe('fetchHead', () => {
+		it('should return status and headers on ok response', async () => {
+			const mockHeaders = new Headers({ 'Content-Length': '123' });
+			mockFetch.mockResolvedValueOnce({
+				ok: true,
+				status: 200,
+				headers: mockHeaders
+			} as unknown as Response);
+
+			const result = await fetchHead('https://example.com/api');
+			expect(result.status).toBe(200);
+			expect(result.headers).toBe(mockHeaders);
+		});
+
+		it('should throw Error on non-ok response (except Forbidden)', async () => {
+			mockFetch.mockResolvedValueOnce({
+				ok: false,
+				status: 404,
+				statusText: 'Not Found'
+			} as unknown as Response);
+
+			await expect(fetchHead('https://example.com/api')).rejects.toThrow('404: Not Found');
+		});
+
+		it('should return status and headers on Forbidden (403)', async () => {
+			const mockHeaders = new Headers();
+			mockFetch.mockResolvedValueOnce({
+				ok: false,
+				status: 403,
+				headers: mockHeaders
+			} as unknown as Response);
+
+			const result = await fetchHead('https://example.com/api');
+			expect(result.status).toBe(403);
+			expect(result.headers).toBe(mockHeaders);
+		});
+	});
+});