Forem: Dirisu Jesse

Unlocking improved Flutter performance; a case for Keys

Dirisu Jesse — Fri, 01 Nov 2024 22:10:38 +0000

We recently wrote an app akin to Instagram but for pets, for such apps, list views permitting doom scrolling till infinity are critical. Unfortunately we hit an unexpected performance bottle neck here, try as we might, nothing we did fixed the very noticeable jank when users scrolled up the said list.

After days of debugging, we found scroll performance to be normal when styled_text was replaced with the vanilla Text widget. Ordinarily this would have led to removing said package, but it is so useful for presenting complex rich text, that we considered it worthwhile attempting a refactor. Thus we proceeded to review the codebase for the package, and immediately 2 hypothesis for the suboptimal performance occurred to us; namely:

The use of function based widgets caused incessant rebuilds; widgets returned by functions constitute unique instances requiring a fresh build/paint.

Keys were not assigned to the widgets presenting the parsed text; We believe that if a widget with a specified key is not marked for build, it may not be redrawn in the next frame.

These suggest a potentially simple fix, and informed our 2 step strategy. Firstly we refactored the function based widgets into separate classes, StyledRichText for the non selectable form and StyledSelectableText for the selectable form.

// Non Selectable RichText
...

class StyledRichText extends StatelessWidget {
  final TextSpan textSpan;
  final TextAlign? textAlign;
  final TextDirection? textDirection;
  final bool? softWrap;
  final TextOverflow? overflow;
  final TextScaler textScaler;
  final int? maxLines;
  final Locale? locale;
  final StrutStyle? strutStyle;
  final TextWidthBasis? textWidthBasis;
  final ui.TextHeightBehavior? textHeightBehavior;

  const StyledRichText(
    this.textSpan, {
    super.key,
    Map<String, StyledTextTagBase>? tags,
    this.textAlign,
    this.textDirection,
    this.softWrap = true,
    this.overflow,
    required this.textScaler,
    this.maxLines,
    this.locale,
    this.strutStyle,
    this.textWidthBasis,
    this.textHeightBehavior,
  });

  @override
  Widget build(BuildContext context) {
    final defaultTextStyle = DefaultTextStyle.of(context);
    final registrar = SelectionContainer.maybeOf(context);

    Widget result = RichText(
      textAlign: textAlign ?? defaultTextStyle.textAlign ?? TextAlign.start,
      textDirection: textDirection,
      softWrap: softWrap ?? defaultTextStyle.softWrap,
      overflow:
          overflow ?? textSpan.style?.overflow ?? defaultTextStyle.overflow,
      textScaler: textScaler,
      maxLines: maxLines ?? defaultTextStyle.maxLines,
      locale: locale,
      strutStyle: strutStyle,
      textWidthBasis: textWidthBasis ?? defaultTextStyle.textWidthBasis,
      textHeightBehavior: textHeightBehavior ??
          defaultTextStyle.textHeightBehavior ??
          DefaultTextHeightBehavior.maybeOf(context),
      text: textSpan,
      selectionRegistrar: registrar,
      selectionColor: DefaultSelectionStyle.of(context).selectionColor,
    );

    if (registrar != null) {
      result = MouseRegion(
        cursor: SystemMouseCursors.text,
        child: result,
      );
    }

    return result;
  }
}

// Selectable Styled Text
...

class StyledSelectableText extends StatelessWidget {
  ...

