DEV Community: Lem Canady

Make A TypeScript Middleware Engine

Lem Canady — Mon, 07 Dec 2020 23:58:10 +0000

Introduction

The Middleware pattern is prevalent, especially in the NodeJS ecosystem — and for a good reason! It gives your users a simple interface for extending your software to fit their particular use case and decoupling the sender and receiver, among many other benefits. If you’ve spent any time working with Node’s HTTP/HTTPS libraries, express, KOA, or just about every Node-based web server, then you’ve seen the pattern before.

module.exports = (req, res, next) => {
    req.property = value;
    next();
}

Today, we’ll dig in and learn more about the middleware pattern by building our very own middleware engine, Typescript edition! In the sections that follow, I’m going to start with code, then offer some explanations into the how and why. Ready? Here we go!

Typing

We’ll start with the types that I made to handle the engine. For the most part, they show how the different elements of our engine are going to work.

export type Next = () => Promise<any>;

export type Middleware<T> = (
    context: T,
    next: Next
) => Promise<void>;

export type Pipe<T> = {
    use: (...middlewares: Middleware<T>[]) => Promise<void>;
    execute: (context: T) => Promise<T>;
};

First, I started by defining the type for the next function. It’s invoked at the end of every middleware module. The Next is essentially a container. In particular, it’s a container for functions. A crucial fact for later!

The middleware module comes next. The main part of the framework. Each middleware encapsulates work to be executed on our context object before executing the next function, as shown in the first example.

Finally, we have the definition for the actual engine, the pipe. It has two functions, use and execute. Use loads the pipe with middleware, while execute runs through all of the middleware in the pipe, using the context object.

The Code

Instead of using a class, we will use the revealing module pattern to share our public API. First, we need to declare the stack, an array that will hold all of our middleware functions.

/**
 * Declare a new middleware pipeline.
 * @param middlewares A list of middlewares to add to the pipeline on
 * instantiation.
 */
export function pipeline<T>(...middlewares: Middleware<T>[]): Pipe<T> {
  const stack: Middleware<T>[] = middlewares;

  /**
   * Add middlewares to the pipeline.
   * @param middlewares A list of middlewares to add to the current
   * pipeline.
   */
  const use: Pipe<T>["use"] = (...middlewares) => {
    stack.push(...middlewares);
  };
}

This portion of the code is pretty straight forward. First, we declare our pipeline, the middleware engine, that optionally takes a comma-separated middleware list on instantiation. Next, the stack is defined, then use as a constant. Use takes in a list of middleware and adds them to the stack. Pushing it onto the end.

Next is where the magic happens, the execute function. It’s powered by two key components: a recursive algorithm and closure.

const execute: Pipe<T>["execute"] = async (context) => {
    let prevIndex = -1;

    /**
     * Programmatically go through each middleware and apply it to the context before
     * either moving on to the next middleware or returning the final context
     * object.
     * @param index The current count of middleware executions.
     * @param context The context object to send through the
     * middleware pipeline.
     */
    const handler = async (index: number, context: T): Promise<void | T> => {
      if (index === prevIndex) {
        throw new Error("next() already called.");
      }

      if (index === stack.length) return context;

      prevIndex = index;

      const middleware = stack[index];

      if (middleware) {
        await middleware(context, () => handler(index + 1, context));
      }
    };
    const response = await handler(0, context);
    if (response) return response;
};

First, on line 2, we declare our index at -1 since 0 acts as the first index of our stack array. Next, we set up our recursive function, handler. We do some basic error checking first to make sure each middleware is only being called once. Then, if the middleware index matches the length of the stack, return the context.

On line 21, We select a middleware function from the stack based on the current index and run it. Note how along with context, we pass the handler function to next. This means that when next() is called in the middleware function, it’s actually invoking another run of the handler function, at index +1. A notice how context is actually defined as an exec's argument, and we pass it around to our inner functions? That’s closure! When a variable is defined in an outer scope and referenced within a nested function.
Finally, on lines 27 and 28, we kick off the recursive handler and wait for it to return with a value. That value is then passed back to the rest of your program.

Now let’s look at the whole module at once!

// First we declare our types.
export type Next = () => Promise<any> | any;
export type Middleware<T> = (
  context: T,
  next: Next
) => Promise<void>;
export type Pipe<T> = {
  use: (...middlewares: Middleware<T>[]) => void;
  execute: (context: T) => Promise<void | T>;
};

/**
 * Declare a new middleware pipeline.
 * @param middlewares A list of middlewares to add to the pipeline on
 * instantiation.
 */
export function pipeline<T>(...middlewares: Middleware<T>[]): Pipe<T> {
  const stack: Middleware<T>[] = middlewares;

  /**
   * Add middlewares to the pipeline.
   * @param middlewares A list of middlewares to add to the current
   * pipeline.
   */
  const use: Pipe<T>["use"] = (...middlewares) => {
    stack.push(...middlewares);
  };

  /**
   * Execute a pipeline, and move context through each middleware in turn.
   * @param context The contect object to be sent through the pipeline.
   */
  const execute: Pipe<T>["execute"] = async (context) => {
    let prevIndex = -1;

    /**
     * Programmatically go through each middleware and apply it to context before
     * either moving on to the next middleware or returning the final context
     * object.
     * @param index The current count of middleware executions.
     * @param context The context object to send through the
     * middleware pipeline.
     */
    const handler = async (index: number, context: T): Promise<void | T> => {
      if (index === prevIndex) {
        throw new Error("next() already called.");
      }

      if (index === stack.length) return context;

      prevIndex = index;

      const middleware = stack[index];

      if (middleware) {
        await middleware(context, () => handler(index + 1, context));
      }
    };
    const response = await handler(0, context);
    if (response) return response;
  };

  return { use, execute };
}

At the end of the function (line 63), we return use and execute, offering them our public API. Now let’s see this engine at work!

interface Context {
    [key: string]: any
}

const engine = pipeline<Context>((ctx, next) => {
    ctx.foobar="baz";
    next();
})

engine.use((ctx, next) => {
  ctx.another = 123;
  next();
});

(async () => {
  const context: Context = {};
  await engine.exec(context);
  console.log(context);
})();

// => { foobar: "baz", another: 123 }

I hope you enjoyed my little demo here. If you’d like to see the entire project, it’s available on my GitHub!

Thanks for reading!

Building a Modern MUSH with Typescript Part 6: The Mushcode parser!

Lem Canady — Wed, 25 Mar 2020 15:39:08 +0000

Welcome back! In Part 5 we built the database adapter and actually got the game booted up! Today we're covering my favorite part - the Mushcode interpreter! We'll also build a function as well as a command that makes use of the mushcode engine. It's a kind of code dense, but we'll get through it!

Making a Grammar

