Compare revisions

…

Strategy Pattern

Body changes between the two selected stored revisions. Code is not executed.

53 changed sections

− Removed+ Added153 unchanged content blocks omitted.

Content blocks 8 → 8

The text is unchanged, but footnotes, formatting or block attributes have changed.

Content blocks 10 → none

~~Why would we need the Strategy pattern?~~

(No content)

Content blocks 21 → none

~~We can initially handle the formats with a conditional.~~

(No content)

Content blocks 28 → none

~~We can separate the part that varies.~~

(No content)

Content blocks 34 → none

~~That is the reason to use Strategy here.~~

(No content)

Content blocks 42-43 → 38

~~Let us use~~ diagnostic output as ~~the~~ ~~example. The~~ pattern's ~~terms map to it~~ as follows.

The diagnostic-output example maps to the pattern's roles as follows.

Content blocks 46-47 → 41

As selection grows, it can ~~be collected~~ in a factory ~~or resolver~~. ~~For the two formats in Appendix A~~, a ~~small~~ factory ~~is enough. Choose between StrategyFactory, StrategyResolver, and StrategyRegistry according~~ to ~~the~~ ~~size~~ of ~~the~~ ~~selection~~ ~~rules~~ and ~~how implementations are managed. A factory~~ creates the ~~required implementation; a resolver finds one that matches the conditions. A registry holds registered implementations. With only two formats to choose from~~ ~~here~~, a ~~small~~ ~~factory~~ ~~will~~ do.

If format selection grows, it can go in a factory. Here, a factory takes a name such as human or json and creates the corresponding formatter, as shown in Appendix A.

Content blocks 51 → 45

Start with a valid, single-line diagnostic and concentrate on replacing the formatter. The three C# blocks in this section form one program when combined in order. Appendix A adds input validation~~, multiline-message handling, and checks for invalid formatter output~~.

Start with a valid, single-line diagnostic and concentrate on replacing the formatter. The three C# blocks in this section form one program when combined in order. Appendix A adds input validation.

Content blocks 56-57 → 50

Human-readable text and JSON are the two implementations ~~that fill that place~~. They receive the same diagnostic and each supplies its own string-building rules.

Human-readable text and JSON are the two implementations. They receive the same diagnostic and each supplies its own string-building rules.

Content blocks 63 → none

~~Relaxing the valid-input assumption also shows where the code starts to grow. Appendix A adds input and output contracts and format selection; Appendix C adds executable tests for those promises.~~

(No content)

Content blocks 68 → 60

The text is unchanged, but footnotes, formatting or block attributes have changed.

Content blocks 70 → 62

~~Exposing SetStrategy() when~~ runtime replacement is unnecessary ~~means tracking when other code~~ ~~sharing~~ the ~~object~~ ~~might~~ ~~change~~ ~~its~~ ~~strategy~~. An editor that ~~genuinely~~ needs replacement ~~can have a setter or another selection mechanism,~~ ~~but~~ ~~first~~ ~~define~~ ~~what~~ ~~replacement~~ ~~means~~ ~~for~~ ~~work~~ in ~~progress~~. readonly prevents reference reassignment; ~~whether~~ the strategy object's internal state ~~can change depends on its implementation~~.

When runtime replacement is unnecessary, keep the strategy supplied through the constructor. An editor that needs replacement should define when a strategy may change during a running operation. readonly prevents reference reassignment, not changes to the strategy object's internal state.

Content blocks 79 → 71

The object's formatter.Format(diagnostic) has become format(diagnostic). This is shorter when there is no per-instance configuration or resource to hold. Appendix B ~~extends~~ it ~~with Render and RenderAll for passing an existing object's method or converting~~ several diagnostics together.

The object's formatter.Format(diagnostic) has become format(diagnostic). This is shorter when there is no per-instance configuration or resource to hold. Appendix B applies it to several diagnostics together.

Content blocks 81 → none

The text is unchanged, but footnotes, formatting or block attributes have changed.

Content blocks 86 → 77

The two functions return the same elements in different orders, and the caller sorts ~~according to~~ the function it receives. To compare IDs when prices tie~~, continue with ThenBy~~; ~~calling~~ another OrderBy establishes a new primary sort key.~~[Footnote~~ 4] Appendix B extends the example ~~with OrderBy's deferred execution and stable ordering, when to materialize the input as an array, a closure that remembers a priority product, and a query-syntax variant~~.[Footnote 5]

The two functions return the same elements in different orders, and the caller sorts with the function it receives. Use ThenBy to compare IDs when prices tie; another OrderBy establishes a new primary sort key. Appendix B extends the example.[Footnote 4]

