Create fluent-sequence 0.1.0 (#273)

Author: stasm

fluent-sequence/.gitignore

@@ -0,0 +1,2 @@
+fluent-sequence.js
+compat.js

fluent-sequence/.npmignore

@@ -0,0 +1,3 @@
+docs
+test
+makefile

fluent-sequence/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## fluent-sequence 0.1.0 (August 17, 2018)
+
+The initial release based on `fluent` 0.7.0.

fluent-sequence/README.md

@@ -0,0 +1,65 @@
+# fluent-sequence
+
+`fluent-sequence` provides mapping functions from string identifiers to
+`MessageContext` instances taken from synchronous or asynchronous sequences.
+It's part of Project Fluent, a localization framework designed to unleash the
+expressive power of the natural language.
+
+
+## Installation
+
+`fluent-sequence` can be used both on the client-side and the server-side.
+You can install it from the npm registry or use it as a standalone script (as
+the `FluentSequence` global).
+
+    npm install fluent-sequence
+
+
+## How to use
+
+An ordered iterable of `MessageContext` instances can represent the current
+negotiated fallback chain of languages. This iterable can be used to find the
+best existing translation for a given identifier.
+
+`fluent-sequence` provides two mapping functions: `mapContextSync`, and
+`mapContextAsync`. They can be used to find the first `MessageContext` in the
+given iterable which contains the translation with the given identifier. If
+the iterable is ordered according to the result of a language negotiation the
+returned `MessageContext` contains the best available translation.
+
+A simple function which formats translations based on the identifier might
+be implemented as follows:
+
+```js
+import {mapContextSync} from "fluent-sequence";
+
+function formatString(id, args) {
+    // contexts is a negotiated iterable of MessageContext instances.
+    let ctx = mapContextSync(contexts, id);
+
+    if (ctx === null) {
+        return id;
+    }
+
+    let msg = ctx.getMessage(id);
+    return ctx.format(msg, args);
+}
+```
+
+When passing a synchronous iterator to `mapContextSync`, wrap it in
+`CachedSyncIterable` from the [`cached-iterable`][] package. When passing an
+asynchronous iterator to `mapContextAsync`, wrap it in `CachedAsyncIterable`.
+This allows multiple calls to `mapContext*` without advancing and eventually
+depleting the iterator.
+
+
+## Learn more
+
+Find out more about Project Fluent at [projectfluent.org][], including
+documentation of the Fluent file format ([FTL][]), links to other packages and
+implementations, and information about how to get involved.
+
+
+[`cached-iterable`]: https://www.npmjs.com/package/cached-iterable
+[projectfluent.org]: https://projectfluent.org
+[FTL]: https://projectfluent.org/fluent/guide/

fluent-sequence/makefile

@@ -0,0 +1,28 @@
+PACKAGE := fluent-sequence
+GLOBAL  := FluentSequence
+
+include ../common.mk
+
+build: $(PACKAGE).js compat.js
+
+$(PACKAGE).js: $(SOURCES)
+	@rollup $(CURDIR)/src/index.js \
+	    --config $(ROOT)/bundle_config.js \
+	    --banner "/* $(PACKAGE)@$(VERSION) */" \
+	    --amd.id $(PACKAGE) \
+	    --name $(GLOBAL) \
+	    --output.file $@
+	@echo -e " $(OK) $@ built"
+
+compat.js: $(SOURCES)
+	@rollup $(CURDIR)/src/index.js \
+	    --config $(ROOT)/compat_config.js \
+	    --banner "/* $(PACKAGE)@$(VERSION) */" \
+	    --amd.id $(PACKAGE) \
+	    --name $(GLOBAL) \
+	    --output.file $@
+	@echo -e " $(OK) $@ built"
+
+clean:
+	@rm -f $(PACKAGE).js compat.js
+	@echo -e " $(OK) clean"

fluent-sequence/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "fluent-sequence",
+  "description": "Manage ordered sequences of MessageContexts",
+  "version": "0.1.0",
+  "homepage": "https://projectfluent.org",
+  "author": "Mozilla <[email protected]>",
+  "license": "Apache-2.0",
+  "contributors": [
+    {
+      "name": "Zibi Braniecki",
+      "email": "[email protected]"
+    },
+    {
+      "name": "Staś Małolepszy",
+      "email": "[email protected]"
+    }
+  ],
+  "directories": {
+    "lib": "./src"
+  },
+  "main": "./fluent-sequence.js",
+  "module": "./src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/projectfluent/fluent.js.git"
+  },
+  "keywords": [
+    "fluent",
+    "ftl"
+  ],
+  "engines": {
+    "node": ">=8.9.0"
+  },
+  "devDependencies": {
+    "cached-iterable": "^0.2.1"
+  }
+}

