@tryghost/jsonapi-mapper 1.0.0

package/es/bookshelf/index.js

@@ -0,0 +1,55 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { assign, identity } from "lodash";
+import { pluralize as plural } from "inflection";
+import { Serializer } from "../serializer";
+import { processData, toJSON } from "./utils";
+class Bookshelf {
+  /**
+   * Standard constructor
+   */
+  constructor(baseUrl, serialOpts) {
+    __publicField(this, "baseUrl", baseUrl);
+    __publicField(this, "serialOpts", serialOpts);
+  }
+  /**
+   * Maps bookshelf data to a JSON-API 1.0 compliant object
+   *
+   * The `any` type data source is set for typing compatibility, but must be removed if possible
+   * TODO fix data any type
+   */
+  map(data, type, mapOpts = {}) {
+    const {
+      attributes,
+      keyForAttr = identity,
+      relations = true,
+      typeForModel = (attr) => plural(attr),
+      enableLinks = true,
+      pagination,
+      query,
+      meta,
+      outputVirtuals
+    } = mapOpts;
+    const bookOpts = {
+      attributes,
+      keyForAttr,
+      relations,
+      typeForModel,
+      enableLinks,
+      pagination,
+      query,
+      outputVirtuals
+    };
+    const linkOpts = { baseUrl: this.baseUrl, type, pag: pagination };
+    const info = { bookOpts, linkOpts };
+    const template = processData(info, data);
+    const typeForAttribute = typeof typeForModel === "function" ? typeForModel : (attr) => typeForModel[attr] || plural(attr);
+    assign(template, { typeForAttribute, keyForAttribute: keyForAttr, meta }, this.serialOpts);
+    const json = toJSON(data);
+    return new Serializer(type, template).serialize(json);
+  }
+}
+export {
+  Bookshelf
+};

package/es/bookshelf/links.js

@@ -0,0 +1,92 @@
+import { assign, omit, isEmpty, isNil } from "lodash";
+import { pluralize as plural } from "inflection";
+import { stringify as queryParams } from "qs";
+function urlConcat(...parts) {
+  return parts.join("/");
+}
+function topLinks(linkOpts) {
+  let { baseUrl, type, pag } = linkOpts;
+  let obj = {
+    self: urlConcat(baseUrl, plural(type))
+  };
+  if (!isNil(pag)) {
+    if (!isNil(pag.rowCount)) {
+      pag.total = pag.rowCount;
+    }
+    if (!isNil(pag.total) && pag.total > 0 && pag.total > pag.limit) {
+      assign(obj, pagLinks(linkOpts));
+    }
+  }
+  return obj;
+}
+function pagLinks(linkOpts) {
+  let { baseUrl, type, pag, query = {} } = linkOpts;
+  if (pag === void 0) {
+    return void 0;
+  }
+  const { offset, limit, total } = pag;
+  let baseLink = urlConcat(baseUrl, plural(type));
+  query = omit(query, ["page", "page[limit]", "page[offset]"]);
+  baseLink = baseLink + "?" + queryParams(query, { encode: false });
+  let obj = {};
+  if (offset > 0) {
+    obj.first = () => {
+      let page = { page: { limit, offset: 0 } };
+      return baseLink + queryParams(page, { encode: false });
+    };
+    obj.prev = () => {
+      let page = { page: { limit, offset: offset - limit } };
+      return baseLink + queryParams(page, { encode: false });
+    };
+  }
+  if (total && offset + limit < total) {
+    obj.next = () => {
+      let page = { page: { limit, offset: offset + limit } };
+      return baseLink + queryParams(page, { encode: false });
+    };
+    obj.last = () => {
+      let lastLimit = (total - offset % limit) % limit;
+      lastLimit = lastLimit === 0 ? limit : lastLimit;
+      let lastOffset = total - lastLimit;
+      let page = { page: { limit: lastLimit, offset: lastOffset } };
+      return baseLink + queryParams(page, { encode: false });
+    };
+  }
+  return !isEmpty(obj) ? obj : void 0;
+}
+function dataLinks(linkOpts) {
+  let { baseUrl, type } = linkOpts;
+  let baseLink = urlConcat(baseUrl, plural(type));
+  return {
+    self: function(resource) {
+      return urlConcat(baseLink, resource.id);
+    }
+  };
+}
+function relationshipLinks(linkOpts, related) {
+  let { baseUrl, type } = linkOpts;
+  let baseLink = urlConcat(baseUrl, plural(type));
+  return {
+    self: function(resource, current, parent) {
+      return urlConcat(baseLink, parent.id, "relationships", related);
+    },
+    related: function(resource, current, parent) {
+      return urlConcat(baseLink, parent.id, related);
+    }
+  };
+}
+function includedLinks(linkOpts) {
+  let { baseUrl, type } = linkOpts;
+  let baseLink = urlConcat(baseUrl, plural(type));
+  return {
+    self: function(primary, current) {
+      return urlConcat(baseLink, current.id);
+    }
+  };
+}
+export {
+  dataLinks,
+  includedLinks,
+  relationshipLinks,
+  topLinks
+};