  const StyledSelectableText(
    this.textSpan, {
    super.key,
    Map<String, StyledTextTagBase>? tags,
    this.textAlign,
    this.textDirection,
    this.textScaler,
    this.maxLines,
    this.strutStyle,
    this.textWidthBasis,
    this.textHeightBehavior,
    FocusNode? focusNode,
    bool showCursor = false,
    bool autofocus = false,
    @Deprecated(
      'Use `contextMenuBuilder` instead. '
      'This feature was deprecated after Flutter v3.3.0-0.5.pre.',
    )
    // ignore: deprecated_member_use
    ToolbarOptions? toolbarOptions,
    EditableTextContextMenuBuilder? contextMenuBuilder,
    TextSelectionControls? selectionControls,
    ui.BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight,
    ui.BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight,
    SelectionChangedCallback? onSelectionChanged,
    TextMagnifierConfiguration? magnifierConfiguration,
    double cursorWidth = 2.0,
    double? cursorHeight,
    Radius? cursorRadius,
    Color? cursorColor,
    DragStartBehavior dragStartBehavior = DragStartBehavior.start,
    bool enableInteractiveSelection = true,
    GestureTapCallback? onTap,
    ScrollPhysics? scrollPhysics,
    String? semanticsLabel,
  })  : this._focusNode = focusNode,
        this._showCursor = showCursor,
        this._autofocus = autofocus,
        this._toolbarOptions = toolbarOptions ??
            // ignore: deprecated_member_use
            const ToolbarOptions(
              selectAll: true,
              copy: true,
            ),
        this._contextMenuBuilder = contextMenuBuilder,
        this._selectionHeightStyle = selectionHeightStyle,
        this._selectionWidthStyle = selectionWidthStyle,
        this._selectionControls = selectionControls,
        this._onSelectionChanged = onSelectionChanged,
        this._magnifierConfiguration = magnifierConfiguration,
        this._cursorWidth = cursorWidth,
        this._cursorHeight = cursorHeight,
        this._cursorRadius = cursorRadius,
        this._cursorColor = cursorColor,
        this._dragStartBehavior = dragStartBehavior,
        this._enableInteractiveSelection = enableInteractiveSelection,
        this._onTap = onTap,
        this._scrollPhysics = scrollPhysics,
        this._semanticsLabel = semanticsLabel;

  ...

  @override
  Widget build(BuildContext context) {
    return SelectableText.rich(
      textSpan,
      focusNode: _focusNode,
      showCursor: _showCursor,
      autofocus: _autofocus,
      // ignore: deprecated_member_use
      toolbarOptions: _toolbarOptions,
      contextMenuBuilder: _contextMenuBuilder ?? _defaultContextMenuBuilder,
      selectionControls: _selectionControls,
      selectionHeightStyle: _selectionHeightStyle!,
      selectionWidthStyle: _selectionWidthStyle!,
      onSelectionChanged: _onSelectionChanged,
      magnifierConfiguration: _magnifierConfiguration,
      cursorWidth: _cursorWidth!,
      cursorHeight: _cursorHeight,
      cursorRadius: _cursorRadius,
      cursorColor: _cursorColor,
      dragStartBehavior: _dragStartBehavior,
      enableInteractiveSelection: _enableInteractiveSelection,
      onTap: _onTap,
      scrollPhysics: _scrollPhysics,
      textWidthBasis: textWidthBasis,
      textHeightBehavior: textHeightBehavior,
      textAlign: textAlign,
      textDirection: textDirection,
      textScaler: textScaler,
      maxLines: maxLines,
      strutStyle: strutStyle,
      semanticsLabel: _semanticsLabel,
    );
  }
}

Then we assigned the widgets keys, to identify them in the element tree, preventing rebuilds if not marked for build (denoted as dirty). We settled on using ValueKeys based off the value of the text field of the StyledText class. ValueKeys can take any licit dart Object as its constructor argument, however Key accepts only String objects, this makes them more flexible. Internally the apparent constructor for Key instantiates an instance of ValueKey<String>.

@immutable
@pragma('flutter:keep-to-string-in-subtypes')
abstract class Key {
  /// Construct a [ValueKey<String>] with the given [String].
  ///
  /// This is the simplest way to create keys.
  const factory Key(String value) = ValueKey<String>;

  /// Default constructor, used by subclasses.
  ///
  /// Useful so that subclasses can call us, because the [Key.new] factory
  /// constructor shadows the implicit constructor.
  @protected
  const Key.empty();
}

Consequently the StyledText widget was transformed into the following:

