@bermi/lotr-sdk

lotr-sdk

🧙‍♂️ lotr-sdk The Lord of the Rings SDK

Available via npm for node.js, deno 🦕.

Documentation

Usage

In node.js, install with npm npm install @bermi/lotr-sdk --save. Then require it in your project with:

const lotrSdk = require("@bermi/lotr-sdk").default;

Using TypeScript:

import lotrSdk, { LotrSdk } from "@bermi/lotr-sdk";

Using Deno:

import lotrSdk, { LotrSdk } from "https://deno.land/x/lotr@v1.3.3/mod.ts";

Example

const lotr: LotrSdk = lotrSdk({
  apiToken: "l1bl4b", // Will default to the environment variable LOTR_API_TOKEN
});

// Authenticate the session. Automatically called,
// but it's recommended to call it manually to handle
// authentication errors in the right context.
await lotr.authenticate();

// For list methods you can pass pagination options
const options = { limit: 2, offset: 0, page: 1 };

// Sort options are available for list methods
// By providing sort=field:asc or sort=field:desc you can sort
// by the field in ascending or descending order.
// const options = { sort: "name:asc" };

// Get a list of movies
const movies = await lotr.listMovies(); // => { docs: [{ _id: "123", name: "The Fellowship of the Ring" }], ... }

// Get a movie by id
const movie = await lotr.getMovie("123"); // => { _id: "123", name: "The Fellowship of the Ring" }

// Get a list of quotes for a movie
const quotes = await lotr.listMovieQuotes("123"); // => { docs: [{ _id: "456", character: "789", dialog: "You shall not pass!" }], ... }

Use an async iterator to iterate over all the movies:

// Iterate all movies
for await (const movie of lotr.allMovies()) {
  console.log({ movie });
}

// Iterate all quotes for a movie
for await (const quote of lotr.allMovieQuotes("5cd95395de30eff6ebccde5b")) {
  console.log({ quote });
}

The documentation for the API exposes mongodb lookup expression syntax that can be used to filter, sort, and match results before returning them. JavaScript Array methods: filter, sort, find, reduce, map, etc. are more familiar to developers than custom methods or options.

For example, to get all the movies that have a runtime greater than 200 minutes:

const allMovies = [];
for await (const movie of lotr.allMovies()) {
  allMovies.push(movie);
}
const longMovies = allMovies.filter((movie) => movie.runtimeInMinutes > 200);

This method trades off memory and the initial latency for a more familiar API.

Examples

The directory ./examples contains examples showing how to use this library.

To run all the examples, call:

make run-examples

Design decisions

Please read the design document for more information about the design decisions.

Development

lotr-sdk has been developed using deno 🦕.

The Makefile includes shortcuts to commands that will help test the project and run the examples.

Documentation

The command deno doc mod.ts will show the documentation for the project.

Releasing

Calling make build will generate multiple versions of this project.

npm

The npm directory contains a node.js-compatible version of the project ready to be pushed to npm. You can use make npm-publish to publish the latest version.

cli

The directory deno_dir/dist/binaries/ contains standalone binary versions of the program for Linux, MacOS, and Windows.

deno

Use https://deno.land/add_module to expose this project on https://deno.land/x/lotr

Tests

To run the tests, call:

make test

License

MIT License

Copyright (c) 2023 Bermi Ferrer

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.