package/es/bookshelf/utils.js

@@ -0,0 +1,171 @@
+import {
+  assign,
+  clone,
+  cloneDeep,
+  filter,
+  includes,
+  intersection,
+  isArray,
+  isNil,
+  isString,
+  isUndefined,
+  escapeRegExp,
+  forOwn,
+  has,
+  keys,
+  map,
+  mapValues,
+  merge,
+  omit,
+  reduce,
+  some,
+  toString,
+  update
+} from "lodash";
+import { topLinks, dataLinks, relationshipLinks, includedLinks } from "./links";
+import { isModel, isCollection } from "./extras";
+function processData(info, data) {
+  let { bookOpts: { enableLinks }, linkOpts } = info;
+  let template = processSample(info, sample(data));
+  if (enableLinks) {
+    template.dataLinks = dataLinks(linkOpts);
+    template.topLevelLinks = topLinks(linkOpts);
+  }
+  return template;
+}
+function processSample(info, sample2) {
+  let { bookOpts, linkOpts } = info;
+  let { enableLinks } = bookOpts;
+  let template = {
+    // Add list of valid attributes
+    attributes: getAttrsList(sample2, bookOpts)
+  };
+  forOwn(sample2.relations, (relSample, relName) => {
+    if (!relationAllowed(bookOpts, relName)) {
+      return;
+    }
+    let relLinkOpts = assign(clone(linkOpts), { type: relName });
+    let relTemplate = processSample({ bookOpts, linkOpts: relLinkOpts }, relSample);
+    relTemplate.ref = "id";
+    if (enableLinks) {
+      relTemplate.relationshipLinks = relationshipLinks(linkOpts, relName);
+      relTemplate.includedLinks = includedLinks(relLinkOpts);
+    }
+    if (!includeAllowed(bookOpts, relName)) {
+      relTemplate.included = false;
+    }
+    template[relName] = relTemplate;
+    template.attributes.push(relName);
+  });
+  return template;
+}
+function sample(data) {
+  if (isModel(data)) {
+    const sampled = cloneDeep(omit(data, "relations"));
+    sampled.relations = mapValues(data.relations, sample);
+    return sampled;
+  } else if (isCollection(data)) {
+    const first = data.first();
+    const rest = data.slice(1);
+    return reduce(rest, mergeSample, sample(first));
+  } else {
+    return {};
+  }
+}
+function mergeSample(main, toMerge) {
+  const sampled = sample(toMerge);
+  main.attributes = merge(main.attributes, sampled.attributes);
+  main.relations = merge(main.relations, sampled.relations);
+  return main;
+}
+function matches(matcher, str) {
+  let reg;
+  if (typeof matcher === "string") {
+    reg = RegExp(`^${escapeRegExp(matcher)}$`);
+  } else {
+    reg = matcher;
+  }
+  return reg.test(str);
+}
+function getAttrsList(data, bookOpts) {
+  let idAttr = data.idAttribute;
+  if (isString(idAttr)) {
+    idAttr = [idAttr];
+  } else if (isUndefined(idAttr)) {
+    idAttr = [];
+  }
+  let attrs = keys(data.attributes);
+  let outputVirtuals = data.outputVirtuals;
+  if (!isNil(bookOpts.outputVirtuals)) {
+    outputVirtuals = bookOpts.outputVirtuals;
+  }
+  if (data.virtuals && outputVirtuals) {
+    attrs = attrs.concat(keys(data.virtuals));
+  }
+  let { attributes = { omit: idAttr } } = bookOpts;
+  if (attributes instanceof Array) {
+    attributes = { include: attributes };
+  }
+  let { omit: omit2, include } = attributes;
+  return filter(attrs, (attr) => {
+    let included = true;
+    let omitted = false;
+    if (include) {
+      included = some(include, (m) => matches(m, attr));
+    }
+    if (omit2) {
+      omitted = some(omit2, (m) => matches(m, attr));
+    }
+    return !omitted && included;
+  });
+}
+function relationAllowed(bookOpts, relName) {
+  let { relations } = bookOpts;
+  if (typeof relations === "boolean") {
+    return relations;
+  } else {
+    let { fields } = relations;
+    return !fields || includes(fields, relName);
+  }
+}
+function includeAllowed(bookOpts, relName) {
+  let { relations } = bookOpts;
+  if (typeof relations === "boolean") {
+    return relations;
+  } else {
+    let { fields, included } = relations;
+    if (typeof included === "boolean") {
+      return included;
+    } else {
+      let allowed = included;
+      if (fields) {
+        allowed = intersection(fields, included);
+      }
+      return includes(allowed, relName);
+    }
+  }
+}
+function toJSON(data) {
+  let json = null;
+  if (isModel(data)) {
+    json = data.toJSON({ shallow: true });
+    const idAttr = data.idAttribute;
+    if (isArray(idAttr)) {
+      data.id = map(idAttr, (attr) => data.attributes[attr]).join(",");
+    }
+    if (!has(json, "id")) {
+      json.id = data.id;
+    }
+    update(json, "id", toString);
+    forOwn(data.relations, function(relData, relName) {
+      json[relName] = toJSON(relData);
+    });
+  } else if (isCollection(data)) {
+    json = data.map(toJSON);
+  }
+  return json;
+}
+export {
+  processData,
+  toJSON
+};