I decided early on that I was going to go a different direction than the destructive parser that's popular in other MU* engines. Instead, I went with a library called PEGJS, or a Parsing Expression Grammar. It lexes down expressions into an Abstract Syntax Tree (AST). From there we recursively walk the tree until we've parsed the entire expression.

Disclaimer

I've never taken any sort of language design coursework, I've had to crash course myself on this part. My grammar is messy!

With that said, here we go!

The Grammar

// mushcode Grammar
// Author: Lemuel Canady, Jr 2020
// This grammar is really basic, but it gets the job done!
// Builds an AST to be processed by the game server.

function =  _ call: word "(" _ a: (args)? _ ")" _  
{ 
    const loc = location()
    return {
        type: "function", 
        operator: {type: "word", value:call},
        location: loc,
        args: Array.isArray(a) ? a : [a]
   }
} /

_ "[" _ call: word "(" _ a: (args)? _ ")" _ "]" _  
{ 
    const loc = location()
    return {
        type: "function", 
        operator: {type: "word", value:call},
        location: loc,
        args: Array.isArray(a) ? a : [a]
   }
}


args =  a:(arg arg)+ _ t:args* {
   return [{type: "list", list: a.flat()},...t].flat()
}/ 

a: arg* _ "," _ "," _ t: (args)* 
{ 
    const loc = location();
    return [[
        a,{type: "word", value: null, location:loc}
    ].flat(),t.flat()].flat() 
}/

a: arg* _ "," _ t: (args)* {return [a.flat(),t.flat()].flat()}  / 
arg 

arg =   f: function {return f} / 
    w: word { 
        const loc = location();
        return {type: "word", value: w,   location: loc 
    } 
}

word = w:[^\(\),\[\]]+ {return w.join("").trim()} 
_ = [ \t\n\r]*

The grammar looks for 3 things: Words, functions, and lists. When defining a grammar, they're built from the bottom up. I started with defining what space is, then a word - and move up until I get to define what makes an expression at the top.

A word is anything that isn't a function - function arguments, function names, numbers - it's all strings. Lists are a series of expressions side by side, separated by brackets. For Instance! If we took this mushcode snippet (warning, it's verbose! :D ):

[a([b(1,2)][c()])]

Once parsed by the Grammer returns:

{
   "type": "function",
   "operator": {
      "type": "word",
      "value": "a"
   },
   "location": {
      "start": {
         "offset": 0,
         "line": 1,
         "column": 1
      },
      "end": {
         "offset": 18,
         "line": 1,
         "column": 19
      }
   },
   "args": [
      {
         "type": "list",
         "list": [
            {
               "type": "function",
               "operator": {
                  "type": "word",
                  "value": "b"
               },
               "location": {
                  "start": {
                     "offset": 3,
                     "line": 1,
                     "column": 4
                  },
                  "end": {
                     "offset": 11,
                     "line": 1,
                     "column": 12
                  }
               },
               "args": [
                  {
                     "type": "word",
                     "value": "1",
                     "location": {
                        "start": {
                           "offset": 6,
                           "line": 1,
                           "column": 7
                        },
                        "end": {
                           "offset": 7,
                           "line": 1,
                           "column": 8
                        }
                     }
                  },
                  {
                     "type": "word",
                     "value": "2",
                     "location": {
                        "start": {
                           "offset": 8,
                           "line": 1,
                           "column": 9
                        },
                        "end": {
                           "offset": 9,
                           "line": 1,
                           "column": 10
                        }
                     }
                  }
               ]
            },
            {
               "type": "function",
               "operator": {
                  "type": "word",
                  "value": "c"
               },
               "location": {
                  "start": {
                     "offset": 11,
                     "line": 1,
                     "column": 12
                  },
                  "end": {
                     "offset": 16,
                     "line": 1,
                     "column": 17
                  }
               },
               "args": [
                  null
               ]
            }
         ]
      }
   ]
}

I decided to keep the location information for a debugger I have planned in the future. Once I have that AST I put it through the non-destructive in-game parser. First, we'll save the grammar to the root of our project as mushcode.pegjs. Then, we need to body parser.ts to handle the interpretation.

Want to play with the grammar? Head to PegJS Online, enter my grammar and start building expressions! If you can make improvements? Please let me know!

Updating `parser.ts`

Before we begin! We need to add a new folder to our project structure. From your project root type:

mkdir src/functions

Then, we need to define a couple of new interfaces to shape our data:

export type MuFunction = (
  enactor: DBObj,
  args: Array<Expression | string | number>,
  scope: Scope
) => Promise<any>;

export interface Expression {
  type: string;
  value: string;
  list?: Expression[];
  operator: {
    type: string;
    value: string;
  };
  location?: {
    start: {
      offset: number;
      line: number;
      column: number;
    };
    end: {
      offset: number;
      line: number;
      column: number;
    };
  };
  args: Array<string | Expression>;
}

export interface Scope {
  [key: string]: any;
}

And in the constructor:

export class Parser {
  private stack: MiddlewareLayer[];
  private static instance: Parser;
  private peg: any; 
  private parser: peg.Parser;
  private fns: Map<string, MuFunction>;
  private constructor() {
    this.stack = [];
    this.peg = readFileSync(
      resolve(__dirname, "../../mushcode.pegjs"), {
        encoding: "utf8"
    });
    this.parser = peg.generate(this.peg);
    this.fns = new Map();
    loadDir("../functions/", (name: string) =>
      console.log(`Module loaded: ${name}`)
    );
  }

Pretty straight forward, we added peg, parser, and 'fns' to handle our softcode additions. Next, we load the grammar file, generate a parser from it, and load all of the files located in src/functions/.

/**
   * Parse a string for syntax
   * @param code
   */
  parse(code: string) {
    try {
      return this.parser.parse(code);
    } catch (error) {
      throw error;
    }
  }

  /**
   * Add a new softcode function to the system
   * @param name The name of the function
   * @param func The code to be called when the function
   * name is matched.
   */
  add(name: string, func: MuFunction) {
    this.fns.set(name.toLowerCase(), func);
  }

parse will generate our AST to work with. Then we need to evaluate that tree:

/**
   * Evaluate a mushcode expression AST.
   * @param en The enacting DBObj
   * @param expr The expression to be evaluated
   * @param scope Any variables, substitutions or special forms
   * that affect the lifetime of the expression.
   */
  async evaluate(en: DBObj, expr: Expression, scope: Scope) {
    // First we need to see what kind of expression we're working with.
    // If it's a word, then check to see if it has special value in
    // scope, or if it's just a word.
    if (expr.type === "word") {
      expr.value = expr.value || "";
      if (scope[expr.value]) {
        return scope[expr.value];
      } else {
        // Sometimes variables in scope can be imbedded
        // in a line of text that the parser evaluator 
        // can't see - so we'll do a RegExp replace as well.
        let output = expr.value;
        for (const key in scope) {
          output = output.replace(
            new RegExp(key, "gi"), scope[key]
          );
        }
        return output;
      }
      // If the expression is a function...
    } else if (expr.type === "function") {
      const operator = expr.operator;

      // Make sure it's operator exists in the Map...
      if (operator.type === "word" && this.fns.has(operator.value)) {
        const func = this.fns.get(operator.value);
        if (func) {
          // Execute it and return the results.
          return await func(en, expr.args, scope);
        }
      }

      // If it's a list (operations seperated by square brackets)
      // Process each item in the list.
    } else if (expr.type === "list") {
      let output;
      for (let i = 0; i < expr.list!.length; i++) {
        output += await this.evaluate(en, expr.list![i], scope);
      }
      return output;
      // Else throw an error, unknown operation!
    } else {
      throw new Error("Unknown Expression.");
    }
  }

Expressions can come in two flavors: Just an expression, or an expression surrounded by brackets, embedded within a string of text. The second condition is a bit more verbose. :)

/**
   * Run the parser on the input string.
   * @param en the enacting DBObj
   * @param string The string to be run through the parser.
   * @param scope Any variables, substitutions or special forms
   * that affect the lifetime of the expression.
   */
  async run(en: DBObj, string: string, scope: Scope) {
    try {
      return await this.evaluate(en, this.parse(string), scope);
    } catch (error) {
      return await this.string(en, string, scope);
    }
  }

And then there's string() It basically scrubs through the string character by character looking for parentheses and square brackets.

  async string(en: DBObj, text: string, scope: Scope) {
    let parens = -1;
    let brackets = -1;
    let match = false;
    let workStr = "";
    let output = "";
    let start = -1;
    let end = -1;

    // Loop through the text looking for brackets.
    for (let i = 0; i < text.length; i++) {
      if (text[i] === "[") {
        brackets = brackets > 0 ? brackets + 1 : 1;
        start = start > 0 ? start : i;
        match = true;
      } else if (text[i] === "]") {
        brackets = brackets - 1;
      } else if (text[i] === "(") {
        parens = parens > 0 ? parens + 1 : 1;
      } else if (text[i] === ")") {
        parens = parens - 1;
      }

      // Check to see if brackets are evenly matched.
      // If so process that portion of the string and
      // replace it.
      if (match && brackets !== 0 && parens !== 0) {
        workStr += text[i];
      } else if (match && brackets === 0 && parens === 0) {
        // If the brackets are zeroed out, replace the portion of
        // the string with evaluated code.
        workStr += text[i];
        end = i;

        // If end is actually set (We made it past the first
        //character), then try to parse `workStr`.  If it 
        // won't parse (not an expression)
        // then run it through string again just to make sure.  
        // If /that/ fails? error.
        if (end) {
          let results = await this.run(en, workStr, scope)
            .catch(async () => {
              output += await this.string(en, workStr, scope)
               .catch(console.log);
            });
          // Add the results to the rest of the processed string.
          output += results;
        }

        // Reset the count variables.
        parens = -1;
        brackets = -1;
        match = false;
        start = -1;
        end = -1;
      } else {
        // HACK! If stray paren or bracket slips through, 
        // add it to `workStr`
        // else add it right to the output.  There's no code there.
        if (text[i].match(/[\[\]\(\)]/)) {
          workStr += text[i];
        } else {
          output += text[i];
        }
      }
    }
    // Return the evaluated text
    return output ? output : workStr;
  }
}

