@stone-js/resources 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Stone Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# Stone.js · Resources
+
+[![npm](https://img.shields.io/npm/v/@stone-js/resources)](https://www.npmjs.com/package/@stone-js/resources)
+[![CI](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/stone-foundation/stone-js-framework/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=stone-foundation_stone-js-framework&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stone-foundation_stone-js-framework)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+
+> Framework-agnostic API resources for Stone.js. Shape what your domain exposes — sparse fieldsets, conditional fields, includes and envelopes — decoupled from controllers, the same on backend and frontend.
+
+Part of **[Stone.js](https://stonejs.dev)**, the reference implementation of the
+[Continuum Architecture](https://evens-stone.github.io/continuum-manifesto/manifesto): write your
+domain once, and the context (runtime, protocol, caller) applies to it at run time.
+
+## Install
+
+```bash
+npm i @stone-js/resources
+```
+
+## Usage
+
+```ts
+import { defineResource, only } from '@stone-js/resources'
+
+// Shape what your domain exposes: hide internals, support sparse fieldsets.
+export const TaskResource = defineResource((task) => ({
+  id: task.id,
+  title: task.title,
+  createdAt: task.createdAt
+}))
+
+// only(...) / except(...) drive sparse fieldsets from the request.
+```
+
+## Documentation
+
+Full documentation: **[stonejs.dev/docs/extensions/resources](https://stonejs.dev/docs/extensions/resources)**.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT) © Evens Pierre ("Mr. Stone") and the Stone.js contributors.

package/dist/Resource.d.ts

@@ -0,0 +1,75 @@
+import { IResource, ResourceContext, ResourceEnvelope, ResourceOutput } from './declarations';
+/**
+ * Base API resource — the declarative way to shape what your domain exposes.
+ *
+ * Extend it and implement {@link Resource.toArray} to map a model to its public shape. Everything
+ * else (sparse fieldsets, dropping conditional fields, collections, envelopes) is handled for you.
+ * A resource is decoupled from controllers and platform-agnostic: the same resource shapes data on
+ * the backend and on the frontend.
+ *
+ * @example
+ * ```ts
+ * class UserResource extends Resource<User> {
+ *   toArray (user: User, ctx: ResourceContext) {
+ *     return {
+ *       id: user.id,
+ *       name: user.name,
+ *       email: this.when(ctx.self === true, user.email),
+ *       posts: this.whenIncluded(ctx, 'posts', () => postResource.collection(user.posts))
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Resource<Model = unknown, Output extends ResourceOutput = ResourceOutput> implements IResource<Model, Output> {
+    /**
+     * Map a model to its public shape (before field filtering).
+     *
+     * @param model - The domain model.
+     * @param context - The resource context.
+     * @returns The public shape.
+     */
+    abstract toArray(model: Model, context: ResourceContext): Output;
+    /**
+     * Transform one model, applying the requested sparse fieldset and dropping undefined fields.
+     *
+     * @param model - The domain model.
+     * @param context - The resource context.
+     * @returns The filtered public shape.
+     */
+    item(model: Model, context?: ResourceContext): Partial<Output>;
+    /**
+     * Transform a collection of models.
+     *
+     * @param models - The domain models.
+     * @param context - The resource context.
+     * @returns The transformed collection.
+     */
+    collection(models: Model[], context?: ResourceContext): Array<Partial<Output>>;
+    /**
+     * Wrap a model or a collection in a `{ data, meta }` envelope.
+     *
+     * @param models - A model or a collection.
+     * @param context - The resource context.
+     * @param meta - Optional metadata (pagination, counts, …).
+     * @returns The envelope.
+     */
+    response(models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>): ResourceEnvelope<Partial<Output> | Array<Partial<Output>>>;
+    /**
+     * Include a value only when `condition` is truthy (otherwise the field is dropped).
+     *
+     * @param condition - Whether to include the value.
+     * @param value - The value, or a lazy factory (only evaluated when included).
+     * @returns The value, or `undefined`.
+     */
+    protected when<T>(condition: boolean, value: T | (() => T)): T | undefined;
+    /**
+     * Include a value only when the relation was requested via `context.include`.
+     *
+     * @param context - The resource context.
+     * @param name - The relation name.
+     * @param value - The value, or a lazy factory (only evaluated when included).
+     * @returns The value, or `undefined`.
+     */
+    protected whenIncluded<T>(context: ResourceContext, name: string, value: T | (() => T)): T | undefined;
+}

package/dist/declarations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The context that shapes a transformation: which fields the client asked for, which relations to
+ * include, and any extra data (the current user, the event, …) a resource may consult.
+ *
+ * It is intentionally open so resources can read whatever they need while staying agnostic.
+ */
+export interface ResourceContext {
+    /** Requested sparse fieldset — when set, the output is limited to these top-level keys. */
+    fields?: string[];
+    /** Requested relations to embed. */
+    include?: string[];
+    /** Anything else a resource needs (e.g. the authenticated principal). */
+    [key: string]: unknown;
+}
+/** A plain, serialisable output object. */
+export type ResourceOutput = Record<string, unknown>;
+/**
+ * A `{ data, meta }` envelope around a transformed item or collection.
+ */
+export interface ResourceEnvelope<T> {
+    data: T;
+    meta?: Record<string, unknown>;
+}
+/**
+ * The resource contract: transform a model (or a collection) into its public representation.
+ */
+export interface IResource<Model = unknown, Output extends ResourceOutput = ResourceOutput> {
+    /** Transform one model into its public shape (before field filtering). */
+    toArray: (model: Model, context: ResourceContext) => Output;
+    /** Transform one model, applying sparse fieldsets and dropping undefined fields. */
+    item: (model: Model, context?: ResourceContext) => Partial<Output>;
+    /** Transform a collection. */
+    collection: (models: Model[], context?: ResourceContext) => Array<Partial<Output>>;
+    /** Wrap a model or collection in a `{ data, meta }` envelope. */
+    response: (models: Model | Model[], context?: ResourceContext, meta?: Record<string, unknown>) => ResourceEnvelope<Partial<Output> | Array<Partial<Output>>>;
+}

package/dist/defineResource.d.ts

@@ -0,0 +1,17 @@
+import { Resource } from './Resource';
+import { ResourceContext, ResourceOutput } from './declarations';
+/**
+ * The imperative/functional way to define a resource — a plain transform function instead of a
+ * class. Returns a full {@link Resource} (so you still get `item`/`collection`/`response` and
+ * sparse fieldsets for free).
+ *
+ * @param transform - Maps a model to its public shape.
+ * @returns A resource.
+ *
+ * @example
+ * ```ts
+ * const userResource = defineResource<User>((user) => ({ id: user.id, name: user.name }))
+ * userResource.collection(users, { fields: ['id'] })
+ * ```
+ */
+export declare function defineResource<Model = unknown, Output extends ResourceOutput = ResourceOutput>(transform: (model: Model, context: ResourceContext) => Output): Resource<Model, Output>;

package/dist/helpers.d.ts

@@ -0,0 +1,44 @@
+import { ResourceContext, ResourceOutput } from './declarations';
+/**
+ * Returns a copy of `object` without any `undefined` values (so conditional fields simply vanish).
+ *
+ * @param object - The object to clean.
+ * @returns A copy without undefined values.
+ */
+export declare function stripUndefined<T extends ResourceOutput>(object: T): Partial<T>;
+/**
+ * Keeps only the given keys of an object (ignoring keys that are absent).
+ *
+ * @param object - The source object.
+ * @param keys - The keys to keep.
+ * @returns A new object with only those keys.
+ */
+export declare function only<T extends ResourceOutput>(object: T, keys: string[]): Partial<T>;
+/**
+ * Returns a copy of an object without the given keys.
+ *
+ * @param object - The source object.
+ * @param keys - The keys to drop.
+ * @returns A new object without those keys.
+ */
+export declare function except<T extends ResourceOutput>(object: T, keys: string[]): Partial<T>;
+/**
+ * Applies a sparse fieldset to an output: strips undefined, then narrows to the requested fields
+ * (when any were requested).
+ *
+ * @param output - The transformed output.
+ * @param fields - The requested fields (optional).
+ * @returns The filtered output.
+ */
+export declare function applyFields<T extends ResourceOutput>(output: T, fields?: string[]): Partial<T>;
+/**
+ * Builds a {@link ResourceContext} from an incoming event's `fields` and `include` query
+ * parameters (comma-separated). Agnostic: the event only needs a `get(key)` method.
+ *
+ * @param event - Anything with `get(key)` (an `IncomingHttpEvent`, a URL search wrapper, …).
+ * @param extra - Extra context to merge in.
+ * @returns The resource context.
+ */
+export declare function contextFromEvent(event: {
+    get: <T>(key: string, fallback?: T) => T;
+}, extra?: ResourceContext): ResourceContext;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Resource';
+export * from './declarations';
+export * from './defineResource';
+export * from './helpers';

package/dist/index.js

@@ -0,0 +1,191 @@
+/**
+ * Returns a copy of `object` without any `undefined` values (so conditional fields simply vanish).
+ *
+ * @param object - The object to clean.
+ * @returns A copy without undefined values.
+ */
+function stripUndefined(object) {
+    const out = {};
+    for (const key of Object.keys(object)) {
+        if (object[key] !== undefined) {
+            out[key] = object[key];
+        }
+    }
+    return out;
+}
+/**
+ * Keeps only the given keys of an object (ignoring keys that are absent).
+ *
+ * @param object - The source object.
+ * @param keys - The keys to keep.
+ * @returns A new object with only those keys.
+ */
+function only(object, keys) {
+    const set = new Set(keys);
+    const out = {};
+    for (const key of Object.keys(object)) {
+        if (set.has(key)) {
+            out[key] = object[key];
+        }
+    }
+    return out;
+}
+/**
+ * Returns a copy of an object without the given keys.
+ *
+ * @param object - The source object.
+ * @param keys - The keys to drop.
+ * @returns A new object without those keys.
+ */
+function except(object, keys) {
+    const set = new Set(keys);
+    const out = {};
+    for (const key of Object.keys(object)) {
+        if (!set.has(key)) {
+            out[key] = object[key];
+        }
+    }
+    return out;
+}
+/**
+ * Applies a sparse fieldset to an output: strips undefined, then narrows to the requested fields
+ * (when any were requested).
+ *
+ * @param output - The transformed output.
+ * @param fields - The requested fields (optional).
+ * @returns The filtered output.
+ */
+function applyFields(output, fields) {
+    const clean = stripUndefined(output);
+    return fields !== undefined && fields.length > 0 ? only(clean, fields) : clean;
+}
+/**
+ * Builds a {@link ResourceContext} from an incoming event's `fields` and `include` query
+ * parameters (comma-separated). Agnostic: the event only needs a `get(key)` method.
+ *
+ * @param event - Anything with `get(key)` (an `IncomingHttpEvent`, a URL search wrapper, …).
+ * @param extra - Extra context to merge in.
+ * @returns The resource context.
+ */
+function contextFromEvent(event, extra = {}) {
+    return {
+        ...extra,
+        fields: splitCsv(event.get('fields', '')),
+        include: splitCsv(event.get('include', ''))
+    };
+}
+/**
+ * Splits a comma-separated string into a trimmed, non-empty list (or `undefined` when empty).
+ *
+ * @param value - The CSV string.
+ * @returns The list, or `undefined`.
+ */
+function splitCsv(value) {
+    const parts = value.split(',').map((part) => part.trim()).filter((part) => part.length > 0);
+    return parts.length > 0 ? parts : undefined;
+}
+
+/**
+ * Base API resource — the declarative way to shape what your domain exposes.
+ *
+ * Extend it and implement {@link Resource.toArray} to map a model to its public shape. Everything
+ * else (sparse fieldsets, dropping conditional fields, collections, envelopes) is handled for you.
+ * A resource is decoupled from controllers and platform-agnostic: the same resource shapes data on
+ * the backend and on the frontend.
+ *
+ * @example
+ * ```ts
+ * class UserResource extends Resource<User> {
+ *   toArray (user: User, ctx: ResourceContext) {
+ *     return {
+ *       id: user.id,
+ *       name: user.name,
+ *       email: this.when(ctx.self === true, user.email),
+ *       posts: this.whenIncluded(ctx, 'posts', () => postResource.collection(user.posts))
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class Resource {
+    /**
+     * Transform one model, applying the requested sparse fieldset and dropping undefined fields.
+     *
+     * @param model - The domain model.
+     * @param context - The resource context.
+     * @returns The filtered public shape.
+     */
+    item(model, context = {}) {
+        return applyFields(this.toArray(model, context), context.fields);
+    }
+    /**
+     * Transform a collection of models.
+     *
+     * @param models - The domain models.
+     * @param context - The resource context.
+     * @returns The transformed collection.
+     */
+    collection(models, context = {}) {
+        return models.map((model) => this.item(model, context));
+    }
+    /**
+     * Wrap a model or a collection in a `{ data, meta }` envelope.
+     *
+     * @param models - A model or a collection.
+     * @param context - The resource context.
+     * @param meta - Optional metadata (pagination, counts, …).
+     * @returns The envelope.
+     */
+    response(models, context = {}, meta) {
+        const data = Array.isArray(models) ? this.collection(models, context) : this.item(models, context);
+        return meta === undefined ? { data } : { data, meta };
+    }
+    /**
+     * Include a value only when `condition` is truthy (otherwise the field is dropped).
+     *
+     * @param condition - Whether to include the value.
+     * @param value - The value, or a lazy factory (only evaluated when included).
+     * @returns The value, or `undefined`.
+     */
+    when(condition, value) {
+        if (!condition) {
+            return undefined;
+        }
+        return typeof value === 'function' ? value() : value;
+    }
+    /**
+     * Include a value only when the relation was requested via `context.include`.
+     *
+     * @param context - The resource context.
+     * @param name - The relation name.
+     * @param value - The value, or a lazy factory (only evaluated when included).
+     * @returns The value, or `undefined`.
+     */
+    whenIncluded(context, name, value) {
+        return this.when(context.include?.includes(name) === true, value);
+    }
+}
+
+/**
+ * The imperative/functional way to define a resource — a plain transform function instead of a
+ * class. Returns a full {@link Resource} (so you still get `item`/`collection`/`response` and
+ * sparse fieldsets for free).
+ *
+ * @param transform - Maps a model to its public shape.
+ * @returns A resource.
+ *
+ * @example
+ * ```ts
+ * const userResource = defineResource<User>((user) => ({ id: user.id, name: user.name }))
+ * userResource.collection(users, { fields: ['id'] })
+ * ```
+ */
+function defineResource(transform) {
+    return new class extends Resource {
+        toArray(model, context) {
+            return transform(model, context);
+        }
+    }();
+}
+
+export { Resource, applyFields, contextFromEvent, defineResource, except, only, stripUndefined };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@stone-js/resources",
+  "version": "0.8.0",
+  "description": "Framework-agnostic API resources for Stone.js. Shape what your domain exposes — sparse fieldsets, conditional fields, includes and envelopes — decoupled from controllers, the same on backend and frontend.",
+  "author": "Mr. Stone <evensstone@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stone-foundation/stone-js-framework.git",
+    "directory": "stone-js-resources"
+  },
+  "homepage": "https://stonejs.dev",
+  "bugs": {
+    "url": "https://github.com/stone-foundation/stone-js-framework/issues"
+  },
+  "keywords": [
+    "StoneJS",
+    "resources",
+    "transformer",
+    "serializer",
+    "api",
+    "fieldsets",
+    "presenter",
+    "isomorphic"
+  ],
+  "files": [
+    "/dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-multi-entry": "^6.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@types/node": "^24.0.7",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.44.1",
+    "rollup-plugin-node-externals": "^8.0.1",
+    "ts-standard": "^12.0.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.28.6",
+    "typedoc-plugin-markdown": "^4.7.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "ts-standard": {
+    "globals": [
+      "it",
+      "test",
+      "vi",
+      "expect",
+      "describe",
+      "beforeEach"
+    ]
+  },
+  "scripts": {
+    "lint": "ts-standard src",
+    "lint:fix": "ts-standard --fix src tests",
+    "predoc": "rimraf docs",
+    "doc": "typedoc",
+    "clean": "rimraf dist",
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:cvg": "npm run test -- --coverage",
+    "test:text": "npm run test:cvg -- --coverage.reporter=text",
+    "test:html": "npm run test:cvg -- --coverage.reporter=html",
+    "test:clover": "npm run test:cvg -- --coverage.reporter=clover"
+  }
+}