...

 const StyledText({
    super.key,
    required this.text,
    this.newLineAsBreaks = true,
    this.style,
    Map<String, StyledTextTagBase>? tags,
    this.textAlign,
    this.textDirection,
    this.softWrap = true,
    this.overflow,
    this.textScaleFactor,
    this.textScaler,
    this.maxLines,
    this.locale,
    this.strutStyle,
    this.textWidthBasis,
    this.textHeightBehavior,
    this.parseAsynchronously = false,
  })  : this.tags = tags ?? const {},
        this.selectable = false,
        this._focusNode = null,
        this._showCursor = false,
        this._autofocus = false,
        this._toolbarOptions = null,
        this._contextMenuBuilder = null,
        this._selectionControls = null,
        this._selectionHeightStyle = null,
        this._selectionWidthStyle = null,
        this._onSelectionChanged = null,
        this._magnifierConfiguration = null,
        this._cursorWidth = null,
        this._cursorHeight = null,
        this._cursorRadius = null,
        this._cursorColor = null,
        this._dragStartBehavior = DragStartBehavior.start,
        this._enableInteractiveSelection = false,
        this._onTap = null,
        this._scrollPhysics = null,
        this._semanticsLabel = null,
        assert(!(textScaleFactor != null && textScaler != null));

 ...
  const StyledText.selectable({
    super.key,
    required this.text,
    this.newLineAsBreaks = false,
    this.style,
    Map<String, StyledTextTagBase>? tags,
    this.textAlign,
    this.textDirection,
    this.textScaleFactor,
    this.textScaler,
    this.maxLines,
    this.strutStyle,
    this.textWidthBasis,
    this.textHeightBehavior,
    FocusNode? focusNode,
    bool showCursor = false,
    bool autofocus = false,
    this.parseAsynchronously = false,
    @Deprecated(
      'Use `contextMenuBuilder` instead. '
      'This feature was deprecated after Flutter v3.3.0-0.5.pre.',
    )
    // ignore: deprecated_member_use
    ToolbarOptions? toolbarOptions,
    EditableTextContextMenuBuilder contextMenuBuilder =
        _defaultContextMenuBuilder,
    TextSelectionControls? selectionControls,
    ui.BoxHeightStyle selectionHeightStyle = ui.BoxHeightStyle.tight,
    ui.BoxWidthStyle selectionWidthStyle = ui.BoxWidthStyle.tight,
    SelectionChangedCallback? onSelectionChanged,
    TextMagnifierConfiguration? magnifierConfiguration,
    double cursorWidth = 2.0,
    double? cursorHeight,
    Radius? cursorRadius,
    Color? cursorColor,
    DragStartBehavior dragStartBehavior = DragStartBehavior.start,
    bool enableInteractiveSelection = true,
    GestureTapCallback? onTap,
    ScrollPhysics? scrollPhysics,
    String? semanticsLabel,
  })  : this.tags = tags ?? const {},
        this.selectable = true,
        this.softWrap = true,
        this.overflow = TextOverflow.clip,
        this.locale = null,
        this._focusNode = focusNode,
        this._showCursor = showCursor,
        this._autofocus = autofocus,
        this._toolbarOptions = toolbarOptions ??
            // ignore: deprecated_member_use
            const ToolbarOptions(
              selectAll: true,
              copy: true,
            ),
        this._contextMenuBuilder = contextMenuBuilder,
        this._selectionHeightStyle = selectionHeightStyle,
        this._selectionWidthStyle = selectionWidthStyle,
        this._selectionControls = selectionControls,
        this._onSelectionChanged = onSelectionChanged,
        this._magnifierConfiguration = magnifierConfiguration,
        this._cursorWidth = cursorWidth,
        this._cursorHeight = cursorHeight,
        this._cursorRadius = cursorRadius,
        this._cursorColor = cursorColor,
        this._dragStartBehavior = dragStartBehavior,
        this._enableInteractiveSelection = enableInteractiveSelection,
        this._onTap = onTap,
        this._scrollPhysics = scrollPhysics,
        this._semanticsLabel = semanticsLabel;