Next, we'll define a command that can handle expressions, and a function to example with! We'll use a classic: src/commands/think.ts

import cmds from "../api/commands";
import mu from "../api/mu";
import parser from "../api/parser";

export default () => {
  cmds.add({
    name: "think",
    flags: "connected",
    pattern: /think\s+?(.*)/i,
    exec: async (id: string, args: string[]) => {
      const en = mu.connMap.get(id);
      return await parser.run(en!, args[1], {});
    }
  });
};

Then we need to add our function to src/functions/math.ts:

import parser, { Expression, Scope } from "../api/parser";
import { DBObj } from "../api/database";

export default () => {
  // MATHS!

  /**
   * Add a list of numbers together!
   */
  parser.add("add", async (en: DBObj, args: any[], scope: Scope) => {
    let total = 0;
    for (const arg of args) {
      // We have to evaluate any argument we want to work
      // with, because it's still in expression AST form.  
      // It could be anything at this point. this will recursively
      // trigger each expression in the tree.
      total += parseInt(await parser.evaluate(en, arg, scope), 10);
    }
    return total.toString();
  });
};

And now, let's see it work all together. It's animated gif time!

I think that's where I'll wrap for this installment, woot! We only have a few base features left! Next time we'll cover grid commands (building/editing/destroying) so we can instantiate objects from within the mush!

Thanks for stopping in and surviving the read! Feel free to Follow me for updates, and or leave a comment!

Building A Modern MUSH With Typescript Part 5: Slaying the Databeast!

Lem Canady — Tue, 17 Mar 2020 22:15:20 +0000

Hello! Welcome back to my tutorial series where we're building a MUSH engine piece by piece. In Part 4 we covered creating the flag and file systems! In this installment, we're going to build an adapter for our database, and then implement it using NeDB.

Defining The Adapter

First things first, we need to define the database adapter. In the spirit of keeping UrsaMU extendable, I decided to go with an adapter pattern instead of just wiring the game up to a single database. We're going to define our adapter stub in src/api/mu.ts

export abstract class DbAdapter {
  abstract model(...args: any[]): any | Promise<any>;
  abstract get(...args: any[]): any | Promise<any>;
  abstract find(...args: any[]): any | Promise<any>;
  abstract create(...args: any[]): any | Promise<any>;
  abstract update(...args: any[]): any | Promise<any>;
  abstract delete(...args: any[]): any | Promise<any>;
}

Because it's an abstract class it's never meant to be called directly, instead any inheriting class will have to implement its methods.

Writing our Database Code - src/api/database.ts

Now we'll extend the adapter class and make a module for NeDB. In the future, we could swap the database out with anything we want, without affecting the game engine.

import DataStore from "nedb";
import { DbAdapter } from "./mu.ts";
import { resolve } from "path";

Here we're defining the shape of our NeDB data. We'll pass it as a type when we instantiate the game object database.

export interface DBObj {
  _id?: string;
  id: string;
  desc: string;
  name: string;
  type: "thing" | "player" | "room" | "exit";
  alias?: string;
  password?: string;
  attribites: Attribute[];
  flags: string[];
  location: string;
  contents: string[];
  exits?: string[];
  owner?: string;
}

Here, we use our first Generic! The T in NeDB<T> is a stand-in for whatever kind of type we want to check our typescript code against when manually entering new items into the database. You'll notice that T is used in places for our returns instead of a predefined type.