fluent-sequence/src/index.js

@@ -0,0 +1,7 @@
+/*
+ * @module fluent-sequence
+ * @overview Manage ordered sequences of MessageContexts.
+ */
+
+export {default as mapContextSync} from "./map_sync";
+export {default as mapContextAsync} from "./map_async";

fluent-sequence/src/map_async.js

@@ -0,0 +1,36 @@
+/*
+ * Asynchronously map an identifier or an array of identifiers to the best
+ * `MessageContext` instance(s).
+ *
+ * @param {AsyncIterable} iterable
+ * @param {string|Array<string>} ids
+ * @returns {Promise<MessageContext|Array<MessageContext>>}
+ */
+export default async function mapContextAsync(iterable, ids) {
+  if (!Array.isArray(ids)) {
+    for await (const context of iterable) {
+      if (context.hasMessage(ids)) {
+        return context;
+      }
+    }
+  }
+
+  let remainingCount = ids.length;
+  const foundContexts = new Array(remainingCount).fill(null);
+
+  for await (const context of iterable) {
+    for (const [index, id] of ids.entries()) {
+      if (!foundContexts[index] && context.hasMessage(id)) {
+        foundContexts[index] = context;
+        remainingCount--;
+      }
+
+      // Return early when all ids have been mapped to contexts.
+      if (remainingCount === 0) {
+        return foundContexts;
+      }
+    }
+  }
+
+  return foundContexts;
+}

fluent-sequence/src/map_sync.js

@@ -0,0 +1,30 @@
+/*
+ * Synchronously map an identifier or an array of identifiers to the best
+ * `MessageContext` instance(s).
+ *
+ * @param {Iterable} iterable
+ * @param {string|Array<string>} ids
+ * @returns {MessageContext|Array<MessageContext>}
+ */
+export default function mapContextSync(iterable, ids) {
+  if (!Array.isArray(ids)) {
+    return getContextForId(iterable, ids);
+  }
+
+  return ids.map(
+    id => getContextForId(iterable, id)
+  );
+}
+
+/*
+ * Find the best `MessageContext` with the translation for `id`.
+ */
+function getContextForId(iterable, id) {
+  for (const context of iterable) {
+    if (context.hasMessage(id)) {
+      return context;
+    }
+  }
+
+  return null;
+}

fluent/test/fallback_async_test.js renamed to fluent-sequence/test/fallback_async_test.js

@@ -1,8 +1,8 @@
 import assert from 'assert';
 
-import { CachedAsyncIterable } from 'cached-iterable';
+import {CachedAsyncIterable} from 'cached-iterable';
 import MessageContext from './message_context_stub';
-import { mapContextAsync } from '../src/index';
+import {mapContextAsync} from '../src/index';
 
 suite('Async Fallback — single id', function() {
   let ctx1, ctx2, generateMessages;

fluent/test/fallback_sync_test.js renamed to fluent-sequence/test/fallback_sync_test.js

@@ -1,8 +1,8 @@
 import assert from 'assert';
 
-import { CachedSyncIterable } from 'cached-iterable';
+import {CachedSyncIterable} from 'cached-iterable';
 import MessageContext from './message_context_stub';
-import { mapContextSync } from '../src/index';
+import {mapContextSync} from '../src/index';
 
 suite('Sync Fallback — single id', function() {
   let ctx1, ctx2;

fluent-sequence/test/message_context_stub.js

@@ -0,0 +1,19 @@
+export default class MessageContext {
+  _setMessages(ids) {
+    this.ids = ids;
+  }
+
+  hasMessage(id) {
+    return this.ids.includes(id);
+  }
+
+  getMessage(id) {
+    if (this.hasMessage(id)) {
+      return id.toUpperCase();
+    }
+  }
+
+  format(msg) {
+    return msg;
+  }
+}

fluent/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+  - Move `mapContext*` functions to `fluent-sequence`. (#273)
+
+    The `mapContextSync` and `mapContextAsync` functions previously exported
+    by the `fluent` package have been moved to the new `fluent-sequence`
+    package. `fluent-sequence` 0.1.0 corresponds to the exact implementation
+    of these functions from `fluent` 0.7.0.
+
 ## fluent 0.7.0 (July 24, 2018)
 
   - Implement support for Fluent Syntax 0.6.

fluent/package.json

@@ -44,7 +44,6 @@
     "node": ">=8.9.0"
   },
   "devDependencies": {
-    "cached-iterable": "^0.2.1",
     "sinon": "^4.2.2"
   }
 }