...

  @override
  Widget build(BuildContext context) {
    ...

    return CustomStyledText(
      key: ValueKey(text),
      style: style,
      newLineAsBreaks: newLineAsBreaks,
      text: text,
      tags: tags,
      builder: (BuildContext context, TextSpan textSpan) {
        if (!selectable) {
          return StyledRichText(
            textSpan,
            textScaler: effectiveTextScaler,
            textAlign: textAlign,
            textDirection: textDirection,
            softWrap: softWrap,
            overflow: overflow,
            maxLines: maxLines,
            locale: locale,
            strutStyle: strutStyle,
            textWidthBasis: textWidthBasis,
            textHeightBehavior: textHeightBehavior,
            key: ValueKey("$text-plain-rich"),
          );
        }
        return StyledSelectableText(
          textSpan,
          focusNode: _focusNode,
          showCursor: _showCursor,
          autofocus: _autofocus,
          // ignore: deprecated_member_use, deprecated_member_use_from_same_package
          toolbarOptions: _toolbarOptions,
          contextMenuBuilder: _contextMenuBuilder,
          selectionControls: _selectionControls,
          selectionHeightStyle: _selectionHeightStyle!,
          selectionWidthStyle: _selectionWidthStyle!,
          onSelectionChanged: _onSelectionChanged,
          magnifierConfiguration: _magnifierConfiguration,
          cursorWidth: _cursorWidth!,
          cursorHeight: _cursorHeight,
          cursorRadius: _cursorRadius,
          cursorColor: _cursorColor,
          dragStartBehavior: _dragStartBehavior,
          enableInteractiveSelection: _enableInteractiveSelection,
          onTap: _onTap,
          scrollPhysics: _scrollPhysics,
          textWidthBasis: textWidthBasis,
          textHeightBehavior: textHeightBehavior,
          textAlign: textAlign,
          textDirection: textDirection,
          textScaler: effectiveTextScaler,
          maxLines: maxLines,
          strutStyle: strutStyle,
          semanticsLabel: _semanticsLabel,
          key: ValueKey("$text-selectable-rich"),
        );
      },
      textParserBuilder: (onTag, onParsed) {
        if (!parseAsynchronously) {
          return StyledTextParserSync(onTag: onTag, onParsed: onParsed);
        }
        return StyledTextParserAsync(onTag: onTag, onParsed: onParsed);
      },
    );
  }
}

These rather minor changes resulted in noticeable performance improvements as shown below:

The performance improvement is undeniable, scrolling up is smoother, no longer does the scroll position jump as a result of concurrent builds. The simple act of adding keys to widgets improved performance by:

helping the Flutter Engine associate a specific identifier, to the element configured by the widget in the element tree during traversal
thereby preventing unnecessary rebuilds if not marked for a build
key essentially memoises widget rendering under the right circumstances

We hope that we have convincingly highlighted the importance of keys to flutter widgets, proving them to be key performance improvement tools. The repository containing the refactor resides here, thanks very much for your time.

URL Expansion with Dart

Dirisu Jesse — Sat, 02 Sep 2023 12:46:16 +0000

A few months ago, I was proud to announce during a team meeting that I had successfully deployed the deeplinking service for a Flutter app we were developing. However, just a few days later, I was jolted awake in the middle of the night by a flurry of Slack alerts. The deeplinking service was down, and customers couldn't pay using our payment links! Although I had thoroughly tested the service, I hadn't accounted for one thing: our recent switch to using shortened URLs through an Iterable SMS campaign.

In this article, I will share the solution that finally fixed the deeplinking service's shortcomings. We'll dive into how we developed a URL expander app using Dart's HttpClient class, making our service more robust and reliable. First, we'll outline the app's structure, explaining its purpose and how it works. Then, we'll provide some practical usage examples to give you a clearer understanding of its capabilities. We'll also identify some initial limitations that we needed to address to make the tool more effective.

Next, we'll go through the steps of unit testing the app, ensuring that it meets our requirements and behaves as expected. Unit tests are crucial for confirming that the code functions properly, especially when changes are made in the future. Through this journey, we aim to provide you with a comprehensive understanding of how to tackle issues like the one we faced with deeplinking, thereby improving your own development practices.

What is a URL expander?

We are likely very familiar with URL shortening services like bit.ly which allow for users to generate shorter (sometimes custom, meaningful) URLs from long and potentially unwieldy URLs. However the task of resolving the original links is trivialised by modern browsers, which often resolve to original urls automatically, thus little attention is often paid to URL expansion.

However, in non-browser environments, like a Flutter mobile app, automatic URL resolution isn't a given. In these contexts, URL expanders become essential. You can think of a URL expander as a tool or service that resolves a shortened URL back to its original, longer form. In this article, we'll walk you through how to implement such a URL expander.

The URL Expander

Our URL Expander is implemented as a Dart CLI app exposing a utility via which shortened URLs may be expanded to their original form.

Overview of URL Expander App