export class NeDB<T> implements DbAdapter {
  path?: string;
  db: DataStore | undefined;

  constructor(path?: string) {
    this.path = path || "";
  }

  /** create the database model  */
  model() {
    if (this.path) {
      this.db = new DataStore<T>({
        filename: this.path,
        autoload: true
      });
    } else {
      this.db = new DataStore<T>();
    }
  }

  /** Initialize the database */
  init() {
    this.model();
    console.log(`Database loaded: ${this.path}`);
  }

NeDB is callback-based, which is kind of a bummer - However! Making promises out of callbacks is easy! In fact, NodeJS has a way! But I thought for the sake of demonstration, I'd show how you go about converting your own functions. :)

/** Create a new DBObj */
  create(data: T): Promise<T> {
    return new Promise((resolve: any, reject: any) =>
      this.db?.insert(data, (err: Error, doc: T) => {
        if (err) reject(err);
        return resolve(doc);
      })
    );
  }

  /**
   * Get a single database document.
   * @param query The query object to search for.
   */
  get(query: any): Promise<T> {
    return new Promise((resolve: any, reject: any) =>
      this.db?.findOne<T>(query, (err: Error, doc: any) => {
        if (err) reject(err);
        return resolve(doc);
      })
    );
  }

  /**
   * Find an array of documents that match the query
   * @param query The query object.
   */
  find(query: any): Promise<T[]> {
    return new Promise((resolve: any, reject: any) =>
      this.db?.find<T>(query, (err: Error, docs: T[]) => {
        if (err) reject(err);
        return resolve(docs);
      })
    );
  }

  /**
   * Update fields of the NeDB database
   * @param query The NeDB query for the fields to be updated.
   * @param data The data to update with
   */
  update(query: any, data: T): Promise<T | T[]> {
    return new Promise((resolve: any, reject: any) =>
      this.db?.update(
        query,
        data,
        { returnUpdatedDocs: true },
        (err: Error, _, docs: T) => {
          if (err) return reject(err);
          return resolve(docs);
        }
      )
    );
  }

  /**
   * Delete a a field from the NeDB instance.
   * @param query The object to query against.
   */
  delete(query: any): Promise<number> {
    return new Promise((resolve: any, reject: any) =>
      this.db?.remove(query, {}, (err: Error, n: number) => {
        if (err) reject(resolve);
        return resolve(n);
      })
    );
  }
}

const db = new NeDB<DBObj>(resolve(__dirname, "../../data/ursa.db"));
db.init();
export default db;

Making the client!

I originally wrote this client as a stub in one file, before I had created (or needed) the static directories provided by ExpressJS. In the future, I want to make a MUCH more robust client using ReactJS. Perhaps that's another tutorial series in the making! But! For now! Here's what the client code looks like. First, our markup

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>UrsaMU Client</title>
    <link
      href="https://fonts.googleapis.com/css2?family=Source+Code+Pro:ital,wght@0,400;0,700;1,400;1,700&display=swap"
      rel="stylesheet"
    />
  </head>
  <body>
    <div id="container">
      <div id="input" contenteditable></div>
      <ul id="feed"></ul>
    </div>
  </body>

Nothing too out of the ordinary there! Now for some basic styling:

<style>
    * {
      color: white;
      background-color: black;
      font-family: "Source Code Pro", monospace;
      font-size: 1rem;
      margin: 0;
      padding: 0;
      top: 0;
      left: 0;
    }

    #container {
      display: flex;
      height: 95vh;
      max-width: 800px;
      margin-left: auto;
      margin-right: auto;
      box-sizing: border-box;
      flex-direction: column-reverse;
    }

    #input {
      border: 1px;
      border-style: solid;
      border-color: rgba(255, 255, 255, 0.4);
      border-radius: 5px;
      margin-top: 16px;
      min-height: 48px;
      max-height: 112px;
      overflow-y: auto;
      overflow-x: hidden;
    }

    ul {
      padding: 0;
      margin: 0;
    }

    ul li {
      list-style-type: none;
      padding: 0;
      margin: 0;
    }

    img {
      width: 100%;
      object-fit: cover;
    }

    p {
      padding-top: 4px;
      padding-bottom: 4px;
      font-weight: lighter;
    }

    strong {
      font-weight: bold;
    }

    .item {
      width: 100%;
      word-wrap: break-word;
    }
  </style>

And finally, the JavaScript! A note, the first script tag that imports socket.io.js is provided by our socket.io instance.

  <script src="/socket.io/socket.io.js"></script>

  <script>
    // Declare our variables.
    const feed = document.getElementById("feed");
    const socket = io("http://localhost:8090/");
    const input = document.getElementById("input");

    // Monitor keypresses.  If the user hits enter, send
    // the message off to the server!
    input.addEventListener("keypress", ev => {
      if (ev.keyCode === 13 && !ev.shiftKey) {
        ev.preventDefault();
        socket.send(input.innerText);
        input.innerText = "";
      }
    });

    // When a new message comes in, add it to the feed.

    socket.on("message", res => {
      const li = document.createElement("li");
      li.className = "item";
      console.log(res);
      li.innerHTML = res.message;
      feed.appendChild(li);
    });
  </script>
</html>

And now the moment we've all been waiting for: A screen cap gif! :D

There we have it! I think that's a good wrapping up point for this article. In our next installment we're going to add a few more commands to the system: Specifically character creation and connection commands to test out the shiny new database!

Thanks for stopping in! Make sure to Follow to get notifications on my future articles. Feel free to leave a comment!

Building A Modern MUSH With Typescript Part 4: Flags, Files, and clients - Oh my!

Lem Canady — Mon, 16 Mar 2020 18:51:52 +0000

Hello! If you've been following along? Thanks for coming back! Else Welcome to the series! in Part 3, We set up our command handling code - but it was missing the implementation of flags.ts Well today we'll cover that! As well as handling text files! We'll be ready to actually fire this thing up soon!

Creating `src/api/flags.ts`

The flags system enables permissions, behavior, or settings depending on if a flag is set or not. Note that I've referenced the database here which hasn't been set up yet - but I'll give you a hint at what we're covering soon! :)

import { game } from "../config/config.json";
import db, { DBObj } from "./database";

export interface Flag {
  name: string;
  code: string;
  lvl: number;
}

The actual Flags class is another singleton, because we only want one instance of the class running at a time.

export class Flags {
  private flags: Flag[];
  private static instance: Flags;
  private constructor() {
    this.flags = game.flags;
  }

  /**
   * Add a new flag to the system.
   * @param flg the Flag object to add
   */
  addFlag(flg: Flag) {
    this.flags.push(flg);
  }

  /**
   * Check to see if a flag exists.
   * @param flg The name of the flag to check
   */
  isFlag(flg: string) {
    return this.flags.map(flag => flag.name).indexOf(flg) ? true : false;
  }

