@contentrain/query 5.0.1 → 5.1.0

package/README.md

@@ -173,9 +173,61 @@ Public root exports:
 - `SingletonAccessor`
 - `DictionaryAccessor`
 - `DocumentQuery`
-- `createContentrainClient`
+- `createContentrainClient` — local generated client loader
+- `createContentrain` — CDN client factory
+- `ContentrainError` — HTTP error class for CDN mode
 
-## 🧩 CommonJS Usage
+## CDN Transport
+
+For apps that fetch content from Contentrain Studio CDN (SSR, serverless, mobile):
+
+```ts
+import { createContentrain } from '@contentrain/query/cdn'
+
+const client = createContentrain({
+  projectId: '350696e8-...',
+  apiKey: 'crn_live_xxx',
+  // baseUrl: 'https://studio.contentrain.io/api/cdn/v1'  (default)
+})
+
+// All CDN queries are async
+const posts = await client.collection('faq').locale('en').all()
+const hero  = await client.singleton('hero').locale('en').get()
+const t     = await client.dictionary('ui').locale('en').get()
+const doc   = await client.document('docs').locale('en').bySlug('intro')
+```
+
+CDN collection queries support extended operators:
+
+```ts
+const filtered = await client.collection('faq')
+  .locale('en')
+  .where('order', 'gt', 5)
+  .where('category', 'in', ['general', 'billing'])
+  .sort('order', 'desc')
+  .limit(10)
+  .all()
+```
+
+CDN also exposes metadata endpoints:
+
+```ts
+const manifest = await client.manifest()
+const models   = await client.models()
+const model    = await client.model('faq')
+```
+
+### CDN vs Local
+
+| Aspect | Local (`#contentrain`) | CDN (`createContentrain()`) |
+|--------|----------------------|---------------------------|
+| Data source | Bundled `.mjs` files | HTTP fetch from CDN |
+| Return type | Sync (`T[]`) | Async (`Promise<T[]>`) |
+| Auth | None | API key required |
+| Caching | In-memory (embedded) | ETag-based HTTP cache |
+| Use case | SSG, build-time | SSR, client-side, serverless |
+
+## CommonJS Usage
 
 Generated clients support CommonJS through `init()`:
 
@@ -210,11 +262,15 @@ npx contentrain-query generate --root /path/to/project
 
 Main package:
 
-- `@contentrain/query`
+- `@contentrain/query` — runtime classes + `createContentrain()` CDN factory
 
 Generator entry:
 
-- `@contentrain/query/generate`
+- `@contentrain/query/generate` — programmatic generation API
+
+CDN transport:
+
+- `@contentrain/query/cdn` — CDN client with `HttpTransport`, async query classes
 
 ## 🧠 Design Constraints
 

package/dist/cdn/index.cjs

@@ -0,0 +1,9 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cdn = require("../cdn-C8uXJe3A.cjs");
+exports.CdnCollectionQuery = require_cdn.CdnCollectionQuery;
+exports.CdnDictionaryAccessor = require_cdn.CdnDictionaryAccessor;
+exports.CdnDocumentQuery = require_cdn.CdnDocumentQuery;
+exports.CdnSingletonAccessor = require_cdn.CdnSingletonAccessor;
+exports.ContentrainError = require_cdn.ContentrainError;
+exports.HttpTransport = require_cdn.HttpTransport;
+exports.createContentrain = require_cdn.createContentrain;

package/dist/cdn/index.d.cts

@@ -0,0 +1,2 @@
+import { a as CdnDocumentQuery, c as CdnCollectionQuery, d as DictionaryDataSource, f as DocumentDataSource, i as ContentrainError, l as HttpTransport, n as ContentrainCDNConfig, o as CdnDictionaryAccessor, p as SingletonDataSource, r as createContentrain, s as CdnSingletonAccessor, t as ContentrainCDNClient, u as CollectionDataSource } from "../index-Xjd0isXU.cjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, DictionaryDataSource, DocumentDataSource, HttpTransport, SingletonDataSource, createContentrain };

package/dist/cdn/index.d.mts