Content blocks 88 → 79

TypeScript can receive a comparison rule in ~~much~~ the same way. This version assumes valid safe-integer prices and IDs ~~and shows only~~ ~~copying~~ the input array and ~~sorting~~ it. Appendix B ~~includes~~ input validation ~~and the execution-environment requirements~~.

TypeScript can receive a comparison rule in the same way. This version assumes valid safe-integer prices and IDs, copies the input array, and sorts it. Appendix B adds input validation.

Content blocks 94 → none

~~A correctly formatted string alone does not tell us whether that formatter suits the program's request.~~

(No content)

Content blocks 98 → 88

Appendix C ~~injects failures and checks the exact exception types. The minimal examples introduce the replacement relationship first; the~~ ~~extended~~ ~~implementation~~ ~~checks~~ the ~~conditions in~~ ~~this~~ ~~table~~ ~~individually~~.

Appendix C contains executable tests for the implementations and their selection.

Content blocks 116 → 106

Strategy fits choosing one alternative for a role. If ~~three~~ discount rules must all ~~run in sequence~~, ~~their order and conflict rules need defining. If~~ ~~validation~~ ~~should~~ ~~collect~~ ~~every~~ ~~error,~~ ~~define~~ ~~when~~ to ~~stop~~ and ~~how to aggregate errors. Those rules belong in the code~~ ~~that~~ ~~combines~~ ~~the~~ ~~policies~~.

Strategy fits choosing one alternative for a role. When several discount rules must all apply, the code combining them also needs rules for their order and whether they can be stacked.

Content blocks 127-128 → 117

When these requirements coexist, an executor ~~might~~ take a scheduled request, select a channel strategy, and let that strategy use an adapter for the external SDK. Supporting storage and re-execution also requires rules for request serialization, permissions, duplicate execution, and failures in the actual job-execution contract. Storing a request as a Command does not define cancellation by itself. Design the information and actions needed to undo it separately.

When these requirements coexist, an executor can take a scheduled request, select a channel strategy, and let that strategy use an adapter for the external SDK.

Content blocks 131-132 → 120

A ~~contract can be justified even with one implementation~~ in ~~the~~ ~~repository~~ if it is a ~~library~~ ~~extension~~ ~~point~~ ~~for~~ ~~user~~-~~supplied algorithms~~ or ~~meets~~ a ~~confirmed deployment-specific~~ replacement requirement. ~~Creating~~ only DefaultStrategy ~~without such a need~~ may add declarations and assembly code ~~while leaving the behavior unchanged~~. ~~Look at the actual use as well as~~ ~~the~~ ~~implementation~~ ~~count. It~~ ~~helps~~ to ~~prioritize performance where it matters and readability in higher-level application code~~.

A library that accepts user-supplied algorithms can justify a contract even with one built-in implementation. Without a replacement requirement, adding only DefaultStrategy may just add declarations and assembly code. Start with what actually needs to vary.

Content blocks 135 → 123

The text is unchanged, but footnotes, formatting or block attributes have changed.

Content blocks 138 → 126

This extends the ~~minimal~~ object example ~~by removing the~~ ~~valid-~~input ~~assumption and adding~~ validation, output contracts, and format selection. It reuses the ~~minimal example's~~ type names, so ~~do not combine~~ ~~the~~ ~~two~~ ~~versions~~ in ~~one~~ ~~file~~. ~~Instead, collect~~ the C# blocks ~~from~~ ~~this~~ ~~appendix~~ through ~~Appendix~~ C in order to form one program.

This extends the object example with input validation, output contracts, and format selection. It reuses the same type names, so keep it separate from the minimal version. Combine the C# blocks in Appendices A through C in order to form one program.

Content blocks 140 → 128

~~The following~~ method selects the format and builds its string in one place~~. After separating the strategy, Report(diagnostic, output) still records the diagnostic. Combining the C# blocks in Appendices A through C in one file also includes the final tests~~.

This method selects the format and builds its string in one place.

Content blocks 144 → 132

The example ~~targets~~ .NET 8 ~~(net8.0)~~ and C# 12 ~~(LangVersion=12.0)~~ with nullable analysis enabled ~~(Nullable=enable)~~ and no external packages. ~~C# 12 matches the default language version for a .NET 8 project. The extended implementation has also been built and run with LangVersion=9.0.~~[Footnote 10] ~~The verification record lists the verification date, reference commit, tool versions, and results.~~

The example uses .NET 8 and C# 12 with nullable analysis enabled and no external packages.[Footnote 9]

Content blocks 146 → none