  /**
   * Check to see if the given DBObj has the listed flags.
   * @param tar The target DBObj
   * @param flgs The list of flags to check against.
   */
  hasFlags(tar: DBObj, flgs: string) {
    return flgs
      .split(" ")
      .map(flag => (tar.flags.indexOf(flag) ? true : false))
      .indexOf(false)
      ? false
      : true;
  }

  /**
   * Add a flag to a DBObj.
   * @param tar The target DBObj
   * @param flg The flag to be added.
   */
  async setFlag(tar: DBObj, flg: string) {
    const flagSet = new Set(tar.flags);
    if (this.isFlag(flg)) {
      flagSet.add(flg);
      tar.flags = Array.from(flagSet);
      return await db.update({ _id: tar._id }, tar);
    }
    return false;
  }

  /**
   * Get the full name of a flag from a fragment.
   * Returns the first result.
   * @param flg The flag to get the name of
   */
  flagName(flg: string) {
    return this.flags
      .filter(flag => flag.name.match(new RegExp(flg, "i")))
      .map(flag => flag.name)[0];
  }

  /**
   * Remove a flag from a DBObj
   * @param tar The DBObj to remove the flag from
   * @param flag The flag to remove.
   */
  async remFlag(tar: DBObj, flag: string) {
    tar.flags = tar.flags.filter(flag => flag !== this.flagName(flag));
    return await db.update({ _id: tar._id }, tar);
  }

  /**
   * Find a character bit level (permission level).  
   * The higher the level, the more engine permissions.
   * @param tar The Target DBObj to compare.
   */
  private _bitLvl(tar: DBObj) {
    return this.flags
      .filter(flag => tar.flags.indexOf(flag.name))
      .map(flag => flag.lvl)
      .reduce((prev: number, curr: number) => (prev > curr ? prev : curr), 0);
  }

  /**
   * Check to see if the enactor has the permission level to modify
   * the target
   * @param en The enacting DBObj
   * @param tar The targeted DBObj
   */
  canEdit(en: DBObj, tar: DBObj) {
    return this._bitLvl(en) >= this._bitLvl(tar) ? true : false;
  }

  static getInstance() {
    if (!Flags.instance) Flags.instance = new Flags();
    return Flags.instance;
  }
}

export default flags.getInstance();

I didn't do a whole lot of intermittent commenting on this one - the file comments pretty much sum this one up. We're checking for, setting and removing flags with a couple of private helper functions. Please let me know if I need to break this code down further in the comments!

Creating `src/api/text.ts`

This is the code responsible for loading text files into memory for quick reference later during the lifecycle of the program. text.ts another singleton (There are quite a few in this project, whew!), instantiated only once.

import { readdirSync, readFileSync } from "fs";
import { resolve } from "path";

export interface FileInfo {
  name: string;
  text: string;
  category: string;
}

class TextFiles {
  private static instance: TextFiles
  private _index: FileInfo[];
  private constructor() {
    this._index = [];
  }

  /**
   * Load text files from a directory.
   * @param path The path to where the files are found.
   * @param category The base category for the files to load
   */
  load(path: string, category: string = "general") {
    const dir = readdirSync(resolve(__dirname, path), {
      encoding: "utf8",
      withFileTypes: true
    });

    // load files.
    dir.forEach(dirent => {
      if (dirent.isFile() && dirent.name.toLowerCase().endsWith(".md")) {
        const name = dirent.name?.split(".")[0].toLowerCase();
        const text = readFileSync(resolve(__dirname, path, dirent.name), {
          encoding: "utf8"
        });
        return this._index.push({ name, text, category });
      } else if (dirent.isDirectory()) {
        this.load(resolve(__dirname, path, dirent.name), dirent.name);
      }
    });
  }

  /**
   * Grab the contents of a stored text file.
   * @param name The name of the file to grab (without the extension)
   * @param category The file's category
   */
  get(name: string, category = "general") {
    const results = this._index.find(
      file =>
        file.name.toLowerCase() === name.toLowerCase() &&
        file.category.toLowerCase() === category.toLowerCase()
    );

    if (results) {
      return results.text;
    } else {
      return "";
    }
  }

  static getInstance(){
    if(!TextFiles.instance) TextFiles.instance = new TextFiles();
    return TextFiles.instance;
  }

}

export default TextFiles.getInstance();

Creating a Connect screen! (`text/connect.md`)

We'll have to modify our project structure just a little. From the root of your project:

mkdir text

Then we can define our simple connect screen. I plan on taking full advantage of markdown's ability to define HTML structure, like images! When the client is made, it should load our graphic!

![Alt Text!](images/ursamu_github_banner.png)

**Welcome To UrsaMU!**

This is an example server for the [UrsaMU](repo/not/ready) server.

To Create a new character, use `create <name> <password>`<br/>
To Connect to an existing character, use `connect <name> <password>`

Okay! I think that's enough for this post. In our next installment, we will work on making our database adapter, and also finally get the client made and boot this thing up!

Thanks for stopping in to read! Feel free to follow to keep up to date with my releases - I'm planning on an article every few days until the barebones are ready!

Writing a Modern MUSH server with Typescript Part 3: The Command Handler

Lem Canady — Fri, 13 Mar 2020 16:14:32 +0000

In Part 2 We set up socket.io on the server-side and created our basic input parsing middleware engine. In today's installment, we're going to create the command handling middleware and a couple of commands!

Before we begin we'll have to update our project structure just a bit. From your project root:

mkdir src/middleware
mkdir src/commands

Defining `src/api/commands.ts`, our In-Game Command Structure

The first thing we'll want to do is define the methods for handling the internals of a command. Note: We haven't defined flags yet, or utils we'll get to them soon!

import { types } from "util";
import { loadDir } from "./utils";
import mu from "./mu";
import { Marked } from "@ts-stack/markdown";

type Exec = (id: string, args: string[]) => Promise<string>;

export class MuCommand {
  private _pattern: RegExp | string;
  flags: string;
  name: string;
  exec: Exec;

  constructor({
    name,
    flags,
    pattern,
    exec
  }: {
    name: string;
    flags?: string;
    pattern: RegExp | string;
    exec: Exec;
  }) {
    this.name = name;
    this._pattern = pattern;
    this.flags = flags || "";
    this.exec = exec;
  }

Because I want users to be able to define in-game commands with both wildcard matching and regular expressions, I made a getter and setter for MuCommands. internally, the engine runs on regular expressions - so they need to be converted before being called by the command handling middleware.

  /**
   * Getter for the pattern.  Always return a regex string.
   */
  get pattern() {
    return types.isRegExp(this._pattern)
      ? this._pattern
      : this._globStringToRegex(this._pattern);
  }