The structure of the App patterns in agreement with the template for dart CLI apps as highlighted below.

.
├── CHANGELOG.md
├── README.md
├── analysis_options.yaml
├── bin
│   └── url_expander.dart
├── build
│   ├── test_cache
│   │   └── build
│   │       └── c075001b96339384a97db4862b8ab8db.cache.dill.track.dill
│   └── unit_test_assets
│       ├── AssetManifest.bin
│       ├── AssetManifest.json
│       ├── FontManifest.json
│       ├── NOTICES.Z
│       └── shaders
│           └── ink_sparkle.frag
├── coverage
│   ├── coverage.json
│   └── lcov.info
├── lib
│   └── url_expander.dart
├── pubspec.lock
├── pubspec.yaml
├── test
│   └── url_expander_test.dart
└── tree.txt

9 directories, 17 files

Steps to Url Expansion

Get input URL (shortened).
Get input base URL for expected expanded URL.
Validate input URL.
IF input URL is invalid throw an exception; else
Open a HTTP HEAD request to fetch headers associated with the URL
Close request to receive resolved headers.
Extract location header from the response
IF location header is not found then throw an exception; else
Validate the location against the expected base URL for the expansion of input URL
IF validation fails for location but there is a redirect in the response; recursively goto 1; decrease times we can goto 1; else
IF validation fails and there is no redirect throw an exception; else
IF validation is successful for location return it as expanded URL

The UrlExpander encapsulates these steps, the UrlExpander class is described in greater detail in the following section.

The `UrlExpander` class

