ec.fdk

Featherweight Development Kit for entrecode APIs.

Install

npm i ec.fdk

Getting Started

There are 2 ways to use ec.fdk:

method chaining
act

Method Chaining

Start by calling fdk with your environment (stage | live), then method chain your way to success:

import { fdk } from "ec.fdk";

fdk("stage") // choose stage environment
  .dm("83cc6374") // select datamanager via short id
  .model("muffin") // select model muffin
  .entryList() // load entry list
  .then((list) => {
    console.log(list);
  });

See all functions in the Fdk reference.

act

The act function converts a single object param into a fetch request:

const muffins = await act({
  action: "entryList",
  env: "stage",
  dmShortID: "83cc6374",
  model: "muffin",
});

Using act with swr / react-query

The act function is good to be used with swr or react-query:

import { act } from "ec.fdk";
import useSWR from "swr";

export function useFdk(config) {
  const key = config ? JSON.stringify(config) : null;
  return useSWR([key], () => act(config));
}

Then use the hook:

const config = {
  env: "stage",
  dmShortID: "83cc6374",
};

function App() {
  const { data: entryList } = useFdk({
    ...config,
    action: "entryList",
    model: "muffin",
  });
  /* more stuff */
}

migration from ec.sdk

ec.fdk won't change / decorate data returned from ec APIs. For example, an entry returned from the datamanager will be returned as is. Advantages:

The network tab shows what goes into the frontend
Resources have the same shape everywhere
Resources are serializable

Entry save

Instead of mutating an EntryResource and calling .save(), we now pass the new value directly:

// this does not exist anymore:
await entry.save(); // <- DONT
// use this to update an entry:
await editEntryObject(entry, value); // <- DO
// alternatively:
await fdk.env(env).dm(dmShortID).model(model).updateEntry(entryID, value);
// or:
await act({ action: "editEntry", env, dmShortID, model, entryID, value });

Entry delete

Similar to save:

// this does not exist anymore:
await entry.del(); // <- DONT
// use this to delete an entry:
await deleteEntryObject(entry); // <- DO
// alternatively:
await fdk.dm("shortID").model("model").deleteEntry("entryID");
// or:
await act({ action: "deleteEntry", env, dmShortID, model, entryID });

Entry Asset Fields

In ec.fdk, entry asset fields are plain ids:

// assuming "photo" is an asset field:
entry.photo; // <-- this used to be an AssetResource. Now it's a plain id string.
// use this to get the embedded AssetResource:
getEntryAsset("photo", entry); // (no request goes out)

Entry Date Fields

// assuming "lastSeen" is a datetime field:
entry.lastSeen; // <-- this used to be an instance of Date. Now it's a date ISO string
// use this to get a Date instance:
new Date(entry.lastSeen);

Entry List

// ec.sdk
const api = new PublicAPI(shortID, env, true);
const entryList = await api.entryList(model);
const items = entryList.getAllItems();
const first = entryList.getFirstItem();
// ec.fdk
const api = fdk(env).dm(shortID);
const entryList = await api.entryList(model);
const items = entryList.items; // <------- change
const first = entryList.items[0]; // <------- change
// or in one line:
const entryList = await fdk(env).dm(shortID).entryList(model);

Entry List Filter Options

By default, the second param of ec.fdk entryList will just convert the object to url params:

const entryList = await fdk("stage")
  .dm("83cc6374")
  .entryList({ createdTo: "2021-01-18T09:13:47.605Z" });
/* 
https://datamanager.cachena.entrecode.de/api/83cc6374/muffin?
_list=true&
createdTo=2021-01-18T09:13:47.605Z&
page=1&
size=50
*/

Read more in the entrecode filtering doc

There is some syntax sugar you can use to get the same behavior as ec.sdk filterOptions:

const entryList = await fdk("stage")
  .dm("83cc6374")
  .entryList(filterOptions({ created: { to: "2021-01-18T09:13:47.605Z" } }));

Publish

cd packages/ec.fdk
bump version in packages/ec.fdk/package.json
run pnpm docs to regenerate docs folder
commit + push
run pnpm publish