  /**
   *  Set the pattern.
   */
  set pattern(str: string | RegExp) {
    this._pattern = str;
  }

Here's where the actual conversion process lives. It basically escapes out all special characters, before converting wildcard characters * and ? into regular expressions.

  /**
   * Convert a wildcard(glob) string to a regular expression.
   * @param str The string to convert to regex.
   */
  private _globStringToRegex(str: string) {
    return new RegExp(
      this._preg_quote(str)
        .replace(/\\\*/g, "(.*)")
        .replace(/\\\?/g, "(.)"),
      "gi"
    );
  }

  /**
   * Escape a string of characters to be Regex escaped.
   * @param str The string to convert to a regex statement.
   * @param delimiter The character to separate out words in
   * the string.
   */
  private _preg_quote(str: string, delimiter?: string) {
    // http://kevin.vanzonneveld.net
    // +   original by: booeyOH
    // +   improved by: Ates Goral (http://magnetiq.com)
    // +   improved by: Kevin van Zonneveld (http://kevin.vanzonneveld.net)
    // +   bugfixed by: Onno Marsman
    // +   improved by: Brett Zamir (http://brett-zamir.me)
    // *     example 1: preg_quote("$40");
    // *     returns 1: '\$40'
    // *     example 2: preg_quote("*RRRING* Hello?");
    // *     returns 2: '\*RRRING\* Hello\?'
    // *     example 3: preg_quote("\\.+*?[^]$(){}=!<>|:");
    // *     returns 3: '\\\.\+\*\?\[\^\]\$\(\)\{\}\=\!\<\>\|\:'
    return (str + "").replace(
      new RegExp(
        "[.\\\\+*?\\[\\^\\]$(){}=!<>|:\\" + (delimiter || "") + "-]",
        "g"
      ),
      "\\$&"
    );
  }
}

Now we can define the command management system! This is going to be another singleton, as we only want it to be instantiated once.

export class Commands {
  cmds: MuCommand[];
  private static instance: Commands;

  private constructor() {
    this.cmds = [];
    this.init();
  }

When the class initializes it attempts to load all of the files
from the given directory.

  /**
   * initialize the object.
   */
  init() {
    loadDir("../commands/", (name: string) =>
      console.log(`Module loaded: ${name}`)
    );
  }

  /**
   * Add a new command to the system.
   * @param command The command object to be added to the system
   */
  add({
    name,
    flags,
    pattern,
    exec
  }: {
    name: string;
    flags?: string;
    pattern: RegExp | string;
    exec: Exec;
  }) {
    const command = new MuCommand({ name, flags, pattern, exec });
    this.cmds.push(command);
  }

match is a little intimidating at first, but I'm basically chaining array functions together. First I map through the commands and test against the command's pattern. If a match is found it returns an object, else it returns false. Then I filter through that map to take out the false entries. Finally, I return the first match, just in case there's more than one.

  /**
   * Match a string to a command pattern.
   * @param str The string to match the command against.
   */
  match(str: string) {
    return this.cmds
      .map(cmd => {
        const matched = str.match(cmd.pattern);
        if (matched) {
          return {
            args: matched,
            exec: cmd.exec,
            flags: cmd.flags
          };
        } else {
          return;
        }
      })
      .filter(Boolean)[0];
  }

The force method allows us to skip the command matching and fire a command directly from the command handler.

  async force(id: string, name: string, args: string[] = []) {
    const response = {
      id,
      payload: {
        command: name,
        message: await this.cmds
          .filter(cmd => 
            cmd.name.toLowerCase() === name.toLowerCase()
           )[0]
          .exec(id, args)
      }
    };

    if (response.payload.message)
      response.payload.message = Marked.parse(response.payload.message);
    mu.io?.to(id).send(response.payload);
  }

  static getInstance() {
    if (!Commands.instance) Commands.instance = new Commands();
    return Commands.instance;
  }
}

export default Commands.getInstance();

An example command src/commands/test.ts:

import cmds from '../api/commands'

export default () => {
  cmds.add({
    name: "Test",
    pattern: /^[+@]?test$/g,
    exec: async (id: string, args: any[]) => "Made it!!"; });
}

Creating `src/middleware/commands.middleware.ts`

Now we can edit our command middleware. Again, flags aren't defined yet, but we'll get to that soon!

import { MiddlewareNext, MuRequest } from "../api/parser";
import cmds from "../api/commands";
import flags from "../api/flags";
import mu from "../api/mu";

Since the middleware is just a function, we'll export default the module with the required arguments.

export default async (req: MuRequest, next: MiddlewareNext) => {
  const id = req.socket.id;
  const message = req.payload.message || "";
  let matched = cmds.match(message);
  let flgs: Boolean;

Here I made a helper function expression to encapsulate the logic of matching flags (coming soon!) without having to make my main logic too spammy. This basically just checks a few conditions to make sure the enactor has the right permissions to use the command.

  const _hasFlags = () => {
    if (matched && mu.connMap.has(id)) {
      const char = mu.connMap.get(id);
      return flags.hasFlags(char!, matched.flags);
    } else {
      return false;
    }
  };

  if (matched && (!matched.flags || _hasFlags())) {
    // Matching command found!
    // run the command and await results
    const results = await matched
      .exec(id, matched.args)
      .catch((err: Error) => next(err, req));

    req.payload.matched = matched ? true : false;
    req.payload.message = results;
    return next(null, req);
  } else if (!mu.connMap.has(id)) {
    req.payload.matched = matched ? true : false;
    req.payload.message = "";
    return next(null, req);
  }

  return next(null, req);
};

And with that, our command handling code is done! In our next installment, we'll try to cover flags, text files, and building a simple client so we can check out our work so far!

Thanks for stopping in for the read! Feel free to follow, leave a comment, or discuss!

Writing a Modern MUSH Server with Typescript Part 2: The Input Parser

Lem Canady — Thu, 12 Mar 2020 15:39:27 +0000

In Part 1 of the tutorial series, we went over some basic setup for the project. We also addressed some of the overall goals for the UrsaMU project.

The Parser

First, we're going to setup the parser that will handle input from a socket, then we'll define the socket server and accompanying support code!

First, we need to define a couple of interfaces to act as contracts from what we expect the shape of our data to look like.

import { Socket } from "socket.io";
import { Marked } from "@ts-stack/markdown";
import text from "../api/text";

export type MiddlewareNext = (
  err: Error | null,
  req: MuRequest
) => Promise<any>;

export type MiddlewareLayer = (
  data: MuRequest,
  next: MiddlewareNext
) => Promise<MuResponse>;

export interface MuRequest {
  socket: Socket;
  payload: {
    command: string;
    message?: string;
    [key: string]: any;
  };
}
export interface MuResponse {
  id: string;
  payload: {
    command: string;
    message?: string;
    [key: string]: any;
  };
}