The UrlExpander class is the central functional unit of our app. The UrlExpander class exposes a public method getFullUrl, a wrapper to the encapsulated _extractFullUrl method. The UrlExpander class also encapsulates the _client variable (it's HttpClient instance). The _isValidUrl method and the _isValidFullUrl method, which serve as checks and guards for licit expansions.

import 'dart:developer';
import 'dart:io';

class UrlExpander {
  final HttpClient _client = HttpClient();

  Future<String> getFullUrl(
    String url, {
    required String expandedBaseUrl,
  }) async {
    try {
      return await _extractFullUrl(url, expandedBaseUrl);
    } catch (e, t) {
      log('$e', error: e, stackTrace: t);
      throw Exception(e);
    }
  }

  _extractFullUrl(
    String url,
    String expandedBaseUrl, [
    int iterationsAllowed = 5,
  ]) async {
    try {
      if (!(iterationsAllowed >= 1)) throw "Max redirect limit reached";
      if (!_isValidUrl(url)) throw "Invalid URL";

      final uri = Uri.parse(url);

      final request = await _client.headUrl(uri);
      request.followRedirects = false;

      final response = await request.close();

      stdout.write(
          "\x1B[32m========\nHEADERS\n=========\n${response.headers}\n==========\x1B[0m\n");

      final fullUrl = response.headers.value(HttpHeaders.locationHeader);

      if ((fullUrl ?? '').isEmpty) throw "URL not found";

      final isValidUrl = _isValidFullUrl(
        fullUrl,
        expandedBaseUrl,
      );

      if (!isValidUrl && response.isRedirect) {
        return await _extractFullUrl(
          fullUrl!,
          expandedBaseUrl,
          --iterationsAllowed,
        );
      }

      if (!isValidUrl) throw 'Cannot fetch expanded URL';

      return fullUrl!;
    } catch (_) {
      rethrow;
    }
  }

  bool _isValidUrl(String? url) {
    if (url != null && Uri.tryParse(url) != null) {
      final RegExp urlRegex = RegExp(
        r"\b[(http(s)?):\/\/(www\.)?a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)\b",
        caseSensitive: false,
      );

      return urlRegex.hasMatch(url);
    }

    return false;
  }

  bool _isValidFullUrl(String? url, String baseUrl) {
    if (url == null) return false;
    return url.startsWith(baseUrl);
  }
}

The `_extractFullUrl` method

  _extractFullUrl(
    String url,
    String expandedBaseUrl, [
    int iterationsAllowed = 5,
  ]) async {
    try {
      if (!(iterationsAllowed >= 1)) throw "Max redirect limit reached";
      if (!_isValidUrl(url)) throw "Invalid URL";

      final uri = Uri.parse(url);

      final request = await _client.headUrl(uri);
      request.followRedirects = false;

      final response = await request.close();

      stdout.write(
          "\x1B[32m========\nHEADERS\n=========\n${response.headers}\n==========\x1B[0m\n");

      final fullUrl = response.headers.value(HttpHeaders.locationHeader);

      if ((fullUrl ?? '').isEmpty) throw "URL not found";

      final isValidUrl = _isValidFullUrl(
        fullUrl,
        expandedBaseUrl,
      );

      if (!isValidUrl && response.isRedirect) {
        return await _extractFullUrl(
          fullUrl!,
          expandedBaseUrl,
          --iterationsAllowed,
        );
      }

      if (!isValidUrl) throw 'Cannot fetch expanded URL';

      return fullUrl!;
    } catch (_) {
      rethrow;
    }
  }

The _extractFullUrl method is the central functional unit of the UrlExpander class. The method receives three arguments url, expandedBaseUrl and iterationsAllowed.

The url argument serves as the shortened URL input. The expandedBaseUrl serves as input to the associated _isValidFullUrl method (along with the url input), ensuring that only full urls that match the host expected for the expanded shortened URL are marked as valid. The iterationsAllowed is primarily given in recursive calls to prevent runaway/infinite recursions.

The stepwise operations of the _extractUrl method are as follows;

WHEN recursively called it check that the recursive iteration is permitted in a guard; if not an exception is thrown.
It checks that the input URL is valid in a guard else it throws an exception; then.
It generates Uri object instance from the input URL
It creates a HttpClientRequest instance request from an HTTP HEAD request on the generated Uri.
We disable automatic redirects on the request instance.
We create a HttpClientResponse instance from the result of closing the request.
We print the response header in green.
We extract the fullUrl string from the location header
IF fullUrl is null or empty we throw an exception; else
We validate fullUrl against its expected base URL denoted by the expandedBaseUrl argument; then
IF fullUrl is invalid but response has a redirect, we recursively call _extractFullUrl, reducing the value of the iterationsAllowed argument; else
IF fullUrl is invalid but there is no redirect in the response we throw an exception; else;
We return fullUrl as the output.

With these operations stated, we find it necessary to highlight the use of the CLI, this is shown below.

Current gaps of the `_extractFullUrl` method

The current iteration of the _extractFullUrl method while apparently well forms, has a shortcoming. It fails to parse full URL inputs correctly, as full URLs may not return the location header from a HEAD request. This is highlighted below:

We can introduce a guard to force an early exit from the method when a valid full URL is input as shown below.

  _extractFullUrl(
    String url,
    String expandedBaseUrl, [
    int iterationsAllowed = 5,
  ]) async {
    try {
      if (!(iterationsAllowed >= 1)) throw "Max redirect limit reached";
      if (!_isValidUrl(url)) throw "Invalid URL";
      if (_isValidFullUrl(url, expandedBaseUrl)) return url;

      final uri = Uri.parse(url);

      final request = await _client.headUrl(uri);
      request.followRedirects = false;

      final response = await request.close();

      stdout.write(
          "\x1B[32m========\nHEADERS\n=========\n${response.headers}\n==========\x1B[0m\n");

      final fullUrl = response.headers.value(HttpHeaders.locationHeader);

      if ((fullUrl ?? '').isEmpty) throw "URL not found";

      final isValidUrl = _isValidFullUrl(
        fullUrl,
        expandedBaseUrl,
      );

      if (!isValidUrl && response.isRedirect) {
        return await _extractFullUrl(
          fullUrl!,
          expandedBaseUrl,
          --iterationsAllowed,
        );
      }

      if (!isValidUrl) throw 'Cannot fetch expanded URL';

      return fullUrl!;
    } catch (_) {
      rethrow;
    }
  }

Consequently the behaviour of the method changes, to return the valid full URL immediately as shown below.

Testing the url expander

Unit tests were written to ensure that the url expander functions as expected in a plethora of scenarios, a presentation of these tests in action is presented below.

The source code for these tests may be found here.

This article made a presentation on the implementation of a URL expander CLI app in Dart. I would like to thank Kenneth Ngedo and Samuel Abada for their reviews on earlier drafts of this article.

dirisujesse / url_expander

URL EXPANDER

A dart CLI application for fetching full urls from short URLs

Usage Example

View on GitHub

Going from Numbers to Words

Dirisu Jesse — Sat, 21 Dec 2019 14:23:40 +0000

Here I present a brief discussion of my solution to the simple numbers to word conversion problem. The solution in question primarily leverages recursion and as such this serves as a presentation on recursion in practice.

dirisujesse / VanillaNumerals

JS Numerals Test Solution Implementation

Code Files

index.html

<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" href="index.css">
    </head>

    <body>
        <div class="converter-container">
            <h2>Number Converter</h3>
            <div class="input-container">
                <label for="num-input">Enter Number &darr;</label>
                <input id="num-input" type="number">
                <button id="submit-btn">convert</button>
            </div>
            <div class="result-container">
                <p id="conversion-holder">English literal will show here</p>
            </div>
        </div>
        <script src="index.js"></script>
        <script>
            let numInput = document.getElementById("num-input");
            let submitBtn = document.getElementById("submit-btn");
            let conversionHolder = document.getElementById("conversion-holder");
            let errMessage = "The provided value appears invalid, provide a valid number to convert"
            submitBtn.addEventListener("click", handleSubmit)
            function handleSubmit(e) {
                e.preventDefault();
                e.stopPropagation();
                let numString = numInput.value || null;
                if (numString && !isNaN(+numString)) {
                    let englishPhrase = convertNum(numString);
                    if (englishPhrase !== errMessage) {
                        conversionHolder.innerText = englishPhrase;
                    } else {
                        alert(errMessage);
                    }
                } else {
                    alert(errMessage);
                    return errMessage;
                }
            }
        </script>
    </body>
</html>

The index.html file presents to the user a number input field as well as a submit button visually. The file imports the index.js file for the conversion logic, which is called within the embedded script in the click listener registered on the submit button.

index.css

html {
    font-size: 62.5%;
}

body {
    max-height: 100vh;
    max-width: 100vw;
    background-color: #FFF;
    color: #000;
    padding: 3rem;
    font-family: Arial, Helvetica, sans-serif;
}

.converter-container {
    position: absolute;
    width: fit-content;
    min-height: fit-content;
    max-width: 80%;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    padding: 2rem;
    background-color: #EFF2F5;
    border-radius: 20px;
    border: 2px dashed black;
}

h2 {
    text-align: center;
    font-size: 2rem;
    text-transform: uppercase;
    color: #007CBB;
}

.input-container {
    font-size: 1.5rem;
}

.input-container * {
    display: block;
    margin-bottom: 0.5rem;
}

#num-input {
    color: #000;
    padding: 1rem;
    width: 100%;
    box-shadow: none;
    border-radius: 5px;
    border: 2px solid #007CBB;
}