@@ -0,0 +1,2 @@
+import { a as CdnDocumentQuery, c as CdnCollectionQuery, d as DictionaryDataSource, f as DocumentDataSource, i as ContentrainError, l as HttpTransport, n as ContentrainCDNConfig, o as CdnDictionaryAccessor, p as SingletonDataSource, r as createContentrain, s as CdnSingletonAccessor, t as ContentrainCDNClient, u as CollectionDataSource } from "../index-D5zB3y75.mjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, CollectionDataSource, ContentrainCDNClient, ContentrainCDNConfig, ContentrainError, DictionaryDataSource, DocumentDataSource, HttpTransport, SingletonDataSource, createContentrain };

package/dist/cdn/index.mjs

@@ -0,0 +1,2 @@
+import { a as CdnCollectionQuery, i as CdnSingletonAccessor, n as CdnDocumentQuery, o as HttpTransport, r as CdnDictionaryAccessor, s as ContentrainError, t as createContentrain } from "../cdn-D66-Npqt.mjs";
+export { CdnCollectionQuery, CdnDictionaryAccessor, CdnDocumentQuery, CdnSingletonAccessor, ContentrainError, HttpTransport, createContentrain };

package/dist/cdn-C8uXJe3A.cjs

@@ -0,0 +1,351 @@
+//#region src/cdn/errors.ts
+var ContentrainError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "ContentrainError";
+	}
+};
+//#endregion
+//#region src/cdn/http-transport.ts
+var HttpTransport = class {
+	_baseUrl;
+	_projectId;
+	_apiKey;
+	_cache = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this._baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this._projectId = config.projectId;
+		this._apiKey = config.apiKey;
+	}
+	async fetch(path) {
+		const url = `${this._baseUrl}/${this._projectId}/${path}`;
+		const cached = this._cache.get(path);
+		const headers = { "Authorization": `Bearer ${this._apiKey}` };
+		if (cached?.etag) headers["If-None-Match"] = cached.etag;
+		const res = await globalThis.fetch(url, { headers });
+		if (res.status === 304 && cached) return cached.data;
+		if (!res.ok) throw new ContentrainError(res.status, await res.text());
+		const data = await res.json();
+		const etag = res.headers.get("etag") ?? "";
+		if (etag) this._cache.set(path, {
+			data,
+			etag
+		});
+		return data;
+	}
+	collection(modelId) {
+		return {
+			getAll: async (locale) => {
+				const map = await this.fetch(`content/${modelId}/${locale}.json`);
+				return Object.entries(map).map(([id, entry]) => Object.assign({ id }, entry));
+			},
+			getOne: async (id, locale) => {
+				const entry = (await this.fetch(`content/${modelId}/${locale}.json`))[id];
+				return entry ? {
+					id,
+					...entry
+				} : null;
+			}
+		};
+	}
+	singleton(modelId) {
+		return { get: (locale) => this.fetch(`content/${modelId}/${locale}.json`) };
+	}
+	dictionary(modelId) {
+		return { get: (locale) => this.fetch(`content/${modelId}/${locale}.json`) };
+	}
+	document(modelId) {
+		return {
+			getIndex: (locale) => this.fetch(`documents/${modelId}/_index/${locale}.json`),
+			getBySlug: (slug, locale) => this.fetch(`documents/${modelId}/${slug}/${locale}.json`)
+		};
+	}
+};
+//#endregion
+//#region src/cdn/collection-query.ts
+var CdnCollectionQuery = class {
+	_transport;
+	_source;
+	_modelId;
+	_locale = "en";
+	_filters = [];
+	_sortField = null;
+	_sortOrder = "asc";
+	_limit = null;
+	_offset = 0;
+	_includes = [];
+	constructor(transport, modelId, defaultLocale) {
+		this._transport = transport;
+		this._source = transport.collection(modelId);
+		this._modelId = modelId;
+		if (defaultLocale) this._locale = defaultLocale;
+	}
+	locale(lang) {
+		this._locale = lang;
+		return this;
+	}
+	where(field, op, value) {
+		this._filters.push({
+			field,
+			op,
+			value
+		});
+		return this;
+	}
+	sort(field, order = "asc") {
+		this._sortField = field;
+		this._sortOrder = order;
+		return this;
+	}
+	limit(n) {
+		this._limit = n;
+		return this;
+	}
+	offset(n) {
+		this._offset = n;
+		return this;
+	}
+	include(...fields) {
+		this._includes.push(...fields);
+		return this;
+	}
+	async all() {
+		let items = await this._source.getAll(this._locale);
+		for (const clause of this._filters) items = items.filter((item) => applyWhere$1(item, clause));
+		if (this._sortField) {
+			const field = this._sortField;
+			const dir = this._sortOrder === "asc" ? 1 : -1;
+			items = items.toSorted((a, b) => {
+				const va = a[field];
+				const vb = b[field];
+				if (va == null && vb == null) return 0;
+				if (va == null) return dir;
+				if (vb == null) return -dir;
+				if (va < vb) return -dir;
+				if (va > vb) return dir;
+				return 0;
+			});
+		}
+		if (this._offset > 0 || this._limit !== null) {
+			const end = this._limit !== null ? this._offset + this._limit : void 0;
+			items = items.slice(this._offset, end);
+		}
+		if (this._includes.length > 0) items = await this._resolveIncludes(items);
+		return items;
+	}
+	async first() {
+		return (await this.all())[0];
+	}
+	async _resolveIncludes(items) {
+		const cache = /* @__PURE__ */ new Map();
+		for (const field of this._includes) for (const item of items) {
+			const val = item[field];
+			const ids = Array.isArray(val) ? val : val ? [val] : [];
+			for (const id of ids) {
+				if (typeof id !== "string") continue;
+				if (!cache.has(field)) {
+					try {
+						const related = await this._transport.fetch(`content/${field}/${this._locale}.json`);
+						const map = /* @__PURE__ */ new Map();
+						for (const [entryId, entry] of Object.entries(related)) map.set(entryId, {
+							id: entryId,
+							...entry
+						});
+						cache.set(field, map);
+					} catch {
+						cache.set(field, /* @__PURE__ */ new Map());
+					}
+					break;
+				}
+			}
+		}
+		return items.map((item) => {
+			const resolved = { ...item };
+			const dst = resolved;
+			for (const field of this._includes) {
+				const related = cache.get(field);
+				if (!related) continue;
+				const val = item[field];
+				if (Array.isArray(val)) dst[field] = val.map((id) => typeof id === "string" ? related.get(id) ?? id : id);
+				else if (typeof val === "string") dst[field] = related.get(val) ?? val;
+			}
+			return resolved;
+		});
+	}
+};
+function applyWhere$1(item, clause) {
+	const val = item[clause.field];
+	switch (clause.op) {
+		case "eq": return val === clause.value;
+		case "ne": return val !== clause.value;
+		case "gt": return val > clause.value;
+		case "gte": return val >= clause.value;
+		case "lt": return val < clause.value;
+		case "lte": return val <= clause.value;
+		case "in": return Array.isArray(clause.value) && clause.value.includes(val);
+		case "contains":
+			if (typeof val === "string") return val.includes(clause.value);
+			if (Array.isArray(val)) return val.includes(clause.value);
+			return false;
+		default: return true;
+	}
+}
+//#endregion
+//#region src/cdn/singleton-accessor.ts
+var CdnSingletonAccessor = class {
+	_source;
+	_locale = "en";
+	constructor(source, defaultLocale) {
+		this._source = source;
+		if (defaultLocale) this._locale = defaultLocale;
+	}
+	locale(lang) {
+		this._locale = lang;
+		return this;
+	}
+	async get() {
+		return this._source.get(this._locale);
+	}
+};
+//#endregion
+//#region src/cdn/dictionary-accessor.ts
+var CdnDictionaryAccessor = class {
+	_source;
+	_locale = "en";
+	constructor(source, defaultLocale) {
+		this._source = source;
+		if (defaultLocale) this._locale = defaultLocale;
+	}
+	locale(lang) {
+		this._locale = lang;
+		return this;
+	}
+	async get(key, params) {
+		const dict = await this._source.get(this._locale);
+		if (key === void 0) return dict;
+		const value = dict[key];
+		if (value === void 0) return void 0;
+		if (params) return interpolate(value, params);
+		return value;
+	}
+};
+function interpolate(template, params) {
+	return template.replace(/\{(\w+)\}/g, (match, key) => {
+		const val = params[key];
+		return val !== void 0 ? String(val) : match;
+	});
+}
+//#endregion
+//#region src/cdn/document-query.ts
+var CdnDocumentQuery = class {
+	_source;
+	_locale = "en";
+	_filters = [];
+	constructor(source, defaultLocale) {
+		this._source = source;
+		if (defaultLocale) this._locale = defaultLocale;
+	}
+	locale(lang) {
+		this._locale = lang;
+		return this;
+	}
+	where(field, op, value) {
+		this._filters.push({
+			field,
+			op,
+			value
+		});
+		return this;
+	}
+	async all() {
+		let items = await this._source.getIndex(this._locale);
+		for (const clause of this._filters) items = items.filter((item) => applyWhere(item, clause));
+		return items;
+	}
+	async first() {
+		return (await this.all())[0];
+	}
+	async bySlug(slug) {
+		return this._source.getBySlug(slug, this._locale);
+	}
+};
+function applyWhere(item, clause) {
+	const val = item[clause.field];
+	switch (clause.op) {
+		case "eq": return val === clause.value;
+		case "ne": return val !== clause.value;
+		case "gt": return val > clause.value;
+		case "gte": return val >= clause.value;
+		case "lt": return val < clause.value;
+		case "lte": return val <= clause.value;
+		case "in": return Array.isArray(clause.value) && clause.value.includes(val);
+		case "contains":
+			if (typeof val === "string") return val.includes(clause.value);
+			if (Array.isArray(val)) return val.includes(clause.value);
+			return false;
+		default: return true;
+	}
+}
+//#endregion
+//#region src/cdn/index.ts
+function createContentrain(config) {
+	const transport = new HttpTransport({
+		baseUrl: config.baseUrl ?? "https://studio.contentrain.io/api/cdn/v1",
+		projectId: config.projectId,
+		apiKey: config.apiKey
+	});
+	const defaultLocale = config.defaultLocale;
+	return {
+		collection: (modelId) => new CdnCollectionQuery(transport, modelId, defaultLocale),
+		singleton: (modelId) => new CdnSingletonAccessor(transport.singleton(modelId), defaultLocale),
+		dictionary: (modelId) => new CdnDictionaryAccessor(transport.dictionary(modelId), defaultLocale),
+		document: (modelId) => new CdnDocumentQuery(transport.document(modelId), defaultLocale),
+		manifest: () => transport.fetch("_manifest.json"),
+		models: () => transport.fetch("models/_index.json"),
+		model: (id) => transport.fetch(`models/${id}.json`)
+	};
+}
+//#endregion
+Object.defineProperty(exports, "CdnCollectionQuery", {
+	enumerable: true,
+	get: function() {
+		return CdnCollectionQuery;
+	}
+});
+Object.defineProperty(exports, "CdnDictionaryAccessor", {
+	enumerable: true,
+	get: function() {
+		return CdnDictionaryAccessor;
+	}
+});
+Object.defineProperty(exports, "CdnDocumentQuery", {
+	enumerable: true,
+	get: function() {
+		return CdnDocumentQuery;
+	}
+});
+Object.defineProperty(exports, "CdnSingletonAccessor", {
+	enumerable: true,
+	get: function() {
+		return CdnSingletonAccessor;
+	}
+});
+Object.defineProperty(exports, "ContentrainError", {
+	enumerable: true,
+	get: function() {
+		return ContentrainError;
+	}
+});
+Object.defineProperty(exports, "HttpTransport", {
+	enumerable: true,
+	get: function() {
+		return HttpTransport;
+	}
+});
+Object.defineProperty(exports, "createContentrain", {
+	enumerable: true,
+	get: function() {
+		return createContentrain;
+	}
+});