package/es/index.js

@@ -0,0 +1,3 @@
+export * from "./bookshelf";
+export * from "./interfaces";
+export * from "./serializer";

package/es/interfaces/index.js

@@ -0,0 +1,3 @@
+export * from "./common";
+export * from "./links";
+export * from "./relations";

package/es/serializer/index.js

@@ -0,0 +1,5 @@
+import * as jas from "jsonapi-serializer";
+let Serializer = jas.Serializer;
+export {
+  Serializer
+};

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@tryghost/jsonapi-mapper",
+  "version": "1.0.0",
+  "description": "JSON API-Compliant Serialization for your ORM",
+  "source": "src/index.ts",
+  "files": [
+    "cjs",
+    "es",
+    "types",
+    "src"
+  ],
+  "main": "cjs/index.js",
+  "module": "es/index.js",
+  "types": "types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "ssh://git@github.com/TryGhost/Pro-Packages",
+    "directory": "packages/jsonapi-mapper"
+  },
+  "keywords": [
+    "json",
+    "api",
+    "json-api",
+    "jsonapi",
+    "orm",
+    "mapper",
+    "bookshelf",
+    "serializer",
+    "serialization"
+  ],
+  "author": "James Dixon <jim.w.dixon@gmail.com>",
+  "contributors": [
+    {
+      "name": "Manuel Pacheco",
+      "email": "manuelalejandropm@gmail.com"
+    },
+    {
+      "name": "Matteo Ferrando",
+      "email": "matteo.ferrando2@gmail.com"
+    }
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/TryGhost/Pro-Packages/issues"
+  },
+  "homepage": "https://github.com/TryGhost/Pro-Packages/tree/main/packages/jsonapi-mapper",
+  "dependencies": {
+    "bookshelf": "1.2.0",
+    "inflection": "1.12.0",
+    "jsonapi-serializer": "3.5.6",
+    "knex": "0.21.1",
+    "lodash": "^4.17.20",
+    "qs": "6.5.1",
+    "type-check": "0.3.2"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/cjs",
+          "{projectRoot}/es",
+          "{projectRoot}/types"
+        ]
+      }
+    }
+  },
+  "devDependencies": {
+    "@types/bookshelf": "1.1.1",
+    "@types/inflection": "1.5.28",
+    "@types/knex": "0.0.61",
+    "@types/lodash": "4.14.93",
+    "@types/node": "25.7.0",
+    "@types/qs": "6.5.1",
+    "esbuild": "0.28.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "dev": "echo \"Implement me!\"",
+    "pretest": "NODE_ENV=production pnpm run build",
+    "build": "pnpm run build:cjs && pnpm run build:es && pnpm run build:types",
+    "build:cjs": "esbuild src/index.ts 'src/**/*.ts' --target=es2020 --outdir=cjs --format=cjs",
+    "build:es": "esbuild src/index.ts 'src/**/*.ts' --target=es2020 --outdir=es --format=esm",
+    "build:types": "tsc --emitDeclarationOnly --declaration --declarationMap --outDir types",
+    "test": "NODE_ENV=testing vitest run --coverage",
+    "lint": "oxlint -c ../../.oxlintrc.json .",
+    "posttest": "pnpm run lint"
+  }
+}