#submit-btn {
    color: #FFF;
    background-color: #007CBB;
    padding: 1rem;
    width: 100%;
    box-shadow: none;
    border-radius: 5px;
    text-transform: uppercase;
    border: 0px solid transparent;
}

#conversion-holder {
    font-size: 1.5rem;
    text-align: center;
    text-transform: capitalize;
}

The index.css file provides basic styling for the html code.

index.js

const units = [
    '', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight',
    'nine', 'ten','eleven', 'twelve', 'thirteen', 'fourteen', 'fifteen',
    'sixteen', 'seventeen', 'eighteen', 'nineteen'
];
const tens = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety'];

const numDict = {
    "0": "Zero", "1": "One",
    "2": "Two", "3": "Three",
    "4": "Four", "5": "Five",
    "6": "Six", "7": "Seven",
    "8": "Eight", "9": "Nine",
}

const errors = {
    unsafeNum: "This is a pretty large number, don't expect much accuracy as our engine is not used to handling such massive figures",
    isNanOrInvalid: "The provided value appears invalid, provide a valid number to convert",
    unhandled: "Oops can't handle this, is this a valid number?, number may be too large",
};

// Scales correspond to lengths of numbers from thousands to centillions
// With sub scales corresponding to units, tens and hundreds subscales within the number scales
const scales = [
    [ 4,  5,  6], [ 7,  8,  9], [10, 11, 12],
    [13, 14, 15], [16, 17, 18], [19, 20, 21],
    [22, 23, 24], [25, 26, 27], [28, 29, 30],
    [31, 32, 33], [34, 35, 36], [37, 38, 39], [40, 41, 42],
    [43, 44, 45], [46, 47, 48], [49, 50, 51],
    [52, 53, 54], [55, 56, 57], [58, 59, 60],
    [61, 62, 63], [64, 65, 66], [67, 68, 69]
];

