Prep API and README for testing article (#200)

* Prep API and README for testing article

There is an article in the works that references the LDAP simulator as
a solution to testing a backstage server. Unfortunately, we don't have
a README, and so the [NPM package
homepage](https://www.npmjs.com/package/@simulacrum/ldap-simulator/v/0.4.0)
looks quite bad.

This adds a basic readme and shows how to start an LDAP server from
both a vanilla JavaScript context as well from an Effection
context. There is a third way, which is via a simulacrum server, but
this does not add that since it's a bit more fiddly, likely to change,
and not relevant for the content of the blog post.

It also adds the actual vanilla javascript integration since it didn't
exist before (it just wraps the resource in a run);

* Code formatting was broken

Co-authored-by: Taras Mankovski <taras@frontside.com>

Author: cowboyd

.changes/ldap-readme.md

@@ -0,0 +1,5 @@
+---
+"@simulacrum/ldap-simulator": minor
+---
+Add a README to the NPM package as well as an async api around an LDAP server
+resource

packages/ldap/README.md

@@ -0,0 +1,77 @@
+# @simulacrum/ldap-simulator
+
+Simulate an actual LDAP server for testing and development.
+
+Often you are working on software that depends on the presence of an
+LDAP directory. This let's you create an LDAP server in a known state
+that can be used for offline development and testing.
+
+There are two different ways to start an LDAP simulator, but they both involve
+the same set of options. If you are running in a vanilla JavaScript
+environment, you can use promise-based API.
+
+## Plain JavaScript
+
+```js
+import { runLDAPServer } from "@simulacrum/ldap-simulator";
+
+async function run() {
+  let server = await runLDAPServer({
+    port: 3890,
+    baseDN: "ou=users,dc=org.com",
+    bindDn: "admin@org.com",
+    bindPassword: "password",
+    groupDN:"ou=groups,dc=org.com",
+    users: [{
+      //required
+      cn: 'Charles Lowell',
+      //optional to bind using this user
+      password: "super-secret-but-not-really",
+      //optional:
+      uid: 'cowboyd',
+
+    }]
+  });
+  console.log(`LDAP server running on ${server.port}`);
+  try {
+    //.... do some stuff;
+  } finally {
+    // don't forget to release the server resources!
+    await server.close();
+  }
+}
+```
+
+## Effection
+
+However, if you are already using [Effection][effection], the LDAP
+server is available as a [Resource][resource], and so you can use it
+freely in any context:
+
+```js
+import { createLDAPServer } from "@simulacrum/ldap-simulator";
+
+function* run() {
+  let server = yield runLDAPServer({
+    port: 3890,
+    baseDN: "ou=users,dc=org.com",
+    bindDn: "admin@org.com",
+    bindPassword: "password",
+    groupDN:"ou=groups,dc=org.com",
+    users: [{
+      //required
+      cn: 'Charles Lowell',
+      //optional to bind using this user
+      password: "super-secret-but-not-really",
+      //optional:
+      uid: 'cowboyd',
+
+    }]
+  });
+
+  //... do some stuff
+}
+```
+
+[effection]: https://frontside.com/effection
+[resource]: https://frontside.com/effection/docs/guides/resources

packages/ldap/src/index.ts

@@ -1,5 +1,6 @@
 import type { SearchRequest, Server, SearchResponse, CompareRequest, CompareResponse, BindResponse, BindRequest } from 'ldapjs';
 import type { Operation } from 'effection';
+import { run } from 'effection';
 import { createServer, InvalidCredentialsError, NoSuchObjectError, OperationsError } from 'ldapjs';
 import type { LDAPOptions, LDAPStoreOptions, Port, UserData } from './types';
 import type { SimulationState, Simulator } from '@simulacrum/server';
@@ -166,6 +167,22 @@ UserBaseDN:    ${bindDn}
   };
 }
 
+export interface Close {
+  close(): Promise<void>;
+}
+
+/**
+ * Wraps an LDAP server resource into an Promise based API
+ */
+export async function runLDAPServer<T extends UserData>(options: LDAPOptions & LDAPStoreOptions<T>): Promise<Server & Port & Close> {
+  let task = run(createLDAPServer(options));
+  let server = await task;
+  return Object.create(server, {
+    close: { value: () => task.halt() }
+  });
+
+}
+
 export function createLdapService<T extends UserData>(options: LDAPOptions, state: Slice<SimulationState>): ResourceServiceCreator {
   return () => {
     let users = {