package/src/bookshelf/extras.ts

@@ -0,0 +1,77 @@
+/**
+ * The purpose of this module is to extend the initially defined properties,
+ * behaviors and characteristics of the bookshelf API
+ */
+
+import { Model as BModel, Collection as BCollection } from 'bookshelf';
+import { MapOpts, RelationTypeOpt, RelationOpts } from '../interfaces';
+
+// Bookshelf Options
+export interface BookOpts extends MapOpts {
+  // Attributes-related
+  keyForAttr: (attr: string) => string;
+
+  // Relations-related
+  relations: boolean | RelationOpts;
+  typeForModel: RelationTypeOpt;
+
+  // Links-related
+  enableLinks: boolean;
+
+  // Virtuals-related;
+  outputVirtuals?: boolean;
+}
+
+/**
+ * Internal form of the relations property of bookshelf objects
+ */
+export interface RelationsObject {
+  [relationName: string]: Data;
+}
+
+export interface Attributes {
+  [attrName: string]: any;
+}
+
+/**
+ * Bookshelf Model including some private properties
+ */
+export interface Model extends BModel<any> {
+  id: any;
+
+  // TODO: PR to fix Bookshelf types
+  // idAttribute?: string | string[];
+  idAttribute: any;
+
+  attributes: Attributes;
+  relations: RelationsObject;
+  virtuals?: any;
+  outputVirtuals?: boolean;
+}
+
+/**
+ * Bookshelf Collection including some private properties
+ */
+export interface Collection extends BCollection<any> {
+  models: Model[];
+  length: number;
+}
+
+export type Data = Model | Collection;
+
+/**
+ * Bookshelf Model Type Guard
+ * https://basarat.gitbooks.io/typescript/content/docs/types/typeGuard.html
+ */
+export function isModel(data: Data): data is Model {
+  return data ? !isCollection(data) : false;
+}
+
+/**
+ * Bookshelf Collection Type Guard
+ * https://basarat.gitbooks.io/typescript/content/docs/types/typeGuard.html
+ */
+export function isCollection(data: Data): data is Collection {
+  // Type recognition based on duck-typing
+  return data ? (data as Collection).models !== undefined : false;
+}

package/src/bookshelf/index.ts

@@ -0,0 +1,64 @@
+import { assign, identity } from 'lodash';
+import { pluralize as plural } from 'inflection';
+
+import { SerialOpts, Serializer } from '../serializer';
+import { Mapper, MapOpts, LinkOpts } from '../interfaces';
+import { Data, BookOpts } from './extras';
+import { Information, processData, toJSON } from './utils';
+
+/**
+ * Mapper class for Bookshelf sources
+ */
+export class Bookshelf implements Mapper {
+
+  /**
+   * Standard constructor
+   */
+  constructor(public baseUrl: string, public serialOpts?: SerialOpts) { }
+
+  /**
+   * Maps bookshelf data to a JSON-API 1.0 compliant object
+   *
+   * The `any` type data source is set for typing compatibility, but must be removed if possible
+   * TODO fix data any type
+   */
+  map(data: Data | any, type: string, mapOpts: MapOpts = {}): any {
+
+    // Set default values for the options
+    const {
+      attributes,
+      keyForAttr = identity,
+      relations = true,
+      typeForModel = (attr: string) => plural(attr),
+      enableLinks = true,
+      pagination,
+      query,
+      meta,
+      outputVirtuals
+    }: MapOpts = mapOpts;
+
+    const bookOpts: BookOpts = {
+      attributes, keyForAttr,
+      relations, typeForModel,
+      enableLinks, pagination,
+      query, outputVirtuals
+    };
+
+    const linkOpts: LinkOpts = { baseUrl: this.baseUrl, type, pag: pagination };
+
+    const info: Information = { bookOpts, linkOpts };
+    const template: SerialOpts = processData(info, data);
+
+    const typeForAttribute: (attr: string) => string =
+      typeof typeForModel === 'function'
+        ? typeForModel
+        : (attr: string) =>  typeForModel[attr] || plural(attr);  // pluralize when falsy
+
+    // Override the template with the provided serializer options
+    assign(template, { typeForAttribute, keyForAttribute: keyForAttr, meta }, this.serialOpts);
+
+    // Return the data in JSON API format
+    const json: any = toJSON(data);
+    return new Serializer(type, template).serialize(json);
+  }
+}