// We handle numbers up to the centillion
const scaleNames = [
    'thousand', 'million', 'billion', 'trillion', 'quadrillion', 'quintillion',
    'sextillion', 'septillion', 'octillion', 'nonillion', 'decillion', 'undecillion', 'duodecillion',
    'tredecillion', 'quatttuor-decillion', 'quindecillion', 'sexdecillion', 'septen-decillion',
    'octodecillion', 'novemdecillion', 'vigintillion', 'centillion'
];

function convertNum(n) {
    n = typeof n !== 'string' ? n.toString() : n;
    // We declare upperlimit variable to check for numbers greater han native JS number bound
    var upperLimit = (2 ** 53) - 1;

    if (Math.abs(+n) > upperLimit) {
        alert(errors.unsafeNum)
    }
    if (n && +n === 0) {
        return "Zero";
    }
    if (!n || isNaN(+n)) {
        return errors.isNanOrInvalid;
    }
    let isSubZero = n.startsWith('-');
    // pruning the minus sign when the number is less than zero
    n = isSubZero ? n.slice(1) : n;
    if (n.includes('.')) {
        let preDecimal, postDecimal;
        let words = n.split('.');
        if (+words[1]) {
            preDecimal = convertPreDecimalNumber(words[0]);
            postDecimal = handleDecimal(words[1]);
            return `${isSubZero ? 'Minus ' : ''}${preDecimal || 'Zero'} point ${postDecimal}`;
        } else {
            preDecimal = convertPreDecimalNumber(words[0]);
            return `${isSubZero ? 'Minus ' : ''}${preDecimal || 'Zero'}`;
        }
    } else {
        let englishPhrase = convertPreDecimalNumber(n);
        return `${isSubZero ? 'Minus ' : ''}${englishPhrase || 'Zero'}`;
    }
}

// returns the literal names for post decimal numbers
function handleDecimal(string) {
    return string.split('').map(wrd => numDict[wrd]).join(' ');
}

function convertPreDecimalNumber(strng) {
    if (!+strng) {
        return '';
    }
    // I parse strng as BigInt to handle numbers beyond native JS Number range
    // Accuracy may be lost over (2**53) - 1 as JS cannot handle very large numbers
    const numString = BigInt(strng).toString();
    const lenNum = numString.length;
    if (lenNum === 1 || +numString <= 19) {
        return units[+numString];
    } else if (lenNum === 2) {
        return `${tens[+numString[0]]} ${units[+numString[1]]}`.trim()
    } else if (lenNum === 3) {
        let [H, T] = [numString[0], +numString.slice(1)];
        let tailString = convertPreDecimalNumber(T.toString());
        tailString = tailString ? `and ${tailString}` : '';
        return `${units[H]} Hundred ${tailString}`.trim()
    }  else {
        const numScale = scales.find(it => it.includes(lenNum));
        if (numScale && numScale !== undefined) {
            const scaleName = scaleNames[scales.indexOf(numScale)];
            if (scaleName && scaleName !== undefined) {
                return handleThanHundredNums(numString, lenNum, scaleName, numScale);
            }
        }
        return errors.unhandled;
    }
}

function handleThanHundredNums(numString, lenNum, scale, numRange) {
    const [minuend, startrange, midrange, _] = [numRange[0] - 1, ...numRange]
    const [H, T] = [
        lenNum === startrange ? 
            units[numString[0]] :
            lenNum === midrange ?
            convertPreDecimalNumber(numString.slice(0, 2)) :
            convertPreDecimalNumber(numString.slice(0, 3)), 
        BigInt(numString.slice(lenNum - minuend)).toString()
    ];
    const tailString = +T ? `${+T >= 100 ? '' : 'and'} ${convertPreDecimalNumber(T.toString())}`.trim() : '';
    return `${H} ${scale} ${tailString}`.trim()
}

A running example of this is to be found as here