
When we talk about writing readable code, one of the most crucial aspects is to recognise that code is meant to be read
by humans first and foremost.

One key principle is that **you should not force the reader to understand or process every little detail** all at once.
Think of your code like a well-written newspaper article. When you read a news article, you start with the
headline—broad and essential information. Then, as you continue reading, the story deepens, with more detailed
explanations that follow in the later paragraphs. This structure allows the reader to get the most critical information
up front and dig deeper only if they want or need to. **Crucially, the reader can bail out when they want to**. Good
code should work the same way.

**Function hoisting** in JavaScript, as opposed to arrow functions (which need to be declared before they’re used),
support this kind of readability. In JavaScript, **function declarations are hoisted**, meaning that you can declare a
function anywhere in the code, and it can still be invoked before its declaration. This allows you to place your most
important logic (like the main flow of your program) at the top, where it is immediately visible and understandable,
without needing to wade through the implementation details of every helper function that supports that logic.

By organising your code this way, the reader can get the "headline" (i.e., the high-level logic) up front. They don't
need to scroll down through the helper functions to see what the program is doing. Only if they're interested in the
details of how a specific task is done do they need to follow the breadcrumbs into those helper functions.

For example, consider this code structure:

```js
function mainTask() {
    // high-level logic, easy to read
    setup();
    process();
    finalize();
}

function setup() {
    // detailed code for setting things up
}

function process() {
    // detailed code for processing
}

function finalize() {
    // detailed code for finalizing
}

```

With **function hoisting**, the reader can start with the `mainTask` function and immediately understand the high-level
flow of the program. If they want more details on how `setup`, `process`, or `finalize` works, they can read further
down. But if they don't need that level of detail, they can bail out after seeing the structure and purpose.

On the other hand, **arrow functions**, which are not hoisted, force you to declare them before they are used. This can
make your code harder to read at first glance, because the reader must sift through low-level implementation before
understanding the bigger picture:

```js
const setup = () => {
    // detailed code for setting things up
};

const process = () => {
    // detailed code for processing
};

const finalize = () => {
    // detailed code for finalizing
};

const mainTask = () => {
    // now the high-level logic
    setup();
    process();
    finalize();
};

```

In this second example, by the time the reader gets to the high-level `mainTask` logic, they’ve already seen the details
they might not care about, and they had no chance to get an overview first.


How function hoisting enables you to write clearer code