~~The single-line contract here means no actual CR or LF. Appendix E covers other Unicode separators, control characters, and the limits of whitespace validation.~~

(No content)

Content blocks 149 → 136

~~Failure behavior is part of the contract.~~ Invalid arguments ~~use~~ argument-related exceptions; a formatter's output-contract violation ~~is reported as~~ InvalidOperationException. An ~~IOException from the~~ output device ~~reaches the caller instead of being hidden or converted into a success string. A buffered writer may fail later at Flush(), after the write call. Flushing and~~ ~~disposal~~ ~~belong~~ to the ~~writer's owner~~.~~[Footnote 11]~~

Invalid arguments raise argument-related exceptions; a formatter's output-contract violation raises InvalidOperationException. An output device's IOException also reaches the caller.

Content blocks 153-156 → 140

~~By default,~~ System.Text.Json ~~emits compact~~ JSON ~~without indentation,~~ with message line breaks escaped inside strings.~~[Footnote~~ ~~12]~~ schemaVersion and the field names ~~are~~ this example's own schema. Connecting to a particular compiler or LSP requires implementing the schema that consumer expects. The default encoder also escapes non-ASCII characters and HTML-sensitive characters such as <, >, &, and '. The Hangul test string 한글 therefore appears as \uD55C\uAE00 in the JSON text. With the .NET 8 defaults used here, a double quote inside a string also appears as \u0022. Parsing the JSON restores the original Hangul and quotes, so check the visible representation separately from preservation of the value.[Footnote 12] The tests below check both. This example keeps the default settings. Changing the encoder to display Hangul directly does not make every character pass through unchanged: block lists can override allowed ranges. UnsafeRelaxedJsonEscaping also relaxes protections needed when embedding text in HTML, so it should not be treated as a readability-only setting. The human-readable format ~~is for display: an original literal \n and an actual LF both appear as \n~~. Consumers that need to recover the message or read individual fields should use JSON. The current implementation does not separately reject malformed UTF-16, so unpaired surrogates may become replacement characters during serialization. Appendix E checks this limit on recovery.[Footnote 13] This call uses reflection-based serialization. It caches type metadata collected on first use and reuses it on later calls. Measure startup time, memory, and throughput before choosing source generation. A Native AOT deployment needs a reflection-independent serialization path and deployment settings, using named output types and facilities such as JsonSerializerContext.[Footnote 14]

System.Text.Json produces JSON with message line breaks escaped inside strings. schemaVersion and the field names belong to this example's format.[Footnote 10]

Content blocks 160 → 144

The reporter's ~~runtime~~ checks only ~~reject~~ empty strings and CR/LF. ~~Implementation tests~~ ~~and~~ ~~review~~ check ~~JSON~~ ~~schemas,~~ format-specific meaning~~, and side effects. Concurrent use of TextWriter and atomic disk writes belong to the output boundary; a program with several tasks sharing an output needs a synchronization policy there~~.

The reporter checks only for empty strings and actual CR/LF. Each formatter's tests check its fields and format-specific meaning.

Content blocks 165 → none

The argument parser can default to human when --format is omitted. Treating the invalid explicit value --format jsno as human would conceal an error in the user's request. Let the parser define omission and the selection boundary check whether a supplied name is supported.

(No content)

Content blocks 167 → none

~~<a id="extended-functions"></a>~~

(No content)

Content blocks 173 → 155

An existing formatter can supply its method as a function value. A small rule without separate settings or resource lifetime can start as a ~~pure~~ function. In either case, ToArray() completes the calculation inside this call, so an exception while processing an element fails the call. Returning a deferred IEnumerable<string> instead moves that failure to the point of enumeration.

An existing formatter can supply its method as a function value. A small rule without separate settings or resource lifetime can start as a function.

Content blocks 178 → 160

CheapestFirstQuery expresses the same rule with from, orderby, and select. ~~The~~ C# compiler translates ~~query syntax into the corresponding~~ ~~method~~ calls, ~~which in this case~~ ~~mean~~ .OrderBy(...).ThenBy(...)~~.[Footnote 15] Choose the~~ ~~clearer~~ of the ~~two notations for the~~ ~~same~~ ~~sorting~~ ~~strategy~~.

CheapestFirstQuery expresses the same rule with from, orderby, and select. Here the compiler translates it to calls corresponding to .OrderBy(...).ThenBy(...), so choose the notation you find clearer.[Footnote 11]

Content blocks 180-181 → 162