Now we define the Parser class itself. Like MU, this is meant to be a singleton, needed only once through the life of the process.

export class Parser {
  private stack: MiddlewareLayer[];
  private static instance: Parser;

  private constructor() {
    this.stack = [];
  }

  static getInstance(){
    if(!this.instance) this.instance = new Parser();
    return this.instance;
  }

This is the method that we're going to call to handle input from the sockets.

  async process(req: MuRequest): Promise<MuResponse> {
    const command = req.payload.command;
    const socket = req.socket;
    const message = req.payload.message;
    const data = req.payload.data;

    switch (command) {
      case "message":
        return this._handle(req);
      case "connect":
        return {
          id: socket.id,
          payload: {
            command: "message",
            message: text.get("connect")
              ? Marked.parse(text.get("connect"))
              : "File Not Found!"
          }
        };
      default:
        return {
          id: socket.id,
          payload: {
            command: "message",
            message
          }
        };
    }
  }

Here is where I've started to define the middleware system that will handle piping an input string through a series of transforms before returning the results to the client. It will use a next() function, like one would expect to see in ExpressJS. :)

  /**
   * Add a new middleware to the stack.
   * @param layer The layer to add to the middleware stack.
   */
  use(layer: MiddlewareLayer) {
    this.stack.push(layer);
  }

  /**
   * Run a string through a series of middleware.
   * @param req The request object to be pushed through the pipeline.
   */
  private async _handle(req: MuRequest): Promise<MuResponse> {
    let idx = 0;

Here's where it gets a little fun! We're going to make a recursive function expression. Every piece of software that goes through the middleware system will have to make sure to individually call next(), or the server will hang!

    /**
     * Recursive function to walk through each piece of
     * middleware in the stack.
     * @param err Any possible errors hit by the middleware.
     * @param data The string the middleware pipeline is going
     * to be working with
     */
    const next = async (
      err: Error | null,
      req: MuRequest
    ): Promise<MuResponse> => {
      // Return early if there's an error, or if we've processed through
      // the entire stack.
      if (err != null) return Promise.reject(err);
      if (idx === this.stack.length) {
        return {
          id: req.socket.id,
          payload: req.payload
        };
      }

      // Grab a new layer from the stack
      const layer = this.stack[idx++];
      // Run the layer
      return await layer(req, next);
    };

    // Return the modified data.
    return await next(null, req).catch((err: Error) => next(err, req));
  }
}

export default Parser.getInstance();

Updating MU

Now we're going to update mu.ts to handle the server traffic from the sockets and routing them to our parser system. We're going to add the following to the startup() method.

async start(callback?: () => void) {
    // Handle new client connections.
    this.io?.on("connection", async (socket: Socket) => {
      const { id, payload }: MuResponse = await parser.process({
        socket: socket,
        payload: {
          command: "connect"
        }
      });

      // Send the results back to the client.
      this.io?.to(id).send(payload);

      // When a new message comes from the client, process
      // it and return the results.
      socket.on("message", async (message: string) => {
        const { id, payload }: MuResponse = await parser.process({
          socket,
          payload: { command: "message", message }
        });

        // Send the results back to the client after converting
        // any markdown.
        if (payload.message) payload.message = Marked.parse(payload.message);
        this.io?.to(id).send(payload);
      });
    });

Well, that's it for today! We've made our middleware system, and handled our socket.io connections and client activity! Perfect! In the next installment, we'll create a piece of middleware to handle commands, define a command or two!

Thanks for stopping in for a read! please feel free to leave a comment, ask a question or just discuss!

Writing a Modern MUSH Server with Typescript Part 1: Overview and Setup

Lem Canady — Thu, 12 Mar 2020 00:18:49 +0000

Introduction

For a while now, I've wanted to start writing tutorials and create my own MUSH server with one of my new favorite language (flavors), Typescript! In this project, we'll learn a little bit of everything. While it won't be a comprehensive guide to the technologies - We'll be working with things like Typescript, TS-Node, Express, a NoSQL database, and Socket.io. We'll also have to make a simple client to our server.

Disclaimer!

There has been a real renaissance of interest in the modernization of servers written in C/C++ out there that are now, twenty or thirty years old. That's amazing! I grew up playing on these platforms, and they will forever hold a special place in my heart. There are other platforms out there that have sprung up in as a new generation of MUSHING. Two of the most notable are AresMUSH written in Ruby, and Evennia written in Python. Both really approachable languages, and both really excellent options! There is, of course, always room for another project!

Update! (3/23/20)

UrsaMU has become my quarantine sanity project, so I've revised it's inner workings some. I'll be slowly moving through the articles I've written to update the code portions to reflect the current build. I flattened the API some - I might even put it into a facade if it starts feeling cumbersome. So, sorry to any of you that were coding along with me, and thanks for the patience! :)

Enter UrsaMU: Project Set up

First things first, we need to make a new folder and set up our project with a package.json. You'll need to make sure that you have node + npm installed in your development environment. For this project, I'll be using Ubuntu 18.04 (through the Windows 10 WSL2) and VS Code as my Typescript IDE.

What is a MUSH?

Let's take a moment to discuss what a MUSH actually is, or, what I interpret a MUSH to be. At its core, a MUSH is a chat server backed by a database of some sort the persistence of in-game objects traditionally consisting of rooms, things, players and exits. When a user types input into the game, it's piped through a series of middlewares to evaluate for in-game actions, evaluating them and returning output to all involved parties. Another key selling point for MUSH is its ability for a user to create custom in-game commands and functions that are saved to specially keyed attributes. This allows for things like creating rooms, objects, exits, etc, and have all of the changes persisted in the database.

A MUSH is a Chat Server At It's Core.

This is where Socket.io comes into play. It'll act as the backbone of our chat server, while also handling things like 'rooms' and 'channels'.

A MUSH Is Backed By A Database for Persistence

For my purposes, I'm going to use a file-based database, NeDB. However, I don't want to limit what kind of database a game uses, or how they choose to store their data so we will focus on creating an adapter for all of the basic commands we'll need for our model (Create, Find, Get, Update, and Delete). We also want to allow other implementations to easily add functionality on top of our initial needs.

A MUSH Evaluates User Input for In-Game Actions.

This will be the primary focus of UrsaMajor. When an input is sent it needs to be evaluated as 'just a message', or if it has in-game significance, like an expression to evaluate, or some special action to take to affect the in-game environment. We will create a middleware system to handle user input, passing responsibility for the input down the line, function by function.

A MUSH Allows For In-Game Creation On The Fly

During our evaluation process, we'll have to check for commands that have been set on in-game objects. This probably means writing a simple algorithm to handle how actions are parsed, and mushcode expressions evaluated.

Planned Features

The working list for basic server features. UrsaMU Is still under extreme development, so this list is subject to shrink (Or grow!):