Introduced in TypeScript v5.0 (see the [great Microsoft release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#decorators)), decorators are an upcoming ECMAScript feature, they enable us to reuse code throughout class members.

Imagine that we want to log the execution time of a particular class method:

```TypeScript
export default class AwesomeClass {  
  constructor() {}  
  
  doSomething() {  
    const startTime = new Date();  
    for (let i = 0; i < 9999999; i++) {  
      // simulating a slow process  
    }  
    const endTime = new Date();  
    const duration = endTime.getTime() - startTime.getTime();  
    console.info("doSomething took:", duration, "ms");  
  }  
}
```

Simple enough, but how can we make this DRY and easily apply it to other class methods? This is where decorators come
in, allowing us to change the above class to just:

```TypeScript 
export default class AwesomeClass {  
  constructor() {}  

  @logPerformance
  doSomething() {  
    for (let i = 0; i < 9999999; i++) {  
      // simulating a slow process  
    }  
  }  
}
```

Here, `@logPerformance` applies the `logPerformance` decorator to the `doSomething` class method. In it's simplest form,
the `logPerformance` decorator would look like this:

```TypeScript 
function logPerformance<This, Args extends any[], Return>(  
  originalMethod: (this: This, ...args: Args) => Return,  
  context: ClassMethodDecoratorContext<  
    This,  
    (this: This, ...args: Args) => Return  
  >,  
) {  
  function replacementMethod(this: any, ...args: Args) {  
    const methodName = String(context.name);  
    const startTime = new Date();  
    const result = originalMethod.call(this, ...args);  
    const endTime = new Date();  
    const duration = endTime.getTime() - startTime.getTime();  
    console.info(`"${methodName}" took: ${duration}ms`);  
    return result;  
  }  
  return replacementMethod;  
}
```

A decorator function returns a new function which accepts `this` and an unspecified number of arguments as its
parameters. When the decorator function is called, it's called with the original method and a context object. We can use
the context object to extract the name of the method, which is quite useful as you can see in the above example as it
allows us to include the method name in the logging message (fyi the context object also includes other information like
if it's a private or static method).
Of course, the most important part of all of this is the fact that we call the original method.
Note that we execute `originalMethod.call(this, ...args)` rather than `originalMethod(...args)` because the original
method will most likely be referencing class properties and will hence need to be bound to the correct `this`.


TypeScript decorators




In iOS, the "system red" is a different shade depending on whether you are in light mode or dark mode, and additionally if you are in an
accessible mode (e.g. high contrast); that's [four different values just for system red](https://developer.apple.com/design/human-interface-guidelines/color#iOS-iPadOS-system-colors).

You can use a system color like so:

```typescript
import {PlatformColor} from "react-native";

const red = PlatformColor("systemRed");
const placeholderColor =PlatformColor("placeholderText");
const background = PlatformColor("systemBackground");
```

What's really neat is that these colors will be in-sync with the user's device. If the sun sets, then the colors will change, and you don't even have to listen for it. The downside is that you have you use pre-defined Apple colors.

![Fig 1: Normal contrast in a RN app, using Apple's system colors](/man_drawer/react_native_notes_005/contrast-regular.png)
![Fig 2: After the user has selected high contrast mode](/man_drawer/react_native_notes_005/contrast-high.png)

Having to use the platform's own colors is restrictive. If you're building for iOS then you can specify your own color set [(see the docs)](https://reactnative.dev/docs/dynamiccolorios):

```typescript
import {DynamicColorIOS} from 'react-native';

const customDynamicTextColor = DynamicColorIOS({
    dark: 'tomato',
    light: 'white',
});

const customContrastDynamicTextColor = DynamicColorIOS({
    dark: 'saddlebrown',
    light: 'azure',
    highContrastDark: 'black',
    highContrastLight: 'white',
});
```

As far as I know, there is not an equivalent for Android or Web so I guess the only solution there is to [listen for dark mode changes](https://reactnative.dev/docs/appearance#addchangelistener), and to [listen for a11y changes](https://reactnative.dev/docs/accessibilityinfo#addeventlistener). 


React Native Notes – 005


After releasing Wobble Time to the app store earlier this week it was time to buy an Android phone and rebuild my shiny new app for Google's Play Store.

I expected to hit a few snags along the way, and I did. Some styling rules don't render the same on Android as they do on iOS (but being a web developer, I'm more than used to dealing with such issues), the Android emulator is finicky – it enjoys taking full advantage of 4 cores and is partial to crashing. However, the most challenging difference so far has been using the motion sensors with Android.

I'm using [Expo's DeviceMotion API](https://docs.expo.dev/versions/latest/sdk/devicemotion/) to access the device's `rotation` values. My app times how long you can keep a wobble board upright and therefore needs frequent updates from the motion sensors. When I use the app on Android it's sluggish to respond to the changing orientation of the phone.

My requested update frequency is 50ms and this feels nice and responsive on iPhone. I decided to collect a sample of motion data from my test devices to see if there is any discrepancy there.
Running on my iPhone XS (released 2018) and collecting a sample of 250 data points (at a request interval of 50ms) the mean interval is bang on 50ms, as is the median. The Android device is not so reliable, as you can see in the table below. Although the values aren't great, I didn't feel like this was the sole explanation for why the app felt so sluggish on the Galaxy.
<f>
| | Apple iPhone XS (2018) |Samsung Galaxy A14 (2023)|
|---|------------------------|---|
|OS Version| 17.1.1                 |13|
|Target Interval| 50ms                   |50ms|
|Sample Size| 250                    |250|
|Mean| 50ms                   |60ms|
|Median| 50ms                   |63ms|
|Max| 52ms                   |68ms|
|Min| 47ms                   |50ms|
|Stdev| 1ms                    |6ms|
</f>
![Fig 1: After creating a 50ms subscription to ah iOS and Android device, the regularity of updates was very different between the two devices](/man_drawer/react_native_notes_004/sensor_response_subscription.png)

I decided to place the Apple and Android side-by-side and monitor the output from the motion sensor. With the Apple, the alpha 


Note about the rotation values: If you were to place your phone on a flat surface in front of you:
- `alpha` changes if you rotate your phone around while keeping it on the table.
- `beta` changes when you tilt the phone back or forth (i.e. along its short edge, assuming it's in portrait orientation) 
- `gamma` changes when you tilt the phone left or right (i.e. along its tall edge, assuming it's in portrait orientation).


This works flawlessly on the iPhone. With the Android however, I noticed that tilting the phone also changes the alpha (so if `beta` or `gamma` change, `alpha` also changes). Additionally, if I pass a ferromagnetic metal (e.g. my penknife) near the Android, the `alpha` value changes considerably; the iPhone is not effected by this.

This is annoying, but again not an explanation for why my app feels so sluggish on the Android. It actually seems that the motion sensor in my Android device is just not capable of outputting a new reading every 50ms.
I have tested the Wobble Time app on 4 physical iOS devices, including an old iPad, and there were no problems with the hardware. I imagine that  premium Androids have better motion sensors but I can't afford to buy another test device to find out.
The Android Sensor API has a [`getResolution`](<https://developer.android.com/reference/android/hardware/Sensor#getResolution()>) method that will tell you the maximum practicable update frequency, unfortunately it's not exposed in React Native. It would be useful in telling a user that their device is not capable of running an app, but if you want to launch a paid app then you need to block the user from buying it in the first place - it'd be no good taking their money only then to tell them that their sensors aren't good enough - and I can't find any way to block distribution in the Play store based on a device's sensor capabilities.


React Native Notes – 004



## Button layout patterns in iOS
While building Wobble Time I've put buttons in the navigation bar of my app; sometimes there will be just just one
button which leads to the question – should it be on the left or the right? Sometimes there will be two buttons in the
navigation bar, which leads to the question – should the *primary* button be on the left or the right?

I haven't been able to find a satisfactory answer in Apple's Human Interface Guidelines regarding button placement in
the navigation bar. As developers and designers we have the ability to use different coloured text in these buttons,
different weight text and we can also position them on the left or right of the navigation bar.

I've gone through some of Apple's own apps to try and figure out a pattern, take a look at these screenshots:


![Fig 1: Notes app uses bold font for the primary action. Both buttons use an accent colour. Primary button on the right.](/man_drawer/react_native_notes_003/1.jpeg)



![Fig 2: Health app is similar to the Notes app with the Primary button on the right and with bold weight. Both buttons
use accent colour.](/man_drawer/react_native_notes_003/2.jpeg)


![Fig 3: A date selection screen in Apple's fitness app. Both buttons have a bold font weight and both use an accent
colour.](/man_drawer/react_native_notes_003/3.jpeg) 


![Fig 4: The Fitness app again. This time the only button is an icon button. It is coloured using the secondary and
tertiary label colours. It is placed on the right.](/man_drawer/react_native_notes_003/4.jpeg)


![Fig 5: The shortcuts app. Uses an icon button on the right and text button on the left. Both are normal weight and use
the accent colour.](/man_drawer/react_native_notes_003/5.jpeg)


![Fig 6: After pressing the "Edit" button in Fig 5, its style changes to be a primary button (i.e. bold font weight) and
the text changes to "Done". Up until now, Done buttons have always appeared on the right, but here it makes for a nice,
*reversible*, experience by keeping it in the same location at the Edit button.](/man_drawer/react_native_notes_003/6.jpeg)


![Fig 7: Watch app places "Done" on the left and doesn't use bold text.](/man_drawer/react_native_notes_003/7.jpeg)


![Fig 8: Editing my home screen - 'gray' and 'tinted' buttons used. The primary button is tinted.](/man_drawer/react_native_notes_003/8.jpeg)


![Fig 9: The App store uses a tinted button to display the price, along with two lines of supplementary text.](/man_drawer/react_native_notes_003/9.jpeg)


These 7 screen shots show that there is variability in how Apple is styling navigation bar buttons, but some loose
patterns to follow when creating iOS navigation bar buttons are:

1. Use ['plain' style buttons](https://developer.apple.com/design/human-interface-guidelines/buttons#iOS-iPadOS)
    1. You can use text or icons for this
    2. Use "Title Style" text 
2. Use the app's accent colour for the button
    1. Some minor operations may use secondary and tertiary label colours (or red for delete-like actions)
3. If there are two buttons, only have one primary one
4. The primary button should use a bold font weight
5. The primary button is generally on the right
    1. but put it on the left if that makes for a better UX!

"Done" is quite a common action button to implement in the navigation bar. Looking at Apple's own apps, you can see that
they don't consistently place this action on the same side. For me, it makes most sense to put "Done" on the left when
it's effect is similar to a back button, otherwise put it on the right.

## Implementation with React Native

When it comes to putting this into practise, the obvious choice is using a `Button` component however, the React
Native `Button` scales its text – seemingly with no bounds – as the user increases their font size preferences.
Unfortunately, there is no `maxFontSizeMultiplier` prop (or similar) that we can apply to cap the size of the button.
Additionally, there is no way to alter the font weight used for the text. This is an issue because the Human Interface
Guidelines
state [that a bold weight is used for a primary button](https://developer.apple.com/design/human-interface-guidelines/buttons#Role).
So the `Button` really fails us on two fronts.

![Fig 10: Left shows how my unoptimised app reacted to the largest dynamic font size in iOS. Middle image is from the iOS
settings, note how Apple have capped the max size of the Back button. Right shows my updated app.](/man_drawer/react_native_notes_003/font-size-comparison.png)


Fig 10 shows how the React Native `Button` component reacts when the user has upped their preferred type size; it's far
too large for the navigation bar, especially when compared to "Back" button in the Settings app which has been capped at
an upper limit.
Also note how the "lap time" (in orange) has scaled from an already large font size to something that is obscene and,
frankly, ruins the app. On the right of Fig 10 is my updated app; the "New" button is capped, matching what Apple do;
text within the screen is also capped. Note that you don't have to scale all the text in your app by the same amount,
the less important stuff doesn't need as much (if any) scaling.

> **Prioritize important content when responding to text-size changes.** Not all content is equally important. When
someone chooses a larger text size, they typically want to make the content they care about easier to read; they don’t
always want to increase the size of every word on the screen. For example, when people choose a large accessibility text
size, Mail displays the subject and body of the message in the large size, but leaves less important text — such as the
date and the sender — in a smaller size. [Source: Human Interaction Guidelines](https://developer.apple.com/design/human-interface-guidelines/typography#Best-practices).

My customised button is a `Pressable` component wrapping some `Text`. This works nicely in the navigation bar and also
throughout the app:

```TypeScript
export function AppButton(props: AppButtonProps) {  
  const {  
    fontWeight,  
    color = rawColors.primary600,  
    title,  
    onPress,  
    style = { color: "inherit" }, // noop to make TS happy that this is a style (casting to a ViewStyle doesn't work)  
    ...rest  
  } = props;  
  
  // testing shows that this value, combined with the font size of 18, is the largest font size  
  // that Apple use in their own buttons when the a11y dynamic font size is maxed-out.  const maxFontSizeMultiplier = 1.2;  
  
  return (  
    <Pressable  
      accessibilityRole="button"  
      onPress={onPress}  
      hitSlop={60}  
      {...rest}  
      style={(state) => {  
        return {  
          opacity: state.pressed ? 0.5 : 1,  
          ...style,  
        };  
      }}  
    >  
      <Text  
        style={[appButtonStyles.text, { color, fontWeight }]}  
        maxFontSizeMultiplier={maxFontSizeMultiplier}  
        // Apple buttons never drop below this size. Unfortunately, this prop doesn't appear to be respected, or I misunderstand what it does.  
        minimumFontScale={18}  
      >  
        {title}  
      </Text>  
    </Pressable>  
  );  
}  
  
export function AppHeaderButtonPrimary(props: AppButtonProps) {  
  return (  
    <AppButton {...props} color={rawColors.primary600} fontWeight={"600"} />  
  );  
}  
  
const appButtonStyles = StyleSheet.create({  
  text: {  
    // this is the font size that Apple use in their own buttons  
    fontSize: 18,  
  },  
});
```



React Native Notes – 003

## OTA updates

The JavaScript bundle in your app (the "React" part of React Native) can be swapped-out in live apps. So if you want to fix a simple typo or even add a new screen to your app, you can update this bundle and your app will fetch it the next time its user opens it.

To enable over-the-air updates for your app, you need to add the `expo-updates` package to your project. This will be automatically installed the first time you run `eas update` (or you can manually install it with `npx expo install expo-updates`).

While you've been developing your app locally, you'll have been running a local server from your machine (via the `npx start` command). The standard `eas.json` `build.development` configuration (i.e. `"developmentClient": true`) will have let you build an app that you can install on a device and this app will look to your local server for the JS bundle, fetching code changes as they happen (i.e. hot module reloading). `eas update` pretty much allows you to do the equivalent but with your production app.

When you run `eas update --auto` from your terminal, the eas cli will build your app bundle locally and then upload it to the Expo servers. It will use the name of your current git branch as the name of your Expo update branch (that's what the `--auto` flag does). 
Now – bear with me – this Expo update branch needs to be linked to an Expo *channel* and channels are then associated with actual builds. So your `production` build would typically be associated to your `main` channel, which is linked to your `main` branch (where `main` is the name of your git branch and also your Expo update branch)

You can link any Expo branch to any Expo channel, this is done by running the following command (assuming that I want to link my "preview" channel and an Expo branch named `feature/foo`):
```shell
eas channel:edit preview --branch feature/foo
```

At the moment I'm leaning towards keeping the channel names the same as the branch names. It seems a bit simpler, one less thing for me to have to remember; I can just simply run `eas update --auto` and not have to worry about it any further.

To associate a build with an update channel, you need to specify the `channel` property in your `eas.json` file:
```json
{  
  "cli": {  
    "version": ">= 5.3.0"
  },  
  "build": {  
    "production": {  
      "node": "18.17.0",  
      "channel": "main"  
    },  
    "preview": {  
      "extends": "production",  
      "distribution": "internal",  
      "channel": "preview"  
    }
  }
}
```

Note that if this is your first time setting-up the eas update functionality, you will need to do another `eas build` after you've added the `expo-updates` package. The newest build will then be capable of fetching updates from the Expo servers.

## Why hasn't my app updated?
There are a few reasons why updates may not appear on your device:

### 1. Configuration
Make sure that you have:
1. Run `npx expo install expo-updates`
2. Set  channels for your build configurations (in `eas.json`)
3. Have run an `eas build` after doing the above 2 things
4. Have run an `eas update` after making a simple code change
5. Your Expo update branch is linked to the channel that is associated with the build that you are testing.
6. Your changes haven't changed the app version or any native code.

### 2. Timing
If your app is able to download both the update manifest **and** all the required assets before the `fallbackToCacheTimeout` setting, then the new update will run immediately upon launch. If not, it will continue to download the update in the background and will run it upon the next launch.
By default `fallbackToCacheTimeout` is 0ms. So, unless you've specified anything greater, this is the primary culprit of why you're not seeing immediate app updates.
You can set this value in your `app.json` file in the `udpates` section.

### 3. Usage limits
Go to the Expo dashboard and navigate to Account Settings > Usage. Make sure that you haven't gone past your limit of updates. Stick in your credit card details if you have or, potentially, [host your own Expo updates server](https://docs.expo.dev/distribution/custom-updates-server/).

## Summary
Now that I've got my head around branches and channels, I'm loving EAS. It really does take a lot of the grunt work out of app development. When I get a chance I'll setup a Github action to automate as much of this as I can; that'll be sweet.

## Other random brain stuff I need to write down
There is a bit of a disconnect for me in that you could be on a git branch called `feature/foo` and then run `eas build --profile preview --platform ios`. That preview app will come bundled with the code in you branch. This makes sense. However, if I were then to fix a typo and run `eas update --auto` then a new Expo branch and a new Expo channel would be created (named `feature/foo`) but this code would not be pushed to instances of the preview app, that's because the preview app is not associated with the channel that the update was deployed to.



React Native Notes – 002


I am dedicating the next 6 months of my life to mastering React Native development. These are my notes along the way.

I've been building web apps for years. I love doing it and I'm pretty good at it now. Moving to native development has required a bit of a shift in where I place the bars. In web development it is a goal to make sure that the (web) app's experience is consistent across devices and browsers. I celebrate unique and well-designed websites. However, taking such an approach in native app development is the wrong approach. Android and iOS have strong design systems associated with them – design systems that the phone user is *very* used to, knows well, and expects to see in front of them. To build an app (I'm not including games here or 'immersive' apps like Headspace) using your own UX patterns, custom components and designs is an anti-pattern. Unless you are running UX tests on your designs you shouldn't be rolling your own custom design patterns to a native environment. I'll double-down on this statement if you justify it by saying "it's so that users have a consistent experience across different platforms". If you do *need* this, then you should probably use the web (or a PWA if you need some offline behaviour). Native components offer a buttery smooth experience, if you're deploying a native app then it's unforgivable not to leverage this because you're making compromises so that your app is the same on iOS and Android. For example, I've seen so many examples of stuttery side navigations (which is a Material Design thing, without a native iOS component) implemented in iOS apps. 

Like it or not, Apple and Google have very established design guidelines. When building for iOS it is your duty (to the iOS users) to follow the Human Interface Guidelines (and likewise for Android users with the Material Design guidelines). You gotta think about their expectations when it comes to apps on *their* phone - they expect something that feels native to their device: it feels like the other apps on their phone, both in a visual sense and a physical sense with those buttery smooth animations. Don't confuse mobile app development with web development, where the website is *yours* and visitors expect unique designs and are more open to learning the behaviour and exploring the layout of your site. 

I like to think of apps as physical things. Android and iOS users are not the same, the 'physical' world feels slightly different to each of these cohorts, based on what they are used to. If you're going to all the effort of using React Native, then do it properly and separate your iOS design from your Android design.


React Native Notes – 001

The return types of the query functions in the MongoDB library are not very accurate; after succumbing to a silly bug due to the lack of proper typings, I decided to make some type-safe code to wrap around the MongoDB library and let TypeScript do it's thing: protect me with static types.

The library's `findOne` and `find` functions accept a *type variable*, describing the shape of the collection's documents. The problem is that the return type just matches whatever you supplied as the type variable and no notice is taken of the *projection*. Take the following example where we select a single document and project just a single field. The return type of `result` is incorrect, typescript believes that **all** of the document's fields have been returned, when in reality only a single field exists on the object:

```typescript
type Document = {
  _id: string
  name: string
  age: number
}

async function noTypeSafety() {
  const connection = await databaseConnection()
  const result = await connection.db
    .collection("myCollection")
    .findOne<Document>({}, { projection: { name: 1 } })
  if (result) {
    result._id // ❌ this *should* cause a type error
    result.name // this is fine
    result.age // ❌ this *should* cause a type error
  }
}

```

That's not the only issue, however. You can also pass in a bogus projection and it will not cause a type error:
```typescript
async function queryNotTyped() {
  const connection = await databaseConnection()
  const result = await connection.db
    .collection("myCollection")
    .findOne<Document>({}, {
      shoe: 1, // this should cause a type error as `shoe` doesn't exist on Document.
    })
}

```


We can fix these issues by creating new TypeScript types which describe valid projections and valid  return types. There are other cases where the types need overhauling (e.g. the query and sort parameters), but for the purpose of this blog post I am just going to concentrate on calling `findOne` with a strongly typed projection parameter, returning a correctly typed object.

First-up, I create a class:
```TypeScript
import { Filter } from "mongodb";

export class TypeSafeMongo<Document extends Record<string, any>> {
  readonly collectionName: string

  constructor(collectionName: string) {
    this.collectionName = collectionName
  }

  async findOne<
    _F extends Filter<Document>,
    _P extends Projection<Document>
  >(
    filter: _F,
    options: { projection: _P; }
  ) {
   // ... todo 
  }
}

```

Ultimately I will wrap many of the MongoDB library's functions with better types (e.g. `.find`, `.delete` etc.) and using a class like this allows me to instantiate a `TypeSafeMongo` instance once – declaring the document type  – and then reusing that instance throughout my code, without having to worry about passing document types around again. I now need to implement the return type and `Projection`.

Starting with the easiest one, `Projection`, what do I want to do? Well, the projection parameter is an object which consists of any combination of fields in the document, assigned a value of 1 or 0. In TypeScript terms:
```TypeScript
type UserDocument = {
  _id: string
  handle: string
  name: {
    first: string
    last: string
  }
}

// both of these are valid projections for the UserDocument
const projection1 = {
  name: 1,
}
const projection2 = {
  name: {
    first: 1,
  },
}

```

It'd be very easy to create a type that describes `projection1` (just map each key to the value `1 | 0`), however, `projection2` is more complicated because we specify a sub field. The `Projection` type needs to be a `Partial` of the `UserDocument`, but not *just* a `Partial` (which comes for free with TypeScript), it needs to be a **deep** partial. Thankfully the [type-fest utility library](https://github.com/sindresorhus/type-fest) has such a type we can just use. The other thing we need to do is only allow `1 | 0` to be specified for the document's fields, again this is made easy with type-fest and their `Schema` type which allows us to apply a blanket type definition to all the fields. In fact, I'm going to be even stricter and only allow `1` to be specified:

```TypeScript
export type Projection<D> = Schema<PartialDeep<D>, 1>

// these work
const projection1: Projection<UserDocument> = {
  handle: 1, // ✅
}
const projection2: Projection<UserDocument> = {
  name: {
    first: 1, // ✅
  },
}

// ts correctly errors on these
const projection3: Projection<UserDocument> = {
  name: 0, // ts error because you can't supply 0
}
const projection4: Projection<UserDocument> = {
  name: {
    middle: 1, // ts error because this field does not exist
  },
}

```

**Side note**: MongoDB projections will allow you to specify `0` if you want to exclude a field; I prefer to have to manually opt-in to each field, this way if I add some sensitive fields to the collection in the future then I won't accidentally dox someone with an overlay keen projection.

So, now for the more complicated return type, `Query`. This type will need to accept both the `Document` and the `Projection` so that it can correctly deduce what will be returned. Enough chat, here is the beast:

```TypeScript
import { RemoveNeverDeep } from "./foo"

type DefinedPrimitive = null | string | number | boolean | symbol | bigint

type _DeepFix<
  Doc extends Record<any, any>,
  Proj extends Schema<PartialDeep<Doc>, any>
> = {
  [K in keyof Doc]: Proj[K] extends Record<any, any> // is user requesting a parts of a nested field?
    ? _DeepFix<Doc[K], Proj[K]> // this is an object. We need to recurse
    : Proj[K] extends DefinedPrimitive // not an object, has the user specified this key?
    ? Doc[K] // key has been requested, return it
    : never
}

export type Query<
  Doc extends Record<any, any>,
  Proj extends Schema<PartialDeep<Doc>, any>
> = RemoveNeverDeep<_DeepFix<Doc, Proj>>
```


```TypeScript
// foo.ts
import { EmptyObject } from "type-fest"

/**
 * In some of my utility functions I need to differentiate between a simple object used to store
 * type data (e.g. `{ ... }`) and a real "thing" that is used to get stuff done type of object.
 */
export type UsefulObjects =
  | Date
  | Class<any>
  | BSON.ObjectId
  | ObjectId
  | RegExp

type RemoveEmptyObjectsDeep<B extends object> = {
  [K in keyof B as EmptyObject extends B[K]
    ? never
    : K]: B[K] extends UsefulObjects
    ? B[K]
    : B[K] extends any[]
    ? B[K]
    : B[K] extends object
    ? RemoveEmptyObjectsDeep<B[K]>
    : B[K]
}

type _RemoveNeverDeep<B extends object> = {
  [K in keyof B as B[K] extends never ? never : K]: B[K] extends UsefulObjects
    ? B[K]
    : B[K] extends object
    ? _RemoveNeverDeep<B[K]>
    : B[K]
}

export type RemoveNeverDeep<B extends object> = B extends Date
  ? B
  : RemoveEmptyObjectsDeep<_RemoveNeverDeep<B>>

```

Alright, there's a lot going on there, the crux of it is:
- `_DeepFix` is doing the heavy-lifting. It recurses through the doc parameter and picks it if that field is also present in the projection. Doing it this way round (rather than recursing through the projection and replacing its type – `1` – with the type from the doc) means that we keep the information of whether the field is optional or not (and less importantly whether the type is readonly or not).
- We end up with a load of `never` types, these are removed with `RemoveNeverDeep`
- We need to take some care around types like `Date` – which look like objects – and not recurse into them!


So with all of that in place, we can now finish off our class:
```TypeScript
import { Filter } from "mongodb";
import { Query } from "./query.ts";

export class TypeSafeMongo<Document extends Record<string, any>> {
  readonly collectionName: string

  constructor(collectionName: string) {
    this.collectionName = collectionName
  }

  private validateProjection(projection: Projection<Document>) {
    if (Object.keys(projection).length === 0) {
      throw new Error("Projection must not be empty", {
        cause: "The projection parameter in the props is empty.",
      })
    }
  }

  async findOne<
    _F extends Filter<Document>,
    _P extends Projection<Document>,
  >(
    filter: _F,
    options: { projection: _P; }
  ): Promise<Query<Document, _P> | null> {
    this.validateProjection(options.projection)
    const connection = await databaseConnection()
    const result = await connection.db
      .collection<Document>(this.collectionName)
      .findOne(filter, {
        projection: options.projection,
      })

    if (!result) return null
    return result as any as Query<Document, _P>
  }
}

```

I've included a little runtime helper function to validate the projection, and that's it. Type safe mongo queries.


TypeScript and MongoDB




## ThePrimeagen

**The Last algorithms course you’ll need**

- [Course website](https://frontendmasters.com/courses/algorithms/)
- [Course Notes](https://theprimeagen.github.io/fem-algos/)
- [Code Exercises](https://github.com/ThePrimeagen/kata-machine)

**Polyglot Programming: TypeScript, Go, & Rust**

- [Course website](https://theprimeagen.github.io/ts-go-rust/)

**Rust for TypeScript Developers**

- [Course website](https://theprimeagen.github.io/rust-for-typescript-devs/)


## Mike North

**TypeScript Fundamentals v3**

- [Course website](https://www.typescript-training.com/course/fundamentals-v3)

**Intermediate TypeScript**

- [Course website](https://www.typescript-training.com/course/intermediate-v1)

**Making TypeScript stick**

- [Course website](https://www.typescript-training.com/course/making-typescript-stick)

**Full stack TypeScript**

- [Course website](https://www.typescript-training.com/course/full-stack-typescript)

## Steve Kinney

**React and TypeScript, v2**

- [Course website](https://fem-react-typescript.vercel.app/)

## Brian Holt

**Complete Intro to React, v8**

- [Course Website](https://react-v8.holt.courses/)
- [Course Repo](https://github.com/btholt/complete-intro-to-react-v8/)
- [Course Project Files](https://github.com/btholt/citr-v8-project/)

**Complete Intro to Computer Science**

- [Course Website](https://btholt.github.io/complete-intro-to-computer-science/)
- [Course GitHub Repo](https://github.com/btholt/complete-intro-to-computer-science)

**Complete Intro to Containers (feat. Docker)**

- [Course Website](https://btholt.github.io/complete-intro-to-containers/)
- [Code Repo & Setup](https://github.com/btholt/complete-intro-to-containers)
- [Project Files](https://github.com/btholt/projects-for-complete-intro-to-containers)

**Complete intro to Linux and the command-line**

- [Course Website](https://btholt.github.io/complete-intro-to-linux-and-the-cli/)
- [Course Repo](https://github.com/btholt/complete-intro-to-linux-and-the-cli)

**Complete Intro to Real-Time**

- [Course Website](https://btholt.github.io/complete-intro-to-realtime/)
- [Course Code](https://github.com/btholt/realtime-exercises)

## Nina Zakharenko

**Practical Guide to Python**

- [Course website](https://practical.learnpython.dev/)

**Intro to Python and Intermediate Python**

- [Course website](https://www.learnpython.dev/)


Awesome courses


Next JS 13 has dropped with a tonne of great features, one being the new  `@next/font/google` package which lets you self-host Google fonts, which means that Google can't track your users if you use one of their fonts. This package has also been optimised to reduce any font flickering while your user is waiting for your web font to load, the fallback font will be a system font most closely matched to your web font. Praise.

Your imported font will have a bit of a random name (e.g. "__Megrim_cb9663"), and because of that, you can't reference it directly in your CSS (for example, if you only want to use the imported font for headings). This also leads to the question of how to use multiple Google fonts on your site... The Next JS beta docs show how to set the site-wide font to a Google font, and it seems that the only way to use additional Google fonts would be to create new React components for them, which would be really annoying to have to do for all your `h1` ... `h6` elements etc.

I've discovered that the font directive allows you to create a CSS variable for it, and that's the key that unlocked this puzzle for me.

```tsx
// layout.tsx
import './globals.css'
import {Megrim, Archivo_Narrow} from '@next/font/google';

const specialFont = Megrim({
    subsets: ["latin"],
    variable: "--font-special",
    weight: "400",
})

const regularFont = Archivo_Narrow({
    subsets: ["latin"],
    variable: "--font-regular",
    weight: "400",
})

export default function RootLayout({
                                       children,
                                   }: {
    children: React.ReactNode
}) {
    return (
        <html lang="en">
        <head/>
        <body className={`${specialFont.variable} ${regularFont.variable}`}>{children}</body>
        </html>
    )
}
```

```css
/* globals.css */
h1, h2, h3, h4, h5, h6 {
    font-family: var(--font-special);
}

body {
    font-family: var(--font-regular);
}
```


Fonts in Next JS 13



The observer pattern is a mechanism that lets you notify multiple *subscribers* when something happens.

```jsx
// observable.js

const observers = [];

export default Object.freeze({
  notify: (data) => observers.forEach((observer) => observer(data)),
  subscribe: (func) => observers.push(func),
  unsubscribe: (func) => {
    [...observers].forEach((observer, index) => {
      if (observer === func) {
        observers.splice(index, 1);
      }
    });
  },
});
```

And this is how something can subscribe to it:

```jsx
import Observable from "./observable";

function logger(data) {
  console.log(`${Date.now()} ${data}`);
}

Observable.subscribe(logger);
```

Finally, this is how the subscriber gets notified:

```jsx
import Observable from "./observable";

document.getElementById("my-button").addEventListener("click", () => {
  Observable.notify("Clicked!"); // Notifies all subscribed observers
});
```

You could use this pattern for something like o triggering calls to all of your analytics backends. Check
out [this example on StackBlitz](https://stackblitz.com/edit/js-mg21bk?file=index.js).


The observer pattern in JS


## Create

`object.create(null)` will make an object **without** a prototype. After you've created it, you can add props to it:

```tsx
const obj1 = Object.create(null)
obj1.make = "Ford"
obj1.model = "Ka"

obj1.toString() // obj1.toString is not a function
```

Conversely, if you want an object to inherit its prototype from somewhere else, then you can do this:

```tsx
const obj2 = Object.create(obj1)
obj2.make // "Ford"
```

## Freeze
`object.freeze` will stop an object from being modified

```tsx
const obj3 = {make: "VW", model: "Golf R"};
Object.freeze(obj3);
obj3.year = "1999"; // Cannot add property year, object is not extensible
obj3.make = "Ford"; // Cannot assign to read only property 'make' of object
```

## Clone
`structuredClone` creates a deep clone of a given value. This is a global available on the `window` and in NodeJS. The
introduction of this API means that you don’t have to use lodash’s `cloneDeep`
method, but note
that [some things don’t work with structured clone](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#things_that_dont_work_with_structured_clone)
, of particular note is:

- Function objects
- DOM nodes
- The prototype chain is not walked or duplicated

```tsx
const obj1 = {make: "VW", model: "Golf R", engine: {size: 2}};
const obj2 = {...obj1};

obj2.engine.size = 3; // 3. We've edited the OG object, which we didn't want to do.
```

Using `structuredClone` instead:

```tsx
const obj1 = {make: "VW", model: "Golf R", engine: {size: 2}};
const obj2 = structuredClone(obj1);

obj2.engine.size = 3;
console.log(obj1.engine.size); // 2 ✌️
```
## Accessing keys

If you're using TypeScript, then you'll use `in` every day:
```jsx
if (myKey in myObj) {
    // do stuff
}
```

### Optional chaining
This is a nice quality-of-life feature that lets you do away with long, speculative checks of
property existence on objects.

```tsx
const baz = foo?.bar?.baz

// if you can't use dot notation to access the prop, you can do this instead
const baz2 = foo?.bar?.["baz 2"]
```

You can also use optional chaining to execute a function if it exists on the object. If the function doesn’t exist, it
will resolve to `undefined` (like it would for a regular property).

```tsx
const width = house?.bedroom?.getWidth?.()
```

### TypeScript

Sometimes I will declare the type of an object, using the `Record` type, and I need to initialise the object as an empty
object (which, in my mind at least, seems valid). TypeScript doesn’t allow this, so in this instance use `Partial` too.
e.g.

```tsx
export type ColumnSearchValue = string | undefined;
export type ColumnSearches<RowRec = RowRecord> = Record<DataTableColumn<RowRec>['id'],
    ColumnSearchValue>;

const relevantColumnSearches: Partial<ColumnSearches<T>> = {};
```

## lodash iterator alternatives

rather than pulling in lodash’s `_.forEach`, `_.map`, `_.filter` etc. methods, use `Object.entries()` instead. i.e.:

- `Object.entries(myObj).forEach(([key, value])=>{ ... })`
- `Object.entries(myObj).map(([key, value])=>{ ... })`
- `Object.entries(myObj).filter(([key, value])=>{ ... })`


JavaScript objects

A reference to save myself from looking these up in the official docs...

## useTransition

Sometimes, updating a state value can cause really expensive re-renders (e.g. you type a search term into an input box
and this filters the rows in a large, complicated table).

Wrap state updates with `startTransition` (see example) if they are low priority. Other state updates in your app that
are regular priority (e.g. updating the text value in an input) will not have to wait for this re-render to complete.

```tsx
const [isPending, startTransition] = useTransition();
const [items, filteredItems] = useState(0);

function onSearchChanged() {
    startTransition(() => {
        const newItems = filterNewItems(searchTerm)

        // changing items will cause an expensive re-render
        // which would block all the other stuff on the page from
        // re-rendering
        setItems(newItems);
    })
}

// ...
return //...
```

## Portals

Portals enable you to render to a DOM element that is outside of your React tree. Needing this is rare but is useful for
stuff like creating full-screen modals. More [details in the proper docs](https://reactjs.org/docs/portals.html).

## Context

`useContext` to avoid prop-drilling. A neat trick is to use a `useState` variable as the item that the context holds.
This way you have a getter and a setter for the context. e.g.

```tsx
const SearchContext = React.createContext(["", (str) => str]);

const App: FC = () => {
    const searchTermState = useState("");

    return (
        <SearchContext.Provider value={searchTermState}>
            <div>
                <input
                    value={searchTermState[0]} // getter
                    onChange={(e) => {
                        const value = e.target.value;
                        // setter
                        searchTermState[1](value);
                    }}
                />
                <ItemList/>
            </div>
        </SearchContext.Provider>
    );
};

function ItemList(): React.Element {
    const [search] = useContext(SearchContext);
    // do stuff with the search variable

    return (
        <div>
            foo bar
        </div>
    );
}
```

## Render function

When you want the ‘wrapping’ component to pass some props to your actual component. It’s basically a way of creating a
Higher Order Component.

```tsx
function Moon(props) {
    const phase = "waxing gibous"
    return (
        <div>
            {props.render({phase})}
        </div>
    )
}

function App() {
    return (
        <Moon
            render={(phase) => {
                <span>The phase is {phase}</span>
            }}
        />
    )
}
```

## useMemo

Incredibly useful function to save unnecessary CPU
cycles ([see working example on code sandbox](https://codesandbox.io/s/usememo-example-hrdgs8?file=/src/App.tsx)).

```tsx
export default function App() {
    const [counter, setCounter] = useState(0);

    /* 
      Bad, each render (each time the button is clicked)
      will cause this function to be called
    */
    const magicNumber = expensiveOperation();

    /*
      Good, as long as the dependencies don't change (and
      we don't have anything in the dependency array) then this function
      is not called.
    */
    const magicNumber2 = useMemo(() => expensiveOperation(), []);

    return (
        <button
            onClick={() => {
                setCounter(counter + 1);
            }}
        >
            Click me!
        </button>
    );
}
```

### Update

I'd always assumed that this function keeps a cache of the values it calculates, but a colleague recently educated me to
the fact that `useMemo` only holds on to the most recent calculation – its cache has a max size of 1!

FYI: If you want to memoize a more substantial set of results, lodash's `memoize` function is unbounded.

## useCallback

Very similar to `useMemo`, but used when you need to make sure that a function is stable between renders. For example,
if you are passing a function to a child component, you don’t want it changing under you as that would cause a re-render
of the child component (i.e. a change of props would be detected)
. [See a working example in this code sandbox](https://codesandbox.io/s/usecallback-example-r1n4wq?file=/src/App.tsx).

```tsx
export default function App() {
    const [counter1, setCounter1] = useState(0);
    const [counter2, setCounter2] = useState(0);

    // bad
    const clickHandler1 = () => {
        setCounter1(counter1 + 1);
    };

    // good
    const clickHandler2 = useCallback(() => {
        setCounter2(counter2 + 1);
    }, [counter2]);

    return (
        <>
            <SpecialButton
                name="Naive"
                count={counter1}
                onClick={clickHandler1}
            />
            <SpecialButton
                name="useCallback"
                count={counter2}
                onClick={clickHandler2}
            />
        </>
    );
}
```

## useLayoutEffect

`useEffect` runs *after* React has rendered your component. Occasionally you need to make sure that an effect runs *
before* a render (and if you need something to happen before the initial render, you should use this hook (equivalent
to `componentWillMount` in class-based land)).# React Patterns



React bits

Bummed that you can’t treeshake lodash away? Well you can use jscodeshift to run a codemod which will explicitly import all of the lodash functions that you're using.


I've taken the codemod 
from [blog.laurenashpole.com](https://blog.laurenashpole.com/post/651822910948900864/optimizing-lodash-imports-with-jscodeshift):

```js
export default (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);
  let specifiers = [];

  root
    .find(j.ImportDeclaration, isLodashImport)
    .forEach((path) => specifiers.push(...path.node.specifiers.map((specifier) => specifier.local.name)))
    .remove();

  root
    .find(j.CallExpression, isLodashExpression)
    .forEach((path) => specifiers.push(path.node.callee.property.name))
    .replaceWith((path) => replaceExpression(path, j));

  if (specifiers.length) {
    cleanSpecifiers(specifiers).forEach((specifier) => {
      root.find(j.Declaration).at(0).get()
        .insertBefore(createImport(j, specifier));
    });
  }

  return root.toSource();
};

function isLodashImport (node) {
  return node.source.value.startsWith('lodash');
}

function isLodashExpression (node) {
  return node.callee.type === 'MemberExpression' && node.callee.object && node.callee.object.name === '_';
}

function replaceExpression (path, j) {
  return j.callExpression(j.identifier(path.node.callee.property.name), path.node.arguments);
}

function cleanSpecifiers (specifiers) {
  return specifiers.filter((specifier, i) => {
    return specifier !== '_' && specifiers.indexOf(specifier) === i;
  });
}

function createImport (j, specifier) {
  return j.importDeclaration(
    [j.importDefaultSpecifier(j.identifier(specifier))],
    j.stringLiteral(`lodash/${specifier}`)
  );
}
```

Name this file `lodash-import-codemod.js` and put it in the root of your project (no need to commit it to git, as you're just using this as a tool to refactor some code). Then run
the following to do the code mod on all your `.tsx` files:

```js
npx jscodeshift -t ./lodash-import-codemod.js --extensions=tsx --parser=tsx  .
```

and then run this to do it on all your TypeScript files:

```js
npx jscodeshift -t ./lodash-import-codemod.js --extensions=ts --parser=ts  .
```

Just be aware that this could result in some name collisions. For example, if you have a variable in your code
named `groupBy` and the file also uses the `_.groupBy` method, after running the codemod, you will also import
the `groupBy` function from lodash, so you’ll either need to change the name that you use to import it, or just rename
your constant to something else.
