rfc: unphased functions

docs/contributing/999-rfcs/2023-06-12-language-spec.md

@@ -752,6 +752,7 @@ For example (continuing the `Bucket` example above):
 
 ```ts
 let bucket = new Bucket();
+
 // OK! We are calling a preflight method from a preflight context
 bucket.allowPublicAccess();
 // ERROR: cannot call inflight methods from preflight context
@@ -776,15 +777,121 @@ let handler2 = inflight() => {
 }
 ```
 
-Bridge between preflight and inflight is crossed with the help of immutable data
-structures, "structs" (user definable and `Struct`), and the capture mechanism.
+The bridge between preflight and inflight is crossed with the help of immutable data
+structures, user-defined structs, resources, and the capture mechanism.
 
 Preflight class methods and initializers can receive an inflight function as an argument. This
 enables preflight classes to define code that will be executed on a cloud compute platform such as
 lambda functions, docker, virtual machines etc.
 
 [`▲ top`][top]
 
+#### 1.3.1 Phase-independent code
+
+> **Note**: Phase-independent functions are not yet implemented. Subscribe to [issue #435](https://github.com/winglang/wing/issues/435) for updates.
+
+Code that is not dependent on the phase of execution can be designated as phase-independent using the `unphased` modifier.
+
+Using this modifier means that the function can be called from either preflight or inflight contexts.
+
+```TS
+let odd_numbers = unphased (arr: Array<num>): Array<num> => {
+  let result = MutArray<num>[];
+  for num in nums {
+    if num % 2 == 1 {
+      result.push(num);
+    }
+  }
+  return result.copy();
+};
+
+// OK! We are calling an unphased function from a preflight context
+let odds = odd_numbers([1, 2, 3]);
+
+let handler = inflight () => {
+  // OK! We are calling an unphased function from an inflight context
+  let big_odds = odd_numbers([7, 8, 9]);
+}
+```
+
+Phase-independent functions are useful for code that is useful across both
+execution phases, such as for data manipulation, utility functions, etc.
+
+Since phase-independent functions can be used inflight, they inherit the same restrictions as inflight functions, like not being able to call preflight functions or instantiate preflight classes.
+
+But phase-independent functions can also be used preflight, so they inherit the same restrictions as preflight functions, like not being able to call inflight functions or instantiate inflight classes.
+
+Phase-independent methods can be defined on resources:
+
+```TS
+class AwsBucket {
+  name: str; // preflight field
+
+  new() {
+    this.name = "my-bucket";
+  }
+
+  unphased object_url(key: str): str {
+    // This method references a preflight field (this.name) -- that is
+    // allowed in both phases so it is OK!
+    return `s3://${this.name}/${key}`;
+  }
+}
+```
+
+Phase-independent methods take on the additional restriction that they
+cannot mutate fields of the resource. For example, the following is disallowed:
+
+```TS
+resource Bucket {
+  name: str; // preflight field
+
+  init() {
+    // initialize `name`
+  }
+
+  unphased set_name(name: str): void {
+    // ERROR: cannot mutate a preflight field from a phase-independent context
+    this.name = name;
+  }
+}
+```
+
+An unphased function can be passed to a function that expects a preflight function or an inflight function. In this way, we can say that an unphased functions are a superset of both preflight and inflight functions.
+
+However, a preflight or inflight function cannot be passed to a function that expects an unphased function.
+An exception to this rule is that if a function is unphased, then we can automatically assume any functions passed to it or returned by it have a matching phase.
+
+You can imagine that when a function is unphased, then "preflight" and "inflight" versions of it are generated at compile-time, and unphased-function types in parameters or return types are automatically converted to the appropriate phase.
+
+For example, `Array<T>.map` is modeled like the following pseudocode:
+
+```js
+native class Array<T> {
+  unphased map<U>(f: unphased (T) => U): Array<U> {
+    // ...
+  }
+}
+```
+
+At compile-time, since the function is unphased, preflight and inflight versions are generated:
+
+```js
+native class Array<T> {
+  preflight map<U>(f: preflight (T) => U): Array<U> {
+    // ...
+  }
+  inflight map<U>(f: inflight (T) => U): Array<U> {
+    // ...
+  }
+}
+```
+
+Notice how "f" is automatically converted to the appropriate phase. This is possible because the function is unphased.
+This way, when you call `Array<T>.map` with in preflight, it's possible to pass a preflight function to it, and when you call it in inflight, it's possible to pass an inflight function to it. (If you're calling `Array<T>.map` within another unphased function, then the unphased version of `Array<T>.map` is used.)
+
+[`▲ top`][top]
+
 ---
 
 ### 1.4 Storage Modifiers