resora 0.1.10 → 0.2.0

package/README.md

@@ -2,13 +2,13 @@
 
 [![NPM Downloads](https://img.shields.io/npm/dt/resora.svg)](https://www.npmjs.com/package/resora)
 [![npm version](https://img.shields.io/npm/v/resora.svg)](https://www.npmjs.com/package/resora)
-[![License](https://img.shields.io/npm/l/resora.svg)](https://github.com/toneflix/resora/blob/main/LICENSE)
-[![CI](https://github.com/toneflix/resora/actions/workflows/ci.yml/badge.svg)](https://github.com/toneflix/resora/actions/workflows/ci.yml)
-[![Deploy Docs](https://github.com/toneflix/resora/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/toneflix/resora/actions/workflows/deploy-docs.yml)
+[![License](https://img.shields.io/npm/l/resora.svg)](https://github.com/arcstack-hq/resora/blob/main/LICENSE)
+[![CI](https://github.com/arcstack-hq/resora/actions/workflows/ci.yml/badge.svg)](https://github.com/arcstack-hq/resora/actions/workflows/ci.yml)
+[![Deploy Docs](https://github.com/arcstack-hq/resora/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/arcstack-hq/resora/actions/workflows/deploy-docs.yml)
 
 Resora is a structured API response layer for Node.js and TypeScript backends.
 
-It provides a clean, explicit way to transform data into consistent JSON responses and automatically send them to the client. Resora supports single resources, collections, and pagination metadata while remaining framework-agnostic and strongly typed.
+It provides a clean, explicit way to transform data into consistent JSON responses and automatically send them to the client. Resora supports single resources, collections, pagination and cursor metadata, conditional attributes, and response customization while remaining framework-agnostic and strongly typed.
 
 Resora is designed for teams that care about long-term maintainability, predictable API contracts, and clean separation of concerns.
 
@@ -33,6 +33,10 @@ Resora introduces a dedicated **response transformation layer** that removes the
 - Automatic JSON response dispatch
 - First-class collection support
 - Built-in pagination metadata handling
+- Built-in cursor metadata handling
+- Conditional attribute helpers (`when`, `whenNotNull`, `mergeWhen`)
+- Configurable response envelope (`wrap`, `rootKey`, `factory`)
+- Configurable pagination URL/link output (`baseUrl`, `pageName`, key mapping)
 - Predictable and consistent response contracts
 - Strong TypeScript typing
 - Transport-layer friendly (Express, H3, and others)
@@ -93,10 +97,13 @@ class UserCollection<R extends User[]> extends ResourceCollection<R> {
 return new UserCollection({
   data: users,
   pagination: {
+    currentPage: 1,
+    lastPage: 10,
     from: 1,
     to: 10,
     perPage: 10,
     total: 100,
+    path: '/users',
   },
 }).additional({
   status: 'success',
@@ -109,13 +116,17 @@ Response:
 ```json
 {
   "data": [...],
+  "links": {
+    "last": "https://localhost/users?page=10"
+  },
   "meta": {
-    "pagination": {
-      "from": 1,
-      "to": 10,
-      "perPage": 10,
-      "total": 100
-    }
+    "from": 1,
+    "to": 10,
+    "per_page": 10,
+    "total": 100,
+    "current_page": 1,
+    "last_page": 10,
+    "path": "/users"
   },
   "status": "success",
   "message": "Users retrieved"
@@ -162,6 +173,23 @@ It works with:
 
 Adapters can be added without changing application logic.
 
+## Conditional Rendering Example
+
+```ts
+class UserResource extends Resource {
+  data() {
+    return {
+      id: this.id,
+      email: this.whenNotNull(this.email),
+      role: this.when(this.isAdmin, 'admin'),
+      ...this.mergeWhen(this.isAdmin, { permissions: ['manage-users'] }),
+    };
+  }
+}
+```
+
+Falsy/null attributes are omitted from the final serialized payload.
+
 ---
 
 ## When to Use Resora
@@ -177,6 +205,15 @@ It is intentionally not opinionated about routing, validation, or persistence.
 
 ---
 
+## Documentation
+
+- Getting Started: https://arcstack-hq.github.io/resora/guide/getting-started
+- Configuration: https://arcstack-hq.github.io/resora/guide/configuration
+- Conditional Rendering: https://arcstack-hq.github.io/resora/guide/conditional-attributes
+- Pagination & Cursor Recipes: https://arcstack-hq.github.io/resora/guide/pagination-cursor-recipes
+
+---
+
 ## License
 
 MIT

package/bin/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync as i,writeFileSync as a}from"fs";import o,{dirname as s,join as c}from"path";import{Command as l,Kernel as u}from"@h3ravel/musket";let d=o.resolve(process.cwd(),`node_modules/resora/stubs`);t(d)||(d=o.resolve(process.cwd(),`stubs`));const f=()=>({stubsDir:d,preferredCase:`camel`,paginatedExtras:[`meta`,`links`],paginatedLinks:{first:`first`,last:`last`,prev:`prev`,next:`next`},paginatedMeta:{to:`to`,from:`from`,links:`links`,path:`path`,total:`total`,per_page:`per_page`,last_page:`last_page`,current_page:`current_page`},resourcesDir:`src/resources`,stubs:{config:`resora.config.stub`,resource:`resource.stub`,collection:`resource.collection.stub`}}),p=(e={})=>{let t=f();return Object.assign(t,e,{stubs:Object.assign(t.stubs,e.stubs||{})})};var m=class{command;config={};constructor(e={}){this.config=p(e)}async loadConfig(e={}){this.config=p(e);let n=[c(process.cwd(),`resora.config.ts`),c(process.cwd(),`resora.config.js`),c(process.cwd(),`resora.config.cjs`)];for(let e of n)if(t(e))try{let{default:t}=await import(e);Object.assign(this.config,t);break}catch(t){console.error(`Error loading config file at ${e}:`,t)}return this}init(){let n=c(process.cwd(),`resora.config.js`),i=c(this.config.stubsDir,this.config.stubs.config);return t(n)&&!this.command.option(`force`)&&(this.command.error(`Error: ${n} already exists.`),process.exit(1)),this.ensureDirectory(n),t(n)&&this.command.option(`force`)&&e(n,n.replace(/\.js$/,`.backup.${Date.now()}.js`)),a(n,r(i,`utf-8`)),{path:n}}ensureDirectory(e){let r=s(e);t(r)||n(r,{recursive:!0})}generateFile(e,n,o,s){t(n)&&!s?.force?(this.command.error(`Error: ${n} already exists.`),process.exit(1)):t(n)&&s?.force&&i(n);let c=r(e,`utf-8`);for(let[e,t]of Object.entries(o))c=c.replace(RegExp(`{{${e}}}`,`g`),t);return this.ensureDirectory(n),a(n,c),n}makeResource(e,n){let r=e;n?.collection&&!e.endsWith(`Collection`)&&!e.endsWith(`Resource`)?r+=`Collection`:!n?.collection&&!e.endsWith(`Resource`)&&!e.endsWith(`Collection`)&&(r+=`Resource`);let i=`${r}.ts`,a=c(this.config.resourcesDir,i),o=c(this.config.stubsDir,n?.collection||e.endsWith(`Collection`)?this.config.stubs.collection:this.config.stubs.resource);t(o)||(this.command.error(`Error: Stub file ${o} not found.`),process.exit(1));let s=r.replace(/(Resource|Collection)$/,``)+`Resource`,l=`/** 
+import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync as i,writeFileSync as a}from"fs";import o,{dirname as s,join as c}from"path";import{Command as l,Kernel as u}from"@h3ravel/musket";let d=o.resolve(process.cwd(),`node_modules/resora/stubs`);t(d)||(d=o.resolve(process.cwd(),`stubs`));const f=()=>({stubsDir:d,preferredCase:`camel`,responseStructure:{wrap:!0,rootKey:`data`},paginatedExtras:[`meta`,`links`],baseUrl:`https://localhost`,pageName:`page`,paginatedLinks:{first:`first`,last:`last`,prev:`prev`,next:`next`},paginatedMeta:{to:`to`,from:`from`,links:`links`,path:`path`,total:`total`,per_page:`per_page`,last_page:`last_page`,current_page:`current_page`},cursorMeta:{previous:`previous`,next:`next`},resourcesDir:`src/resources`,stubs:{config:`resora.config.stub`,resource:`resource.stub`,collection:`resource.collection.stub`}}),p=(e={})=>{let t=f();return Object.assign(t,e,{stubs:Object.assign(t.stubs,e.stubs||{})})};var m=class{command;config={};constructor(e={}){this.config=p(e)}async loadConfig(e={}){this.config=p(e);let n=[c(process.cwd(),`resora.config.ts`),c(process.cwd(),`resora.config.js`),c(process.cwd(),`resora.config.cjs`)];for(let e of n)if(t(e))try{let{default:t}=await import(e);Object.assign(this.config,t);break}catch(t){console.error(`Error loading config file at ${e}:`,t)}return this}getConfig(){return this.config}init(){let n=c(process.cwd(),`resora.config.js`),i=c(this.config.stubsDir,this.config.stubs.config);return t(n)&&!this.command.option(`force`)&&(this.command.error(`Error: ${n} already exists.`),process.exit(1)),this.ensureDirectory(n),t(n)&&this.command.option(`force`)&&e(n,n.replace(/\.js$/,`.backup.${Date.now()}.js`)),a(n,r(i,`utf-8`)),{path:n}}ensureDirectory(e){let r=s(e);t(r)||n(r,{recursive:!0})}generateFile(e,n,o,s){t(n)&&!s?.force?(this.command.error(`Error: ${n} already exists.`),process.exit(1)):t(n)&&s?.force&&i(n);let c=r(e,`utf-8`);for(let[e,t]of Object.entries(o))c=c.replace(RegExp(`{{${e}}}`,`g`),t);return this.ensureDirectory(n),a(n,c),n}makeResource(e,n){let r=e;n?.collection&&!e.endsWith(`Collection`)&&!e.endsWith(`Resource`)?r+=`Collection`:!n?.collection&&!e.endsWith(`Resource`)&&!e.endsWith(`Collection`)&&(r+=`Resource`);let i=`${r}.ts`,a=c(this.config.resourcesDir,i),o=c(this.config.stubsDir,n?.collection||e.endsWith(`Collection`)?this.config.stubs.collection:this.config.stubs.resource);t(o)||(this.command.error(`Error: Stub file ${o} not found.`),process.exit(1));let s=r.replace(/(Resource|Collection)$/,``)+`Resource`,l=`/** 
      * The resource that this collection collects.
      */
     collects = ${s}
@@ -26,4 +26,4 @@ import{copyFileSync as e,existsSync as t,mkdirSync as n,readFileSync as r,rmSync
  |  _  // _ \/ __|/ _ \| '__/ _, |
  | | \ \  __/\__ \ (_) | | | (_| |
  |_|  \_\___||___/\___/|_|  \__,_|                                                                                           
-`;const v=new m;await u.init(await v.loadConfig(),{logo:_,name:`Resora CLI`,baseCommands:[g,h],exceptionHandler(e){throw e}});export{};
+`;const v=new m;await u.init(await v.loadConfig(),{logo:_,name:`Resora CLI`,baseCommands:[g,h,...v.getConfig().extraCommands||[]],exceptionHandler(e){throw e}});export{};