Database: Handle your data however you want! UrsaMU allows you to bring your favorite database to the table with its database adapter API.
Commands: Enter your own custom commands through the command API.
Flags The game's flags are editable from either the Flag API or through stored JSON flat files - or both!
MushCode: Evaluate mushcode expressions!
Attributes Store and evaluate and register commands and functions through MUSH-Like attributes api.
Grid Build a grid in-game, load rooms or entire pre-built areas from flat JSON files or both!
Input Middleware: The server allows for registering middleware to handle how in-game input.

File Structure

Before we begin, we need to set up our basic file structure for the project. First, I'll list all of the commands needed, then we'll break them down to examine what all of this is doing.

mkdir ursamu
cd ursamu

mkdir src
mkdir src/api
mkdir src/config

touch src/ursamu.ts
touch src/api/mu.ts
touch src/config/config.json
touch .gitignore

npm init -y

Then we create stubs for some files that we're going to be working with. Finally, we add our package.json with all of the defaults, which will do for now!

Dependencies

Next, we install the dependencies for our project. We will install the base packages first, before adding our development only npm calls.

npm install express socket.io nedb @ts-stack/markdown shortid
npm install -D typescript @types/node @types/socket.io @types/express @types/nedb  @types/shortid

While we're working on development, we're going to want a way to reload the server automatically and save us a few keystrokes in the process. For this, we're going to be using nodemon. And, as it's a tool I use on MULTIPLE projects, I tend to install it globally. On Linux, it means you need to elevate your permissions with sudo:

sudo npm install -g nodemon

And then set up our tsconfig.json file:

npx tsc -init

npx will call our local install of typescript, instead of installing typescript as a global command.

Our folder structure should now look something like this:

/ursamu
    /src
        /api
            - mu.ts
        /config
            - config.json
        - ursamu.ts
        - tsconfig.json
    - .gitignore
    - package.json

Now! We need to edit our package.json. First, we'll add our start scripts:


"scripts": {
    "prestart": "npx tsc -p ./src/tsconfig.json ./src/ursamu.ts", 
    "start": "node ./dist/ursamu.js",
    "start:watch": "nodemon"
  },

Finally, we need to add a nodemon config section to our package:

"nodemonConfig": {
    "ignore": [
      "**/*.test.ts",
      "**/*.spec.ts",
      ".git",
      "node_modules"
    ],
    "watch": [
      "src"
    ],
    "exec": "npm start",
    "ext": "ts"
  }

And last, we're going to add our config file into src/config/config.json.

{
  "game": {
    "port": 8090
  }
}

That was a bit of setup and exposition! Now let's move onto some code!

Our first step is going to set the MU class, which will handle a lot of the socket.io book-keeping and game startup methods. Notice the constructor is private, and instance is a static property. We're going to make the MU class into a Singleton. I could probably just get away with exporting an instance of the class, but this way future me (or you!) doesn't try to instantiate the class again!

import { EventEmitter } from "events";
import { Server, Socket } from "socket.io";
import { game } from "../config/config.json";

export class MU extends EventEmitter {
  io: Server | undefined;
  private static instance: MU;
  connMap: Map<string, DBObj>;

  private constructor() {
    super();
    this.io;
    this.connMap = new Map();
  }

  /**
   * Get an instance of the MU Class.
   */
  static getInstance() {
    if (!this.instance) {
      MU.instance = new MU();
    }

    return MU.instance;
  }

In order to keep track of our socket server from any other piece of the server we decide to call mu.ts from, it will have a stored instance of the server, using mu.attach().

 /**
   * Attach to a Socket.io  server implementation.
   * @param io The Socket.io server to attach too.
   */
  attach(io: Server) {
    this.io = io;
    return this;
  }

This is where we'll handle things like listeners for new data from
sockets, checking to make sure the starting room is built, etc. A nice facade for implementation details! :)

  /**
   * Start the game engine.
   * @param callback An optional function to execute when the
   * MU startup process ends
   */
  async start(callback?: () => void) {
    if (typeof callback === "function") callback();
  }
}

Then, I make a call to getInstance() for a new instance of the MU class, and share the object as the file's default export. Now, whenever it's imported from another file it'll be working with the same instance, and can't create another.

const mu = MU.getInstance();
export default mu;

Finally, we'll start our ursamu.ts main file, to see the code in action!

import express, { Request, Response } from "express";
import { Server } from "http";
import socketio from "socket.io";
import config from "./config/config.json";
import { resolve } from "path";
import ursamu from "./api/mu";

// Define the various communication channels.
const app = express();
const server = new Server(app);
const io = socketio(server);
const mu = ursamu.attach(io);

app.use(express.static("public"));

app.get("/", (req: Request, res: Response) =>
  res.sendFile(resolve(__dirname, "../public/index.html"))
);

mu.start(() =>
  server.listen(config.game.port, () => {
    console.log(`Server started on port: ${config.game.port}`);
  })
);

That should about do it for part one! Next installment we'll setup Socket.io and the parser! Feel free to follow to get updates on my articles and new posts! Also, feel free to leave a comment or post a question! :)

DEV Community: Lem Canady

Make A TypeScript Middleware Engine

Introduction

Typing

The Code

Building a Modern MUSH with Typescript Part 6: The Mushcode parser!

Making a Grammar

Disclaimer

The Grammar

Updating parser.ts

Building A Modern MUSH With Typescript Part 5: Slaying the Databeast!

Defining The Adapter

Writing our Database Code - src/api/database.ts

Making the client!

Building A Modern MUSH With Typescript Part 4: Flags, Files, and clients - Oh my!

Creating src/api/flags.ts

Creating src/api/text.ts

Creating a Connect screen! (text/connect.md)

Writing a Modern MUSH server with Typescript Part 3: The Command Handler

Defining src/api/commands.ts, our In-Game Command Structure

Creating src/middleware/commands.middleware.ts

Writing a Modern MUSH Server with Typescript Part 2: The Input Parser

The Parser

Updating MU

Writing a Modern MUSH Server with Typescript Part 1: Overview and Setup

Introduction

Disclaimer!

Update! (3/23/20)

Enter UrsaMU: Project Set up

What is a MUSH?

A MUSH is a Chat Server At It's Core.

A MUSH Is Backed By A Database for Persistence

A MUSH Evaluates User Input for In-Game Actions.

A MUSH Allows For In-Game Creation On The Fly

Planned Features

File Structure

Dependencies

That was a bit of setup and exposition! Now let's move onto some code!

Updating `parser.ts`

Creating `src/api/flags.ts`

Creating `src/api/text.ts`

Creating a Connect screen! (`text/connect.md`)

Defining `src/api/commands.ts`, our In-Game Command Structure

Creating `src/middleware/commands.middleware.ts`