~~Use OrderBy(...).ThenBy(...) to add ID order for equal prices. In OrderBy(...).OrderBy(...), the latter call establishes a new primary key.[Footnote 4]~~ Enumerable.OrderBy uses deferred execution ~~and gathers elements when sorting is required~~. ~~The~~ Sort ~~above~~ materializes ~~both~~ input and result with ToArray(), ~~so it finishes~~ the ~~calculation~~ inside the call and ~~returns a~~ ~~sorted~~ array.[Footnote 5] Enumerable.OrderBy is stable, so sorting by price alone preserves input order among equal-priced products. Comparing IDs as well defines the order by price and ID instead of depending on that input order. Items whose two keys both tie still retain their input order.[Footnote 5]

Enumerable.OrderBy uses deferred execution. This Sort materializes its input and result with ToArray(), completing the sort inside the call and returning an array.[Footnote 13]

Content blocks 183 → none

These examples use LINQ to Objects in memory. With EF Core's IQueryable<T>, a provider interprets expression trees as SQL or another execution form, so server-side filtering, sorting, and pagination need queries that provider can translate.[Footnote 15] Passing a database query to this Sort instead makes its internal ToArray() retrieve the entire input and sort it in memory.

(No content)

Content blocks 187 → none

The readonly Product[] syntax was introduced in TypeScript 3.4. The runtime needs ES2015's Number.isSafeInteger.[Footnote 18][Footnote 19] The verification record lists the actual package and Node.js versions and commands. Execution with the TypeScript 3.4 compiler and older browsers has not been verified. target affects emitted syntax and the default lib selection; lib defines the API types known to the compiler, so an unsupported declaration set can fail compilation. Conversely, adding ES2015 to lib can satisfy type checking without supplying the runtime API implementation. Older environments still need API support or a polyfill.[Footnote 18]

(No content)

Content blocks 189 → 168

The flow still copies the product array and calls sort. ~~The~~ comparison function chooses cheaper or more expensive products first. ~~The~~ ~~replaceable~~ rule ~~here~~ is the ~~ordering comparison; Java's Comparator is also an official API for supplying comparison rules to sorting and other~~ ~~methods~~.~~[Footnote 20]~~

The flow still copies the product array and calls sort, while the comparison function chooses cheaper or more expensive products first. That comparison rule is the replaceable strategy.

Content blocks 191 → none

~~<a id="extended-tests"></a>~~

(No content)

Content blocks 193 → 171

Add this ~~small test program~~ to the same file as the C# ~~code~~ in Appendices A and B. ~~It uses StringWriter rather~~ ~~than~~ a ~~file~~ or ~~terminal.~~ ~~The~~ ~~failing~~ ~~writer~~ ~~checks~~ ~~only~~ ~~that~~ an ~~I/O~~ ~~failure~~ ~~reaches~~ ~~the~~ ~~caller~~.

Add this code to the same file as the C# blocks in Appendices A and B to run 38 checks. It uses StringWriter to check format selection, output, and invalid input without creating files.

Content blocks 195-199 → 173

The tests append output.NewLine instead of hard-coding "\n" because StringWriter defaults to "\r\n" on Windows and "\n" on Linux and macOS, and the caller can change it.[Footnote 21] The supplemental tests set each value explicitly to check that the reporter follows the writer's setting. Expect<TException> checks the exact exception type here. A test expecting ArgumentException does not accept ArgumentNullException. The supplemental tests deliberately pass a derived exception to the document's test helper to check this distinction. The JSON tests inspect field values after parsing and the default encoder's escapes, without turning the entire runtime-dependent block list into a separate wire contract. Combining only the C# blocks in Appendices A through C runs the 38 checks in Program.Main(). Use node WIKI/assets/strategy-pattern/verify.mjs --document-only to reproduce that path in the source repository. Running the example verifier with node WIKI/assets/strategy-pattern/verify.mjs from the repository root also checks Appendix E, supplemental cases, C# 9 compatibility, the standalone minimal examples, and TypeScript. The text blocks are call-flow diagrams rather than executable code; the verifier also checks code fences, languages, and footnote anchors. The verification record distinguishes the scope and results of each execution mode. You need a .NET SDK and runtime capable of building and running .NET 8, Node.js, and the TypeScript CLI. The supplemental C# tests use a primary constructor, so their default verification stays on C# 12; a separate project checks the extended example's C# 9 syntax compatibility. The script defaults to %APPDATA%/npm/node_modules/typescript/bin/tsc rather than searching every global npm installation location. If you changed the npm prefix or use another operating system, pass your TypeScript package's bin/tsc path after the script. The TypeScript checks cover sorting, preservation of the input array, rejection of invalid prices and IDs, and the distinction between lib declarations and runtime API implementations. Appendix D. ~~State, lifetime, and output~~ ~~boundaries~~

Appendix D. Implementation considerations